add get-pipx script

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## dev
 
+- Add get-pipx.py script
+
 ## 1.1.0
 
 - Fix encoding issue on Windows when pip fails to install a package

README.md

@@ -22,43 +22,58 @@
 
 **Source Code**: https://github.com/pypa/pipx
 
-_For comparison to other tools including pipsi, see [Comparison to Other Tools](https://pypa.github.io/pipx/comparisons/)._
+_For comparison to other tools, see [Comparison to Other Tools](https://pypa.github.io/pipx/comparisons/)._
 
 ## Install pipx
 
-### On macOS
+There are several ways to install pipx. Below are the most common. For other installation methods, see [installation](https://pypa.github.io/pipx/installation/).
+
+### Linux, macOS
+
+The `get-pipx.py` installation script installs pipx with pipx itself.
+
+After it's finished, you can upgrade pipx with `pipx upgrade pipx`. To uninstall, you can run `pipx uninstall pipx`.
 
 ```
-brew install pipx
-pipx ensurepath
+curl https://raw.githubusercontent.com/pypa/pipx/main/get-pipx.py | python3
 ```
 
-Upgrade pipx with `brew update && brew upgrade pipx`.
+If python3 is not found on your PATH or there is a syntax error/typo, `curl` will fail with the error message: "(23) Failed writing body."
 
-### On Linux, install via pip (requires pip 19.0 or later)
+To pass arguments to the `get-pipx.py` script:
 
 ```
-python3 -m pip install --user pipx
-python3 -m pipx ensurepath
+curl https://raw.githubusercontent.com/pypa/pipx/main/get-pipx.py | python3 - ARGS
 ```
 
-Upgrade pipx with `python3 -m pip install --user -U pipx`.
+For example, you can see options with
+
+```
+curl https://raw.githubusercontent.com/pypa/pipx/main/get-pipx.py | python3 - --help
+```
 
-### On Windows, install via pip (requires pip 19.0 or later)
+The default binary location is ~/.local/bin. This can be overridden with the environment variable PIPX_BIN_DIR.
+
+pipx's default virtual environment location is ~/.local/pipx. This can be overridden with the environment variable PIPX_HOME.
+
+### Windows
+
+Install via pip (requires pip 19.0 or later)
 
 ```
 # If you installed python using the app-store, replace `python` with `python3` in the next line.
 python -m pip install --user pipx
 ```
 
-It is possible (even most likely) the above finishes with a WARNING looking similar to this:
+It is possible the above finishes with a warning such as:
 
 ```
 WARNING: The script pipx.exe is installed in `<USER folder>\AppData\Roaming\Python\Python3x\Scripts` which is not on PATH
 ```
 
 If so, go to the mentioned folder, allowing you to run the pipx executable directly.
-Enter the following line (even if you did not get the warning):
+
+Enter the following line :
 
 ```
 pipx ensurepath
@@ -67,8 +82,6 @@ pipx ensurepath
 This will add both the above mentioned path and the `%USERPROFILE%\.local\bin` folder to your search path.
 Restart your terminal session and verify `pipx` does run.
 
-Upgrade pipx with `python3 -m pip install --user -U pipx`.
-
 ### Shell completions
 
 Shell completions are available by following the instructions printed with this command:
@@ -77,8 +90,6 @@ Shell completions are available by following the instructions printed with this
 pipx completions
 ```
 
-For more details, see the [installation instructions](https://pypa.github.io/pipx/installation/).
-
 ## Overview: What is `pipx`?
 
 pipx is a tool to help you install and run end-user applications written in Python. It's roughly similar to macOS's `brew`, JavaScript's [npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b), and Linux's `apt`.
@@ -124,22 +135,22 @@ This automatically creates a virtual environment, installs the package, and adds
 Example:
 
 ```
->> pipx install pycowsay
+> pipx install pycowsay
   installed package pycowsay 2.0.3, Python 3.7.3
   These apps are now globally available
     - pycowsay
 done! ✨ 🌟 ✨
 
 
->> pipx list
+> pipx list
 venvs are in /home/user/.local/pipx/venvs
 apps are exposed on your $PATH at /home/user/.local/bin
    package pycowsay 2.0.3, Python 3.7.3
     - pycowsay
 
 
 # Now you can run pycowsay from anywhere
->> pycowsay mooo
+> pycowsay mooo
   ____
 < mooo >
   ====

docs/installation.md

@@ -2,26 +2,101 @@
 
 python 3.7+ is required to install pipx. pipx can run binaries from packages with Python 3.3+. Don't have Python 3.7 or later? See [Python 3 Installation & Setup Guide](https://realpython.com/installing-python/).
 
-You also need to have `pip` installed on your machine for `python3`. Installing it varies from system to system. Consult [pip's installation instructions](https://pip.pypa.io/en/stable/installing/). Installing on Linux works best with a [Linux Package Manager](https://packaging.python.org/guides/installing-using-linux-tools/#installing-pip-setuptools-wheel-with-linux-package-managers).
+You also need to have `pip` and `venv` installed on your machine for `python3`. Installing pip varies from system to system. Consult [pip's installation instructions](https://pip.pypa.io/en/stable/installing/). Installing on Linux works best with a [Linux Package Manager](https://packaging.python.org/guides/installing-using-linux-tools/#installing-pip-setuptools-wheel-with-linux-package-managers).
 
-pipx works on macOS, linux, and Windows.
+pipx works on macOS, Linux, and Windows.
 
 ## Install pipx
 
-On macOS:
+### pipx installer for Linux, macOS, Windows (recommended)
+
+This method installs pipxin a temporary environment, then installs pipx _with pipx_. That's right, pipx is a command line tool, so installing it with itself isolates its dependencies just like any other python tool.
+
+After it's finished, you can upgrade pipx with `pipx upgrade pipx`. To uninstall, you can run `pipx uninstall pipx`.
+
+```
+curl https://raw.githubusercontent.com/pypa/pipx/main/get-pipx.py | python3
+```
+
+You can replace `python3` with whichever python binary you want to install pipx with.
+
+If python3 is not found on your PATH or there is a syntax error/typo, `curl` will fail with the error message: "(23) Failed writing body."
+
+To pass arguments to the `get-pipx.py` script:
+
+```
+curl https://raw.githubusercontent.com/pypa/pipx/main/get-pipx.py | python3 - ARGS
+```
+
+For example, you can see options with
+
+```
+> curl https://raw.githubusercontent.com/pypa/pipx/main/get-pipx.py | python3 - --help
+usage: get-pipx.py [-h] [--spec SPEC] [--no-modify-path] [--force]
+                   [--python PYTHON] [--verbose]
+
+Installer script to install pipx. After installing, pipx will be available for
+use. pipx will be by itself, so you can run `pipx upgrade pipx` or `pipx
+uninstall pipx`. Environment variables PIPX_BIN_DIR and PIPX_HOME can be used.
+
+optional arguments:
+  -h, --help        show this help message and exit
+  --spec SPEC       The package specification of pipx to install. This value
+                    is passed to "pip install <value>". For example, to
+                    install from the github repository use
+                    `git+https://github.com/pypa/pipx.git`. Default: pipx
+  --no-modify-path  Don't configure the PATH environment variable
+  --force           reinstall pipx even if existing installation was found
+  --python PYTHON   The Python binary to associate pipx with. Must be v3.7+.
+  --verbose         Display more detailed output
+```
+
+### macOS
 
 ```
 brew install pipx
 pipx ensurepath
 ```
 
-Otherwise, install via pip (requires pip 19.0 or later):
+### Linux, macOS
+
+Install via pip (requires pip 19.0 or later):
 
 ```
 python3 -m pip install --user pipx
 python3 -m pipx ensurepath
 ```
 
+Linux distros also include pipx in their package managers. For example, you may be able to install with apt:
+
+```
+sudo apt install pipx
+```
+
+### Windows
+
+Install via pip (requires pip 19.0 or later):
+
+```
+python -m pip install --user pipx
+```
+
+If you installed python using the app-store, replace `python` with `python3` .
+
+If you get the following warning
+
+```
+WARNING: The script pipx.exe is installed in `<USER folder>\AppData\Roaming\Python\Python3x\Scripts` which is not on PATH
+```
+
+go to the mentioned folder, allowing you to run the pipx executable directly. Enter the following line (even if you did not get the warning):
+
+```
+pipx ensurepath
+```
+
+This will add both the above mentioned path and the %USERPROFILE%.local\bin folder to your search path. Restart your terminal session and verify pipx runs.
+
 ### Installation Options
 
 The default binary location for pipx-installed apps is `~/.local/bin`. This can be overridden with the environment variable `PIPX_BIN_DIR`.
@@ -37,18 +112,32 @@ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install PACKAGE
 
 ## Upgrade pipx
 
-On macOS:
+Upgrade commands vary based on how pipx was installed on your system.
+
+With `get-pipx.py` (an installation of pipx managed by itself):
+
+```
+pipx upgrade pipx
+```
+
+With brew:
 
 ```
 brew update && brew upgrade pipx
 ```
 
-Otherwise, upgrade via pip:
+With pip:
 
 ```
 python3 -m pip install --user -U pipx
 ```
 
+With apt:
+
+```
+sudo apt upgrade pipx
+```
+
 ### Note: Upgrading pipx from a pre-0.15.0.0 version to 0.15.0.0 or later
 
 After upgrading to pipx 0.15.0.0 or above from a pre-0.15.0.0 version, you must re-install all packages to take advantage of the new persistent pipx metadata files introduced in the 0.15.0.0 release. These metadata files store pip specification values, injected packages, any custom pip arguments, and more in each main package's venv.