diff options
Diffstat (limited to 'Doc')
-rw-r--r-- | Doc/library/development.rst | 1 | ||||
-rw-r--r-- | Doc/library/distribution.rst | 14 | ||||
-rw-r--r-- | Doc/library/ensurepip.rst | 125 | ||||
-rw-r--r-- | Doc/library/index.rst | 1 | ||||
-rw-r--r-- | Doc/library/python.rst | 1 | ||||
-rw-r--r-- | Doc/whatsnew/3.4.rst | 29 |
6 files changed, 169 insertions, 2 deletions
diff --git a/Doc/library/development.rst b/Doc/library/development.rst index 2368769..06e7048 100644 --- a/Doc/library/development.rst +++ b/Doc/library/development.rst @@ -23,4 +23,3 @@ The list of modules described in this chapter is: unittest.mock-examples.rst 2to3.rst test.rst - venv.rst diff --git a/Doc/library/distribution.rst b/Doc/library/distribution.rst new file mode 100644 index 0000000..fb3f5df --- /dev/null +++ b/Doc/library/distribution.rst @@ -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 <https://pypi.python.org>`__, 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 --git a/Doc/library/ensurepip.rst b/Doc/library/ensurepip.rst new file mode 100644 index 0000000..3756d4f --- /dev/null +++ b/Doc/library/ensurepip.rst @@ -0,0 +1,125 @@ +: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 + + :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: + +* ``--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 ``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 ``pipX`` + script will *not* be installed. + +* ``--default-pip``: if a "default pip" installation is requested, the + ``pip`` script will be installed in addition to the two regular scripts. + +Providing both of the script selection options will trigger an exception. + + +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=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. + + By default, the scripts ``pipX`` and ``pipX.Y`` will be installed (where + X.Y stands for the current version of Python). + + If *altinstall* is set, then ``pipX`` will *not* be installed. + + If *default_pip* is set, then ``pip`` will be installed in addition to + the two regular scripts. + + 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 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``). diff --git a/Doc/library/index.rst b/Doc/library/index.rst index 1b25c6e..81289a5 100644 --- a/Doc/library/index.rst +++ b/Doc/library/index.rst @@ -65,6 +65,7 @@ the `Python Package Index <http://pypi.python.org/pypi>`_. tk.rst development.rst debug.rst + distribution.rst python.rst custominterp.rst modules.rst diff --git a/Doc/library/python.rst b/Doc/library/python.rst index b67fbfc..f307d7d 100644 --- a/Doc/library/python.rst +++ b/Doc/library/python.rst @@ -25,4 +25,3 @@ overview: inspect.rst site.rst fpectl.rst - distutils.rst diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst index ed6daee..dd992ed 100644 --- a/Doc/whatsnew/3.4.rst +++ b/Doc/whatsnew/3.4.rst @@ -92,6 +92,7 @@ New library modules: * :mod:`asyncio`: New provisonal API for asynchronous IO (:pep:`3156`). * :mod:`enum`: Support for enumeration types (:pep:`435`). +* :mod:`ensurepip`: Bootstrapping the pip installer (:pep:`453`). * :mod:`selectors`: High-level and efficient I/O multiplexing, built upon the :mod:`select` module primitives. * :mod:`statistics`: A basic numerically stable statistics library (:pep:`450`). @@ -123,6 +124,34 @@ CPython implementation improvements: Please read on for a comprehensive list of user-facing changes. + +PEP 453: Explicit bootstrapping of pip in Python installations +============================================================== + +The new :mod:`ensurepip` module (defined in :pep:`453`) provides a standard +cross-platform mechanism to boostrap the pip installer into Python +installations and virtual environments. + +.. note:: + + Only the first phase of PEP 453 has been implemented at this point. + This section will be fleshed out with additional details once those + other changes are implemented. + + Refer to :issue:`19347` for the progress on additional steps: + + * ``make install`` and ``make altinstall`` integration + * Windows installer integration + * Mac OS X installer integration + * :mod:`venv` module and :command:`pyvenv` integration + +.. seealso:: + + :pep:`453` - Explicit bootstrapping of pip in Python installations + PEP written by Donald Stufft and Nick Coghlan, implemented by + Donald Stufft, Nick Coghlan (and ...). + + .. _pep-446: PEP 446: Make newly created file descriptors non-inheritable |