diff -r d6f427f94d85 Doc/library/development.rst --- a/Doc/library/development.rst Sun Oct 27 08:07:46 2013 +0200 +++ b/Doc/library/development.rst Sun Oct 27 17:31:55 2013 +1000 @@ -23,4 +23,3 @@ unittest.mock-examples.rst 2to3.rst test.rst - venv.rst diff -r d6f427f94d85 Doc/library/distribution.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Doc/library/distribution.rst Sun Oct 27 17:31:55 2013 +1000 @@ -0,0 +1,14 @@ +*********************************** +Software Packaging and Distribution +*********************************** + +These libraries help you with publishing and installing Python software. +While these modules are designed to work in conjunction with the +`Python Package Index `__, they can also be used +with a local index server, or without any index server at all. + +.. toctree:: + + distutils.rst + ensurepip.rst + venv.rst diff -r d6f427f94d85 Doc/library/ensurepip.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Doc/library/ensurepip.rst Sun Oct 27 17:31:55 2013 +1000 @@ -0,0 +1,103 @@ +:mod:`ensurepip` --- Bootstrapping the ``pip`` installer +======================================================== + +.. module:: ensurepip + :synopsis: Bootstrapping the ``pip`` installer into an existing Python + installation or virtual environment. + +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``. + +.. versionadded:: 3.4 + +.. 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:`install-index` + The end user guide for installing Python packages + + `http://www.pip-installer.org `__ + The upstream ``pip`` documentation + + :pep:`453`: Explicit bootstrapping of pip in Python installations + The original rationale and specification for this module. + + +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: + +* ``--user``: Installs ``pip`` into the user site packages directory rather + than into the currently active virtual environment or globally for the + Python installation. +* ``--root ``: Installs ``pip`` relative to the given root directory + rather than into the currently active virtual environment or globally + for the Python installation. + + +.. TODO: "pip install --user" questions + + Does --user actually work when a virtualenv is active? + What does --user do when --root is also specified? + + +Module API +---------- + +:mod:`ensurepip` expose 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, 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. + + .. See the CLI comments for queries regarding "pip install --user" + + *verbosity* controls the level of output to :data:`sys.stdout` from the + bootstrapping operation. diff -r d6f427f94d85 Doc/library/index.rst --- a/Doc/library/index.rst Sun Oct 27 08:07:46 2013 +0200 +++ b/Doc/library/index.rst Sun Oct 27 17:31:55 2013 +1000 @@ -65,6 +65,7 @@ tk.rst development.rst debug.rst + distribution.rst python.rst custominterp.rst modules.rst diff -r d6f427f94d85 Doc/library/python.rst --- a/Doc/library/python.rst Sun Oct 27 08:07:46 2013 +0200 +++ b/Doc/library/python.rst Sun Oct 27 17:31:55 2013 +1000 @@ -25,4 +25,3 @@ inspect.rst site.rst fpectl.rst - distutils.rst