Implement PEP 477 - Backport ensurepip (PEP 453) to 2.7
* Backports ensurepip to the 2.7 branch
* Backports some of the improved documentation to the 2.7 branch.
* Adds a private backport of the 3.x mock library as test._mock_backport
to enable saner testing of ensurepip.
Key Differences from 3.x:
* Ensurepip does not have any Makefile integration, specifically
it is not ran by default in the Makefile.
* There is no venv module in 2.7, so downstream distributors can
completely disable ensurepip, ideally with a message redirecting
to the correct way to install pip.
* To match the ``python`` command in 2.7, ensurepip will install
the unversioned ``pip`` command as well.
* No-op and hide --default-pip and add --no-default-pip to restore
the 3.x behavor on 2.7.
diff --git a/Doc/library/ensurepip.rst b/Doc/library/ensurepip.rst
new file mode 100644
index 0000000..7206300
--- /dev/null
+++ b/Doc/library/ensurepip.rst
@@ -0,0 +1,130 @@
+:mod:`ensurepip` --- Bootstrapping the ``pip`` installer
+========================================================
+
+.. module:: ensurepip
+ :synopsis: Bootstrapping the ``pip`` installer into an existing Python
+ installation or virtual environment.
+
+.. versionadded:: 2.7.9
+
+The :mod:`ensurepip` package provides support for bootstrapping the ``pip``
+installer into an existing Python installation or virtual environment. This
+bootstrapping approach reflects the fact that ``pip`` is an independent
+project with its own release cycle, and the latest available stable version
+is bundled with maintenance and feature releases of the CPython reference
+interpreter.
+
+In most cases, end users of Python shouldn't need to invoke this module
+directly (as ``pip`` should be bootstrapped by default), but it may be
+needed if installing ``pip`` was skipped when installing Python (or
+when creating a virtual environment) or after explicitly uninstalling ``pip``.
+
+.. note::
+
+ This module *does not* access the internet. All of the components
+ needed to bootstrap ``pip`` are included as internal parts of the
+ package.
+
+.. seealso::
+
+ :ref:`installing-index`
+ The end user guide for installing Python packages
+
+ :pep:`453`: Explicit bootstrapping of pip in Python installations
+ The original rationale and specification for this module.
+
+ :pep:`477`: Backport ensurepip (PEP 453) to Python 2.7
+ The rationale and specification for backporting PEP 453 to Python 2.7.
+
+
+Command line interface
+----------------------
+
+The command line interface is invoked using the interpreter's ``-m`` switch.
+
+The simplest possible invocation is::
+
+ python -m ensurepip
+
+This invocation will install ``pip`` if it is not already installed,
+but otherwise does nothing. To ensure the installed version of ``pip``
+is at least as recent as the one bundled with ``ensurepip``, pass the
+``--upgrade`` option::
+
+ python -m ensurepip --upgrade
+
+By default, ``pip`` is installed into the current virtual environment
+(if one is active) or into the system site packages (if there is no
+active virtual environment). The installation location can be controlled
+through two additional command line options:
+
+* ``--root <dir>``: Installs ``pip`` relative to the given root directory
+ rather than the root of the currently active virtual environment (if any)
+ or the default root for the current Python installation.
+* ``--user``: Installs ``pip`` into the user site packages directory rather
+ than globally for the current Python installation (this option is not
+ permitted inside an active virtual environment).
+
+By default, the scripts ``pip``, ``pipX``, and ``pipX.Y`` will be installed
+(where X.Y stands for the version of Python used to invoke ``ensurepip``). The
+scripts installed can be controlled through two additional command line
+options:
+
+* ``--altinstall``: if an alternate installation is requested, the ``pip`` and
+ ``pipX`` script will *not* be installed.
+
+* ``--no-default-pip``: if a non-default installation is request, the ``pip``
+ script will *not* be installed.
+
+
+Module API
+----------
+
+:mod:`ensurepip` exposes two functions for programmatic use:
+
+.. function:: version()
+
+ Returns a string specifying the bundled version of pip that will be
+ installed when bootstrapping an environment.
+
+.. function:: bootstrap(root=None, upgrade=False, user=False, \
+ altinstall=False, default_pip=True, \
+ verbosity=0)
+
+ Bootstraps ``pip`` into the current or designated environment.
+
+ *root* specifies an alternative root directory to install relative to.
+ If *root* is None, then installation uses the default install location
+ for the current environment.
+
+ *upgrade* indicates whether or not to upgrade an existing installation
+ of an earlier version of ``pip`` to the bundled version.
+
+ *user* indicates whether to use the user scheme rather than installing
+ globally.
+
+ By default, the scripts ``pip``, ``pipX``, and ``pipX.Y`` will be installed
+ (where X.Y stands for the current version of Python).
+
+ If *altinstall* is set, then ``pip`` and ``pipX`` will *not* be installed.
+
+ If *default_pip* is set to ``False``, then ``pip`` will *not* be installed.
+
+ Setting both *altinstall* and *default_pip* will trigger
+ :exc:`ValueError`.
+
+ *verbosity* controls the level of output to :data:`sys.stdout` from the
+ bootstrapping operation.
+
+ .. note::
+
+ The bootstrapping process has side effects on both ``sys.path`` and
+ ``os.environ``. Invoking the command line interface in a subprocess
+ instead allows these side effects to be avoided.
+
+ .. note::
+
+ The bootstrapping process may install additional modules required by
+ ``pip``, but other software should not assume those dependencies will
+ always be present by default (as the dependencies may be removed in a
+ future version of ``pip``).