add instructions to install python CLI applications with pipx (#594)

* add instructions to install python CLI applications with pipx

* create new guide for Installing stand alone command line tools (#406)

* add pipx to key projects; update pipx url; update installation instructions; document pipx list

* update pipx url in key projects

* clarify PATH text; fix upgrade command

* remove mention of symlinks

Author: Chad Smith

source/guides/index.rst

@@ -10,6 +10,7 @@ introduction to packaging, see :doc:`/tutorials/index`.
 
    tool-recommendations
    installing-using-pip-and-virtualenv
+   installing-stand-alone-command-line-tools
    installing-using-linux-tools
    installing-scientific-packages
    multi-version-installs

source/guides/installing-stand-alone-command-line-tools.rst

@@ -0,0 +1,113 @@
+Installing stand alone command line tools
+=========================================
+
+Many packages have command line entry points. Examples of this type of application are
+`mypy <https://github.com/python/mypy>`_,
+`flake8 <https://github.com/PyCQA/flake8>`_,
+`pipenv <https://github.com/pypa/pipenv>`_,and
+`black <https://github.com/ambv/black>`_.
+
+Usually you want to be able to access these from anywhere,
+but installing packages and their dependencies to the same global environment
+can cause version conflicts and break dependencies the operating system has
+on Python packages.
+
+`pipx <https://github.com/pipxproject/pipx>`_ solves this by creating a virtual
+environment for each package, while also ensuring that package's applications
+are accessible through a directory that is on your ``$PATH``. This allows each
+package to be upgraded or uninstalled without causing conflicts with other
+packages, and allows you to safely run the program from anywhere.
+
+.. Note:: pipx only works with Python 3.6+.
+
+``pipx`` is installed with ``pip``:
+
+::
+
+  $ pip install --user pipx
+  $ pipx ensurepath  # ensures the path of the CLI application directory is on your $PATH
+
+.. Note:: You may need to restart your terminal for the path updates to take effect.
+
+Now you can install packages with ``pipx install`` and access the package's entry point(s) from anywhere.
+
+::
+
+  $ pipx install PACKAGE
+  $ ENTRYPOINT_OF_PACKAGE [ARGS]
+
+For example
+
+::
+
+  $ pipx install cowsay
+    installed package cowsay 2.0, Python 3.6.2+
+    These binaries are now globally available
+      - cowsay
+  done! ✨ 🌟 ✨
+  $ cowsay moo
+    ___
+  < moo >
+    ===
+          \
+           \
+             ^__^
+             (oo)\_______
+             (__)\       )\/       ||----w |
+                 ||     ||
+
+To see a list of packages installed with pipx and which CLI applications are available, use ``pipx list``.
+
+::
+
+  $ pipx list
+  venvs are in /Users/user/.local/pipx/venvs
+  symlinks to binaries are in /Users/user/.local/bin
+     package black 18.9b0, Python 3.6.2+
+      - black
+      - blackd
+     package cowsay 2.0, Python 3.6.2+
+      - cowsay
+     package mypy 0.660, Python 3.6.2+
+      - dmypy
+      - mypy
+      - stubgen
+     package nox 2018.10.17, Python 3.6.2+
+      - nox
+      - tox-to-nox
+
+To upgrade or uninstall the package
+
+::
+
+  $ pipx upgrade PACKAGE
+  $ pipx uninstall PACKAGE
+
+``pipx`` can be upgraded or uninstalled with pip
+
+::
+
+  $ pip install -U pipx
+  $ pip uninstall pipx
+
+``pipx`` also allows you to install and run the latest version of a cli tool
+in a temporary, ephemeral environment.
+
+::
+
+  $ pipx run PACKAGE [ARGS]
+
+For example
+
+::
+
+  $ pipx run cowsay moooo
+
+To see the full list of commands ``pipx`` offers, run
+
+::
+
+  $ pipx --help
+
+You can learn more about ``pipx`` at its homepage,
+https://github.com/pipxproject/pipx.

source/key_projects.rst

@@ -21,7 +21,7 @@ bandersnatch
 `Mailing list <http://mail.python.org/mailman/listinfo/distutils-sig>`__ [2]_ |
 `Issues <https://github.com/pypa/bandersnatch/issues>`__ |
 `Github <https://github.com/pypa/bandersnatch>`__ |
-`PyPI <https://pypi.org/project/bandersnatch>`__ | 
+`PyPI <https://pypi.org/project/bandersnatch>`__ |
 Dev irc:#bandersnatch
 
 bandersnatch is a PyPI mirroring client designed to efficiently create a
@@ -341,6 +341,17 @@ files, standalone Python environments in the spirit of :ref:`virtualenv`.
 ``#!/usr/bin/env python`` and special :file:`__main__.py`, and are designed to
 make deployment of Python applications as simple as ``cp``.
 
+.. _pipx:
+
+pipx
+====
+
+`Docs <https://github.com/pipxproject/pipx>`__ |
+`Github <https://github.com/pipxproject/pipx>`__ |
+`PyPI <https://pypi.org/project/pipx/>`__
+
+pipx is a tool to safely install and run Python CLI applications globally.
+
 .. _scikit-build:
 
 scikit-build

source/tutorials/installing-packages.rst

@@ -161,7 +161,9 @@ Creating Virtual Environments
 
 Python "Virtual Environments" allow Python :term:`packages <Distribution
 Package>` to be installed in an isolated location for a particular application,
-rather than being installed globally.
+rather than being installed globally. If you are looking to safely install
+global command line tools,
+see :doc:`/guides/installing-stand-alone-command-line-tools`.
 
 Imagine you have an application that needs version 1 of LibFoo, but another
 application requires version 2. How can you use both these applications? If you
@@ -472,7 +474,6 @@ Install `setuptools extras`_.
   $ pip install -e .[PDF]==3.0  # editable project in current directory
 
 
-
 ----
 
 .. [1] "Secure" in this context means using a modern browser or a