remove existing files in PIPX_BIN_DIR if --force is passed (#206)

* remove existing files in PIPX_BIN_DIR if --force is passed

* add force arg for other commands

* animation improvements; lint fixes

* update docs

Author: Chad Smith

README.md

@@ -21,7 +21,7 @@ See Contributing for how to update this file.
 <a href="https://travis-ci.org/pipxproject/pipx"><img src="https://travis-ci.org/pipxproject/pipx.svg?branch=master" /></a>
 
 <a href="https://pypi.python.org/pypi/pipx/">
-<img src="https://img.shields.io/badge/pypi-0.14.0.0rc0-blue.svg" /></a>
+<img src="https://img.shields.io/badge/pypi-0.14.0.0rc1-blue.svg" /></a>
 <a href="https://github.com/ambv/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
 </p>
 
@@ -38,20 +38,25 @@ python3 -m pip install --user pipx
 python3 -m pipx ensurepath
 ```
 
-For more details, [installation](installation).
+Upgrade pipx with `python3 -m pip install -U pipx`.
 
-To add shell completions, see instructions with
+Shell completions are available by following the instructions printed with this command:
 ```
 pipx completions
 ```
 
+For more details, see the [installation instructions](https://pipxproject.github.io/pipx/installation/).
+
+
 ## Overview: What is `pipx`?
 
-pipx is a tool to help you install and run end-user applications written in Python. pipx **is not** a tool for development or publishing of your code. It's kind of like macOS's `brew` (if you are familiar with that), but for Python applications.
+pipx is a tool to help you install and run end-user applications written in Python. pipx **is not** a tool for development or publishing of your code -- it's only for consuming already published packages.
+
+If you are familiar macOS's `brew`, it's kind of like that but for Python applications. If you are familiar with JavaScript's [npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b), it's kind of like that but also allows you to install packages. If you are familiar with `pip`, it's kind of like that but is only focused on installing packages that have entry points.
 
-Python and PyPI allow developers to distribute code with "console script entry points". These scripts let users call into Python code from the command line, effectively acting like standalone applications.
+pipx does not ship with pip, but installing it is often an important part of bootstrapping your system.
 
-`pipx` is a tool to install and run any of the thousands of Python applications available on PyPI in a safe, convenient, and reliable way. **In a way, it turns Python Package Index (PyPI) into a big app store for Python applications.** Not all Python packages have entry points, but many do.
+Python and PyPI allow developers to distribute code with "console script entry points". These scripts let users call into Python code from the command line, effectively acting like standalone applications. `pipx` is a tool to install and run any of these thousands of Python applications available on PyPI in a safe, convenient, and reliable way. **In a way, it turns Python Package Index (PyPI) into a big app store for Python applications.** Not all Python packages have entry points, but many do. `pipx` is **not** a tool to install a library and `import` it in your Python code.
 
 `pipx` enables you to:
 
@@ -61,9 +66,8 @@ Python and PyPI allow developers to distribute code with "console script entry p
 
 Best of all, pipx runs with regular user permissions, never calling `sudo pip install` (you aren't doing that, are you? 😄).
 
-pipx is similar to JavaScript's [npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) - which ships with npm, but also allows you to install instead of just run. pipx does not ship with pip but installing it is often an important part of bootstrapping your system.
 
-### Safely installing to isolated environments
+### Walkthrough: Installing a Package and its Applications With `pipx`
 
 You can globally install an application by running
 
@@ -90,6 +94,7 @@ apps are exposed on your $PATH at /home/user/.local/bin
     - pycowsay
 
 
+# Now you can run pycowsay from anywhere
 >> pycowsay mooo
   ____
 < mooo >
@@ -102,12 +107,17 @@ apps are exposed on your $PATH at /home/user/.local/bin
                 ||----w |
                 ||     ||
 
-
 ```
 
-### Running in temporary, sandboxed environments
+### Walkthrough: Running an Application in a Temporary, Sandboxed Environment
+
+I find this handy when I occasionally run an app and want to use the latest version of it, but don't necessarily need it installed on my computer. You may want to do this when you are initializing a new project and want to set up the right directory structure, when you want to view the help text of an application, or if you simply want to run an app in a one-off case.
 
-pipx makes running the latest version of a program in a temporary environment as easy as
+For example, the blog post [How to set up a perfect Python project](https://sourcery.ai/blog/python-best-practices/) uses `pipx run` to kickstart a new project with[cookiecutter](https://github.com/cookiecutter/cookiecutter).
+
+A nice side benefit is that you don't have to remember to upgrade the app it since `pipx run` will automatically run a recent version for you.
+
+Okay, let's see what this looks like in practice!
 
 ```
 pipx run APP [ARGS...]
@@ -121,9 +131,7 @@ pipx run pycowsay moo
 
 Notice that you **don't need to execute any install commands to run the app**.
 
-Re-running the same app is quick because pipx caches Virtual Environments on a per-app basis. These caches last two days.
-
-I find this handy when I want to quickly see the help text of an application, or when I occasionally run an app but don't necessarily want it hanging around on my system. A nice side benefit is that you don't have to remember to upgrade it since `pipx run` will automatically run a recent version for you.
+Re-running the same app is quick because pipx caches Virtual Environments on a per-app basis. The caches only last a few days, and when they expire, pipx will again use the latest version of the package. This way you can be sure you're always running a new version of the package without having to manually upgrade.
 
 You can run .py files directly, too.
 
@@ -167,4 +175,6 @@ Contributors
 - [Paul Moore](https://github.com/pfmoore)
 - [tkossak](https://github.com/tkossak)
 - [Tzu-ping Chung](https://github.com/uranusjr)
-- [Shawn Hensley](https://github.com/sahensley)
+- [Shawn Hensley](https://github.com/sahensley)
+
+Logo by [@IrishMorales](https://github.com/IrishMorales).

docs/changelog.md

@@ -4,6 +4,8 @@
 - Breaking change: for the `inject` command, change `--include-binaries` to `--include-apps`
 - Change all terminology from `binary` to `app` or `application`
 - Improve argument parsing for `pipx run` and `pipx runpip`
+- If `--force` is passed, remove existing files in PIPX_BIN_DIR
+- Move animation to start of line, hide cursor when animating
 
 0.13.2.3
 

docs/docs.md

@@ -100,8 +100,8 @@ optional arguments:
                         git+https://github.com/user/repo.git@branch`
   --include-deps        Include apps of dependent packages
   --verbose
-  --force               Install even when the package has already been
-                        installed
+  --force, -f           Modify existing virtual environment and files in
+                        PIPX_BIN_DIR
   --python PYTHON       The Python executable used to create the Virtual
                         Environment and run the associated app/apps. Must be
                         v3.3+.
@@ -169,7 +169,7 @@ optional arguments:
 
 ```
 pipx upgrade --help
-usage: pipx upgrade [-h] [--spec SPEC] [--include-deps]
+usage: pipx upgrade [-h] [--spec SPEC] [--force] [--include-deps]
                     [--system-site-packages] [--index-url INDEX_URL]
                     [--editable] [--pip-args PIP_ARGS] [--verbose]
                     package
@@ -186,6 +186,8 @@ optional arguments:
                         passed to pip. Runs `pip install -U SPEC`. For example
                         `--spec mypackage==2.0.0` or `--spec
                         git+https://github.com/user/repo.git@branch`
+  --force, -f           Modify existing virtual environment and files in
+                        PIPX_BIN_DIR
   --include-deps        Include apps of dependent packages
   --system-site-packages
                         Give the virtual environment access to the system
@@ -207,7 +209,7 @@ pipx upgrade-all --help
 usage: pipx upgrade-all [-h] [--include-deps] [--system-site-packages]
                         [--index-url INDEX_URL] [--editable]
                         [--pip-args PIP_ARGS] [--skip SKIP [SKIP ...]]
-                        [--verbose]
+                        [--force] [--verbose]
 
 Upgrades all packages within their virtual environments by running 'pip
 install --upgrade PACKAGE'
@@ -225,6 +227,8 @@ optional arguments:
                         install/upgrade commands
   --skip SKIP [SKIP ...]
                         skip these packages
+  --force, -f           Modify existing virtual environment and files in
+                        PIPX_BIN_DIR
   --verbose
 
 ```
@@ -236,7 +240,7 @@ optional arguments:
 pipx inject --help
 usage: pipx inject [-h] [--include-apps] [--include-deps]
                    [--system-site-packages] [--index-url INDEX_URL]
-                   [--editable] [--pip-args PIP_ARGS] [--verbose]
+                   [--editable] [--pip-args PIP_ARGS] [--force] [--verbose]
                    package dependencies [dependencies ...]
 
 Installs packages to an existing pipx-managed virtual environment.
@@ -258,6 +262,8 @@ optional arguments:
   --editable, -e        Install a project in editable mode
   --pip-args PIP_ARGS   Arbitrary pip arguments to pass directly to pip
                         install/upgrade commands
+  --force, -f           Modify existing virtual environment and files in
+                        PIPX_BIN_DIR
   --verbose
 
 ```

docs/index.md

@@ -21,7 +21,7 @@ See Contributing for how to update this file.
 <a href="https://travis-ci.org/pipxproject/pipx"><img src="https://travis-ci.org/pipxproject/pipx.svg?branch=master" /></a>
 
 <a href="https://pypi.python.org/pypi/pipx/">
-<img src="https://img.shields.io/badge/pypi-0.14.0.0rc0-blue.svg" /></a>
+<img src="https://img.shields.io/badge/pypi-0.14.0.0rc1-blue.svg" /></a>
 <a href="https://github.com/ambv/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
 </p>
 
@@ -38,20 +38,25 @@ python3 -m pip install --user pipx
 python3 -m pipx ensurepath
 ```
 
-For more details, [installation](installation).
+Upgrade pipx with `python3 -m pip install -U pipx`.
 
-To add shell completions, see instructions with
+Shell completions are available by following the instructions printed with this command:
 ```
 pipx completions
 ```
 
+For more details, see the [installation instructions](https://pipxproject.github.io/pipx/installation/).
+
+
 ## Overview: What is `pipx`?
 
-pipx is a tool to help you install and run end-user applications written in Python. pipx **is not** a tool for development or publishing of your code. It's kind of like macOS's `brew` (if you are familiar with that), but for Python applications.
+pipx is a tool to help you install and run end-user applications written in Python. pipx **is not** a tool for development or publishing of your code -- it's only for consuming already published packages.
+
+If you are familiar macOS's `brew`, it's kind of like that but for Python applications. If you are familiar with JavaScript's [npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b), it's kind of like that but also allows you to install packages. If you are familiar with `pip`, it's kind of like that but is only focused on installing packages that have entry points.
 
-Python and PyPI allow developers to distribute code with "console script entry points". These scripts let users call into Python code from the command line, effectively acting like standalone applications.
+pipx does not ship with pip, but installing it is often an important part of bootstrapping your system.
 
-`pipx` is a tool to install and run any of the thousands of Python applications available on PyPI in a safe, convenient, and reliable way. **In a way, it turns Python Package Index (PyPI) into a big app store for Python applications.** Not all Python packages have entry points, but many do.
+Python and PyPI allow developers to distribute code with "console script entry points". These scripts let users call into Python code from the command line, effectively acting like standalone applications. `pipx` is a tool to install and run any of these thousands of Python applications available on PyPI in a safe, convenient, and reliable way. **In a way, it turns Python Package Index (PyPI) into a big app store for Python applications.** Not all Python packages have entry points, but many do. `pipx` is **not** a tool to install a library and `import` it in your Python code.
 
 `pipx` enables you to:
 
@@ -61,9 +66,8 @@ Python and PyPI allow developers to distribute code with "console script entry p
 
 Best of all, pipx runs with regular user permissions, never calling `sudo pip install` (you aren't doing that, are you? 😄).
 
-pipx is similar to JavaScript's [npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) - which ships with npm, but also allows you to install instead of just run. pipx does not ship with pip but installing it is often an important part of bootstrapping your system.
 
-### Safely installing to isolated environments
+### Walkthrough: Installing a Package and its Applications With `pipx`
 
 You can globally install an application by running
 
@@ -90,6 +94,7 @@ apps are exposed on your $PATH at /home/user/.local/bin
     - pycowsay
 
 
+# Now you can run pycowsay from anywhere
 >> pycowsay mooo
   ____
 < mooo >
@@ -102,12 +107,17 @@ apps are exposed on your $PATH at /home/user/.local/bin
                 ||----w |
                 ||     ||
 
-
 ```
 
-### Running in temporary, sandboxed environments
+### Walkthrough: Running an Application in a Temporary, Sandboxed Environment
+
+I find this handy when I occasionally run an app and want to use the latest version of it, but don't necessarily need it installed on my computer. You may want to do this when you are initializing a new project and want to set up the right directory structure, when you want to view the help text of an application, or if you simply want to run an app in a one-off case.
 
-pipx makes running the latest version of a program in a temporary environment as easy as
+For example, the blog post [How to set up a perfect Python project](https://sourcery.ai/blog/python-best-practices/) uses `pipx run` to kickstart a new project with[cookiecutter](https://github.com/cookiecutter/cookiecutter).
+
+A nice side benefit is that you don't have to remember to upgrade the app it since `pipx run` will automatically run a recent version for you.
+
+Okay, let's see what this looks like in practice!
 
 ```
 pipx run APP [ARGS...]
@@ -121,9 +131,7 @@ pipx run pycowsay moo
 
 Notice that you **don't need to execute any install commands to run the app**.
 
-Re-running the same app is quick because pipx caches Virtual Environments on a per-app basis. These caches last two days.
-
-I find this handy when I want to quickly see the help text of an application, or when I occasionally run an app but don't necessarily want it hanging around on my system. A nice side benefit is that you don't have to remember to upgrade it since `pipx run` will automatically run a recent version for you.
+Re-running the same app is quick because pipx caches Virtual Environments on a per-app basis. The caches only last a few days, and when they expire, pipx will again use the latest version of the package. This way you can be sure you're always running a new version of the package without having to manually upgrade.
 
 You can run .py files directly, too.
 
@@ -167,4 +175,6 @@ Contributors
 - [Paul Moore](https://github.com/pfmoore)
 - [tkossak](https://github.com/tkossak)
 - [Tzu-ping Chung](https://github.com/uranusjr)
-- [Shawn Hensley](https://github.com/sahensley)
+- [Shawn Hensley](https://github.com/sahensley)
+
+Logo by [@IrishMorales](https://github.com/IrishMorales).

docs/installation.md

@@ -23,6 +23,12 @@ pipx's default binary location is `~/.local/bin`. This can be overriden with the
 
 pipx's default virtual environment location is `~/.local/pipx`. This can be overridden with the environment variable `PIPX_HOME`.
 
+## Shell Completion
+You can easily get your shell's tab completions working by following instructions printed with this command:
+```
+pipx completions
+```
+
 ## Install pipx Development Versions
 New versions of pipx are published as beta or release candidates. These versions look something like `0.13.0b1`, where `b1` signifies the first beta release of version 0.13. These releases can be tested with
 ```

makefile

@@ -12,10 +12,10 @@ publish:
 	pipx run nox -s publish-3.7
 
 docs:
-	pipx run nox --session docs -s docs-3.7
+	pipx run nox -s docs-3.7 -r
 
 watch_docs:
-	pipx run nox -s watch_docs-3.7
+	pipx run nox -s watch_docs-3.7 -r
 
 publish_docs:
-	pipx run nox -s publish_docs-3.7
+	pipx run nox -s publish_docs-3.7 -r

pipx/Venv.py

@@ -194,7 +194,8 @@ def run_app(self, app: str, app_args: List[str]):
             pass
 
     def upgrade_package(self, package_or_url: str, pip_args: List[str]):
-        self._run_pip(["install"] + pip_args + ["--upgrade", package_or_url])
+        with animate(f"upgrading package {package_or_url!r}", self.do_animation):
+            self._run_pip(["install"] + pip_args + ["--upgrade", package_or_url])
 
     def _run_pip(self, cmd):
         cmd = [self.python_path, "-m", "pip"] + cmd