McSinyx
/
pip
mirror of https://github.com/pypa/pip
1
1
Fork 0
Code Issues Releases Activity

Merge pull request #9008 from pradyunsg/better-tabs

This commit is contained in:
Pradyun Gedam 2020-10-19 19:40:51 +05:30 committed by GitHub
parent 4e26bf22f5 fb03b6aede
commit 08c99b6e00
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
20 changed files with 1064 additions and 1292 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/html/conf.py
View File

@ -35,7 +35,7 @@ extensions = [
'sphinx.ext.extlinks',
'sphinx.ext.intersphinx',
# third-party:
'sphinx_tabs.tabs',
'sphinx_inline_tabs',
# in-tree:
'docs_feedback_sphinxext',
'pip_sphinxext',

6
docs/html/development/getting-started.rst
View File

@ -38,9 +38,7 @@ To run the pip executable from your source tree during development, install pip
locally using editable installation (inside a virtualenv).
You can then invoke your local source tree pip normally.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
@ -49,7 +47,7 @@ You can then invoke your local source tree pip normally.
python -m pip install -e .
python -m pip --version
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell

36
docs/html/installing.rst
View File

@ -28,15 +28,13 @@ this link: `get-pip.py
Then run the following command in the folder where you
have downloaded ``get-pip.py``:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python get-pip.py
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -81,15 +79,13 @@ some examples:
Install from local copies of pip and setuptools:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python get-pip.py --no-index --find-links=/local/copies
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -97,15 +93,13 @@ Install from local copies of pip and setuptools:
Install to the user site [3]_:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python get-pip.py --user
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -113,15 +107,13 @@ Install to the user site [3]_:
Install behind a proxy:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python get-pip.py --proxy="http://[user:passwd@]proxy.server:port"
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -130,15 +122,13 @@ Install behind a proxy:
``get-pip.py`` can also be used to install a specified combination of ``pip``,
``setuptools``, and ``wheel`` using the same requirements syntax as pip:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -156,15 +146,13 @@ the `Python Packaging User Guide
Upgrading pip
=============
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install -U pip
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell

38
docs/html/quickstart.rst
View File

@ -6,9 +6,7 @@ First, :doc:`install pip <installing>`.
Install a package from `PyPI`_:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -16,7 +14,7 @@ Install a package from `PyPI`_:
[...]
Successfully installed SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -29,9 +27,7 @@ Install a package that's already been downloaded from `PyPI`_ or
obtained from elsewhere. This is useful if the target machine does not have a
network connection:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -39,7 +35,7 @@ network connection:
[...]
Successfully installed SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -47,12 +43,9 @@ network connection:
[...]
Successfully installed SomePackage
Show what files were installed:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -64,7 +57,7 @@ Show what files were installed:
../somepackage/__init__.py
[...]
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -78,16 +71,14 @@ Show what files were installed:
List what packages are outdated:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
$ python -m pip list --outdated
SomePackage (Current: 1.0 Latest: 2.0)
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -96,9 +87,7 @@ List what packages are outdated:
Upgrade a package:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -110,7 +99,7 @@ Upgrade a package:
Running setup.py install for SomePackage
Successfully installed SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -124,9 +113,7 @@ Upgrade a package:
Uninstall a package:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -136,7 +123,7 @@ Uninstall a package:
Proceed (y/n)? y
Successfully uninstalled SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -146,5 +133,4 @@ Uninstall a package:
Proceed (y/n)? y
Successfully uninstalled SomePackage
.. _PyPI: https://pypi.org/

12
docs/html/reference/pip.rst
View File

@ -7,15 +7,13 @@ pip
Usage
*****
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip <command> [options]
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -232,15 +230,13 @@ and ``pip wheel`` inject additional arguments into the ``setup.py`` command
(``--build-option`` is only available in ``pip wheel``). These arguments are
included in the command as follows:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
python setup.py <global_options> BUILD COMMAND <build_options>
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell

6
docs/html/reference/pip_cache.rst
View File

@ -9,13 +9,11 @@ pip cache
Usage
*****
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: cache "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: cache "py -m pip"

24
docs/html/reference/pip_check.rst
View File

@ -10,13 +10,11 @@ pip check
Usage
=====
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: check "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: check "py -m pip"
@ -32,9 +30,7 @@ Examples
#. If all dependencies are compatible:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -43,7 +39,7 @@ Examples
$ echo $?
0
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -54,9 +50,7 @@ Examples
#. If a package is missing:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -65,7 +59,7 @@ Examples
$ echo $?
1
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -76,9 +70,7 @@ Examples
#. If a package has the wrong version:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -87,7 +79,7 @@ Examples
$ echo $?
1
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console

6
docs/html/reference/pip_config.rst
View File

@ -11,13 +11,11 @@ pip config
Usage
=====
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: config "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: config "py -m pip"

6
docs/html/reference/pip_debug.rst
View File

@ -10,13 +10,11 @@ pip debug
Usage
=====
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: debug "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: debug "py -m pip"

36
docs/html/reference/pip_download.rst
View File

@ -11,13 +11,11 @@ pip download
Usage
=====
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: download "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: download "py -m pip"
@ -64,9 +62,7 @@ Examples
#. Download a package and all of its dependencies
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
@ -74,7 +70,7 @@ Examples
python -m pip download -d . SomePackage # equivalent to above
python -m pip download --no-index --find-links=/tmp/wheelhouse -d /tmp/otherwheelhouse SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -90,9 +86,7 @@ Examples
It will also match deps with platform ``any``. Also force the interpreter version to ``27``
(or more generic, i.e. ``2``) and implementation to ``cp`` (or more generic, i.e. ``py``).
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
@ -103,7 +97,7 @@ Examples
--implementation cp \
SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -118,9 +112,7 @@ Examples
Force the interpreter to be any minor version of py3k, and only accept
``cp34m`` or ``none`` as the abi.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
@ -132,7 +124,7 @@ Examples
--abi cp34m \
SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -146,9 +138,7 @@ Examples
#. Force platform, implementation, and abi agnostic deps.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
@ -160,7 +150,7 @@ Examples
--abi none \
SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -174,9 +164,7 @@ Examples
#. Even when overconstrained, this will still correctly fetch the pip universal wheel.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -193,7 +181,7 @@ Examples
$ ls pip-8.1.1-py2.py3-none-any.whl
pip-8.1.1-py2.py3-none-any.whl
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console

19
docs/html/reference/pip_freeze.rst
View File

@ -11,13 +11,11 @@ pip freeze
Usage
=====
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: freeze "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: freeze "py -m pip"
@ -39,9 +37,7 @@ Examples
#. Generate output suitable for a requirements file.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -52,7 +48,7 @@ Examples
Pygments==1.6
Sphinx==1.2.2
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -63,19 +59,16 @@ Examples
Pygments==1.6
Sphinx==1.2.2
#. Generate a requirements file and then install from it in another environment.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
env1/bin/python -m pip freeze > requirements.txt
env2/bin/python -m pip install -r requirements.txt
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell

12
docs/html/reference/pip_hash.rst
View File

@ -10,13 +10,11 @@ pip hash
Usage
=====
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: hash "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: hash "py -m pip"
@ -49,9 +47,7 @@ Example
Compute the hash of a downloaded archive:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -64,7 +60,7 @@ Compute the hash of a downloaded archive:
./pip_downloads/SomePackage-2.2.tar.gz:
--hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console

145
docs/html/reference/pip_install.rst
View File

@ -10,13 +10,11 @@ pip install
Usage
=====
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: install "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: install "py -m pip"
@ -100,9 +98,7 @@ encountered member of the cycle is installed last.
For instance, if quux depends on foo which depends on bar which depends on baz,
which depends on foo:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -114,7 +110,7 @@ which depends on foo:
...
Installing collected packages foo, baz, bar
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -416,15 +412,13 @@ If your repository layout is::
Then, to install from this repository, the syntax would be:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -677,9 +671,7 @@ against any requirement not only checks that hash but also activates a global
Hash-checking mode can be forced on with the ``--require-hashes`` command-line
option:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -693,7 +685,7 @@ option:
pyelasticsearch==1.0 --hash=sha256:44ddfb1225054d7d6b1d02e9338e7d4809be94edbe9929a2ec0807d38df993fa
more-itertools==2.2 --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -754,15 +746,13 @@ Hash-checking mode also works with :ref:`pip download` and :ref:`pip wheel`. A
Instead of ``python setup.py develop``, use...
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install --no-deps -e .
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -771,15 +761,13 @@ Hash-checking mode also works with :ref:`pip download` and :ref:`pip wheel`. A
Instead of ``python setup.py install``, use...
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install --no-deps .
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -803,21 +791,18 @@ Local project installs
pip supports installing local project in both regular mode and editable mode.
You can install local projects by specifying the project path to pip:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install path/to/SomeProject
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
py -m pip install path/to/SomeProject
During regular installation, pip will copy the entire project directory to a
temporary location and install from there. The exception is that pip will
exclude .tox and .nox directories present in the top level of the project from
@ -835,16 +820,14 @@ installs.
You can install local projects or VCS projects in "editable" mode:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install -e path/to/SomeProject
python -m pip install -e git+http://repo/my_project.git#egg=SomeProject
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -957,9 +940,7 @@ Examples
#. Install ``SomePackage`` and its dependencies from `PyPI`_ using :ref:`Requirement Specifiers`
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
@ -967,7 +948,7 @@ Examples
python -m pip install SomePackage==1.0.4 # specific version
python -m pip install 'SomePackage>=1.0.4' # minimum version
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -978,15 +959,13 @@ Examples
#. Install a list of requirements specified in a file. See the :ref:`Requirements files <Requirements Files>`.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install -r requirements.txt
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -995,15 +974,13 @@ Examples
#. Upgrade an already installed ``SomePackage`` to the latest from PyPI.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install --upgrade SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -1012,16 +989,14 @@ Examples
#. Install a local project in "editable" mode. See the section on :ref:`Editable Installs <editable-installs>`.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install -e . # project in current directory
python -m pip install -e path/to/project # project in another directory
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -1031,15 +1006,13 @@ Examples
#. Install a project from VCS
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -1048,9 +1021,7 @@ Examples
#. Install a project from VCS in "editable" mode. See the sections on :ref:`VCS Support <VCS Support>` and :ref:`Editable Installs <editable-installs>`.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
@ -1060,7 +1031,7 @@ Examples
python -m pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomePackage # from 'feature' branch
python -m pip install -e "git+https://git.repo/some_repo.git#egg=subdir&subdirectory=subdir_path" # install a python package from a repo subdirectory
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -1070,12 +1041,9 @@ Examples
py -m pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomePackage # from 'feature' branch
py -m pip install -e "git+https://git.repo/some_repo.git#egg=subdir&subdirectory=subdir_path" # install a python package from a repo subdirectory
#. Install a package with `setuptools extras`_.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
@ -1085,7 +1053,7 @@ Examples
python -m pip install SomePackage[PDF]==3.0
python -m pip install SomePackage[PDF,EPUB] # multiple extras
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -1095,31 +1063,25 @@ Examples
py -m pip install SomePackage[PDF]==3.0
py -m pip install SomePackage[PDF,EPUB] # multiple extras
#. Install a particular source archive file.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install ./downloads/SomePackage-1.0.4.tar.gz
python -m pip install http://my.package.repo/SomePackage-1.0.4.zip
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
py -m pip install ./downloads/SomePackage-1.0.4.tar.gz
py -m pip install http://my.package.repo/SomePackage-1.0.4.zip
#. Install a particular source archive file following :pep:`440` direct references.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
@ -1127,7 +1089,7 @@ Examples
python -m pip install "SomeProject @ http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl"
python -m pip install SomeProject@http://my.package.repo/1.2.3.tar.gz
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -1135,48 +1097,39 @@ Examples
py -m pip install "SomeProject @ http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl"
py -m pip install SomeProject@http://my.package.repo/1.2.3.tar.gz
#. Install from alternative package repositories.
Install from a different index, and not `PyPI`_
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install --index-url http://my.package.repo/simple/ SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
py -m pip install --index-url http://my.package.repo/simple/ SomePackage
Search an additional index during install, in addition to `PyPI`_
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install --extra-index-url http://my.package.repo/simple SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
py -m pip install --extra-index-url http://my.package.repo/simple SomePackage
Install from a local flat directory containing archives (and don't scan indexes):
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
@ -1184,7 +1137,7 @@ Examples
python -m pip install --no-index --find-links=/local/dir/ SomePackage
python -m pip install --no-index --find-links=relative/dir/ SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -1195,15 +1148,13 @@ Examples
#. Find pre-release and development versions, in addition to stable versions. By default, pip only finds stable versions.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install --pre SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -1214,15 +1165,13 @@ Examples
Do not use any binary packages
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install SomePackage1 SomePackage2 --no-binary :all:
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -1230,15 +1179,13 @@ Examples
Specify ``SomePackage1`` to be installed from source:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell

55
docs/html/reference/pip_list.rst
View File

@ -10,13 +10,11 @@ pip list
Usage
=====
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: list "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: list "py -m pip"
@ -40,9 +38,7 @@ Examples
#. List installed packages.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -53,7 +49,7 @@ Examples
Pygments (1.6)
Sphinx (1.2.1)
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -66,9 +62,7 @@ Examples
#. List outdated packages (excluding editables), and the latest version available.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -76,7 +70,7 @@ Examples
docutils (Current: 0.10 Latest: 0.11)
Sphinx (Current: 1.2.1 Latest: 1.2.2)
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -84,12 +78,9 @@ Examples
docutils (Current: 0.10 Latest: 0.11)
Sphinx (Current: 1.2.1 Latest: 1.2.2)
#. List installed packages with column formatting.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -100,7 +91,7 @@ Examples
idlex 1.13
jedi 0.9.0
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -113,9 +104,7 @@ Examples
#. List outdated packages with column formatting.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -125,7 +114,7 @@ Examples
retry 0.8.1 0.9.1 wheel
setuptools 20.6.7 21.0.0 wheel
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -138,16 +127,14 @@ Examples
#. List packages that are not dependencies of other packages. Can be combined with
other options.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
$ python -m pip list --outdated --not-required
docutils (Current: 0.10 Latest: 0.11)
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -156,9 +143,7 @@ Examples
#. Use legacy formatting
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -168,7 +153,7 @@ Examples
idlex (1.13)
jedi (0.9.0)
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -180,16 +165,14 @@ Examples
#. Use json formatting
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
$ python -m pip list --format=json
[{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ...
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -198,9 +181,7 @@ Examples
#. Use freeze formatting
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -210,7 +191,7 @@ Examples
idlex==1.13
jedi==0.9.0
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console

12
docs/html/reference/pip_search.rst
View File

@ -10,13 +10,11 @@ pip search
Usage
=====
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: search "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: search "py -m pip"
@ -38,9 +36,7 @@ Examples
#. Search for "peppercorn"
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -48,7 +44,7 @@ Examples
pepperedform - Helpers for using peppercorn with formprocess.
peppercorn - A library for converting a token stream into [...]
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console

18
docs/html/reference/pip_show.rst
View File

@ -10,13 +10,11 @@ pip show
Usage
=====
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: show "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: show "py -m pip"
@ -38,9 +36,7 @@ Examples
#. Show information about a package:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -55,7 +51,7 @@ Examples
Location: /my/env/lib/python2.7/site-packages
Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -72,9 +68,7 @@ Examples
#. Show all information about a package
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -117,7 +111,7 @@ Examples
[distutils.commands]
build_sphinx = sphinx.setup_command:BuildDoc
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console

12
docs/html/reference/pip_uninstall.rst
View File

@ -10,13 +10,11 @@ pip uninstall
Usage
=====
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: uninstall "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: uninstall "py -m pip"
@ -38,9 +36,7 @@ Examples
#. Uninstall a package.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -51,7 +47,7 @@ Examples
Proceed (y/n)? y
Successfully uninstalled simplejson
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console

30
docs/html/reference/pip_wheel.rst
View File

@ -11,13 +11,11 @@ pip wheel
Usage
=====
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. pip-command-usage:: wheel "python -m pip"
.. group-tab:: Windows
.. tab:: Windows
.. pip-command-usage:: wheel "py -m pip"
@ -34,15 +32,13 @@ Build System Interface
In order for pip to build a wheel, ``setup.py`` must implement the
``bdist_wheel`` command with the following syntax:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python setup.py bdist_wheel -d TARGET
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -62,15 +58,13 @@ with their arguments in the ``setup.py`` command. This is currently the only
way to influence the building of C extensions from the command line. For
example:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip wheel --global-option bdist_ext --global-option -DFOO wheel
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -103,16 +97,14 @@ Examples
#. Build wheels for a requirement (and all its dependencies), and then install
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip wheel --wheel-dir=/tmp/wheelhouse SomePackage
python -m pip install --no-index --find-links=/tmp/wheelhouse SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -121,15 +113,13 @@ Examples
#. Build a wheel for a package from source
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip wheel --no-binary SomePackage SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell

179
docs/html/user_guide.rst
View File

@ -11,9 +11,7 @@ Running pip
pip is a command line program. When you install pip, a ``pip`` command is added
to your system, which can be run from the command prompt as follows:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
@ -23,7 +21,7 @@ to your system, which can be run from the command prompt as follows:
specified as python. So ``/usr/bin/python3.7 -m pip`` means
you are executing pip for your interpreter located at /usr/bin/python3.7.
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -43,9 +41,7 @@ directly from distribution files.
The most common scenario is to install from `PyPI`_ using :ref:`Requirement
Specifiers`
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
@ -53,7 +49,7 @@ Specifiers`
python -m pip install SomePackage==1.0.4 # specific version
python -m pip install 'SomePackage>=1.0.4' # minimum version
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -162,15 +158,13 @@ Requirements Files
"Requirements files" are files containing a list of items to be
installed using :ref:`pip install` like so:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install -r requirements.txt
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -189,16 +183,14 @@ In practice, there are 4 common uses of Requirements files:
this case, your requirement file contains a pinned version of everything that
was installed when ``pip freeze`` was run.
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -270,15 +262,13 @@ installation of the package.
Use a constraints file like so:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install -c constraints.txt
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -320,15 +310,13 @@ archives.
To install directly from a wheel archive:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install SomePackage-1.0-py2.py3-none-any.whl
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -345,16 +333,14 @@ convenience, to build wheels for all your requirements and dependencies.
To build wheels for your requirements and all their dependencies to a local
directory:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install wheel
python -m pip wheel --wheel-dir=/local/wheels -r requirements.txt
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -364,15 +350,13 @@ directory:
And *then* to install those requirements just using your local directory of
wheels (and not from PyPI):
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install --no-index --find-links=/local/wheels -r requirements.txt
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -384,15 +368,13 @@ Uninstalling Packages
pip is able to uninstall most packages like so:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip uninstall SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -410,9 +392,7 @@ Listing Packages
To list installed packages:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -422,7 +402,7 @@ To list installed packages:
Pygments (1.5)
Sphinx (1.1.2)
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -435,9 +415,7 @@ To list installed packages:
To list outdated packages, and show the latest version available:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -445,7 +423,7 @@ To list outdated packages, and show the latest version available:
docutils (Current: 0.9.1 Latest: 0.10)
Sphinx (Current: 1.1.2 Latest: 1.1.3)
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -455,9 +433,7 @@ To list outdated packages, and show the latest version available:
To show details about an installed package:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -468,7 +444,7 @@ To show details about an installed package:
Location: /my/env/lib/pythonx.x/site-packages
Requires: Pygments, Jinja2, docutils
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -479,7 +455,6 @@ To show details about an installed package:
Location: /my/env/lib/pythonx.x/site-packages
Requires: Pygments, Jinja2, docutils
For more information and examples, see the :ref:`pip list` and :ref:`pip show`
reference pages.
@ -490,15 +465,13 @@ Searching for Packages
pip can search `PyPI`_ for packages using the ``pip search``
command:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip search "query"
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -664,15 +637,13 @@ underscores (``_``).
For example, to set the default timeout:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
export PIP_DEFAULT_TIMEOUT=60
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -680,15 +651,13 @@ For example, to set the default timeout:
This is the same as passing the option to pip directly:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip --default-timeout=60 [...]
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -697,38 +666,32 @@ This is the same as passing the option to pip directly:
For command line options which can be repeated, use a space to separate
multiple values. For example:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
set PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
is the same as calling:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
py -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
Options that do not take a value, but can be repeated (such as ``--verbose``)
can be specified using the number of repetitions, so::
@ -799,36 +762,31 @@ to PyPI.
First, download the archives that fulfill your requirements:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip download --destination-directory DIR -r requirements.txt
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
py -m pip download --destination-directory DIR -r requirements.txt
Note that ``pip download`` will look in your wheel cache first, before
trying to download from PyPI. If you've never installed your requirements
before, you won't have a wheel cache for those items. In that case, if some of
your requirements don't come as wheels from PyPI, and you want wheels, then run
this instead:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip wheel --wheel-dir DIR -r requirements.txt
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -837,15 +795,13 @@ this instead:
Then, to install from local only, you'll be using :ref:`--find-links
<install_--find-links>` and :ref:`--no-index <install_--no-index>` like so:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install --no-index --find-links=DIR -r requirements.txt
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -870,16 +826,14 @@ the breaking nature of ``eager`` when upgrading conflicting dependencies.
As an historic note, an earlier "fix" for getting the ``only-if-needed``
behaviour was:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install --upgrade --no-deps SomePackage
python -m pip install SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -910,16 +864,14 @@ Moreover, the "user scheme" can be customized by setting the
To install "SomePackage" into an environment with site.USER_BASE customized to
'/myappenv', do the following:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
export PYTHONUSERBASE=/myappenv
python -m pip install --user SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -946,19 +898,16 @@ To install "SomePackage" into an environment with site.USER_BASE customized to
To make the rules clearer, here are some examples:
From within a ``--no-site-packages`` virtualenv (i.e. the default kind):
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
$ python -m pip install --user SomePackage
Can not perform a '--user' install. User site-packages are not visible in this virtualenv.
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -969,16 +918,14 @@ From within a ``--no-site-packages`` virtualenv (i.e. the default kind):
From within a ``--system-site-packages`` virtualenv where ``SomePackage==0.3``
is already installed in the virtualenv:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
$ python -m pip install --user SomePackage==0.4
Will not install to the user site because it will lack sys.path precedence
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -987,9 +934,7 @@ is already installed in the virtualenv:
From within a real python, where ``SomePackage`` is *not* installed globally:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -997,7 +942,7 @@ From within a real python, where ``SomePackage`` is *not* installed globally:
[...]
Successfully installed SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -1008,9 +953,7 @@ From within a real python, where ``SomePackage`` is *not* installed globally:
From within a real python, where ``SomePackage`` *is* installed globally, but
is *not* the latest version:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -1021,7 +964,7 @@ is *not* the latest version:
[...]
Successfully installed SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -1035,9 +978,7 @@ is *not* the latest version:
From within a real python, where ``SomePackage`` *is* installed globally, and
is the latest version:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: console
@ -1052,7 +993,7 @@ is the latest version:
[...]
Successfully installed SomePackage
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: console
@ -1171,15 +1112,13 @@ Understanding your error message
When you get a ``ResolutionImpossible`` error, you might see something
like this:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install package_coffee==0.44.1 package_tea==4.3.0
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell
@ -1289,15 +1228,13 @@ In the second case, pip will automatically find a version of both
If you want to prioritize one package over another, you can add version
specifiers to *only* the more important package:
.. tabs::
.. group-tab:: Unix/macOS
.. tab:: Unix/macOS
.. code-block:: shell
python -m pip install package_coffee==0.44.1b0 package_tea
.. group-tab:: Windows
.. tab:: Windows
.. code-block:: shell

2
tools/requirements/docs.txt
View File

@ -1,7 +1,7 @@
sphinx == 3.2.1
git+https://github.com/python/python-docs-theme.git#egg=python-docs-theme
git+https://github.com/pypa/pypa-docs-theme.git#egg=pypa-docs-theme
sphinx-tabs == 1.1.13
sphinx-inline-tabs
# `docs.pipext` uses pip's internals to generate documentation. So, we install
# the current directory to make it work.