From fb03b6aedeb2eb5e68d3dd539c13f2f0eb57b01d Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 18 Oct 2020 22:42:24 +0530 Subject: [PATCH] Switch to sphinx-inline-tabs for tabs --- docs/html/conf.py | 2 +- docs/html/development/getting-started.rst | 26 +- docs/html/installing.rst | 84 ++-- docs/html/quickstart.rst | 172 ++++--- docs/html/reference/pip.rst | 28 +- docs/html/reference/pip_cache.rst | 10 +- docs/html/reference/pip_check.rst | 88 ++-- docs/html/reference/pip_config.rst | 10 +- docs/html/reference/pip_debug.rst | 10 +- docs/html/reference/pip_download.rst | 192 ++++---- docs/html/reference/pip_freeze.rst | 63 ++- docs/html/reference/pip_hash.rst | 52 +- docs/html/reference/pip_install.rst | 473 +++++++++---------- docs/html/reference/pip_list.rst | 227 ++++----- docs/html/reference/pip_search.rst | 32 +- docs/html/reference/pip_show.rst | 222 +++++---- docs/html/reference/pip_uninstall.rst | 44 +- docs/html/reference/pip_wheel.rst | 70 ++- docs/html/user_guide.rst | 549 ++++++++++------------ tools/requirements/docs.txt | 2 +- 20 files changed, 1064 insertions(+), 1292 deletions(-) diff --git a/docs/html/conf.py b/docs/html/conf.py index 444d15a81..adee6fd3c 100644 --- a/docs/html/conf.py +++ b/docs/html/conf.py @@ -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', diff --git a/docs/html/development/getting-started.rst b/docs/html/development/getting-started.rst index 1bc4a5516..436ed241b 100644 --- a/docs/html/development/getting-started.rst +++ b/docs/html/development/getting-started.rst @@ -38,25 +38,23 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + virtualenv venv # You can also use "python -m venv venv" from python3.3+ + source venv/bin/activate + python -m pip install -e . + python -m pip --version - virtualenv venv # You can also use "python -m venv venv" from python3.3+ - source venv/bin/activate - python -m pip install -e . - python -m pip --version +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - virtualenv venv # You can also use "py -m venv venv" from python3.3+ - venv\Scripts\activate - py -m pip install -e . - py -m pip --version + virtualenv venv # You can also use "py -m venv venv" from python3.3+ + venv\Scripts\activate + py -m pip install -e . + py -m pip --version Running Tests ============= diff --git a/docs/html/installing.rst b/docs/html/installing.rst index 5379c1da0..00c74a70a 100644 --- a/docs/html/installing.rst +++ b/docs/html/installing.rst @@ -28,19 +28,17 @@ this link: `get-pip.py Then run the following command in the folder where you have downloaded ``get-pip.py``: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python get-pip.py - python get-pip.py +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py get-pip.py + py get-pip.py .. warning:: @@ -81,68 +79,60 @@ some examples: Install from local copies of pip and setuptools: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python get-pip.py --no-index --find-links=/local/copies - python get-pip.py --no-index --find-links=/local/copies +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py get-pip.py --no-index --find-links=/local/copies + py get-pip.py --no-index --find-links=/local/copies Install to the user site [3]_: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python get-pip.py --user - python get-pip.py --user +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py get-pip.py --user + py get-pip.py --user Install behind a proxy: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python get-pip.py --proxy="http://[user:passwd@]proxy.server:port" - python get-pip.py --proxy="http://[user:passwd@]proxy.server:port" +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py get-pip.py --proxy="http://[user:passwd@]proxy.server:port" + py get-pip.py --proxy="http://[user:passwd@]proxy.server:port" ``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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 - python get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 + py get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 Using Linux Package Managers ============================ @@ -156,19 +146,17 @@ the `Python Packaging User Guide Upgrading pip ============= -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install -U pip - python -m pip install -U pip +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install -U pip + py -m pip install -U pip .. _compatibility-requirements: diff --git a/docs/html/quickstart.rst b/docs/html/quickstart.rst index 9591e1127..96602a7b3 100644 --- a/docs/html/quickstart.rst +++ b/docs/html/quickstart.rst @@ -6,145 +6,131 @@ First, :doc:`install pip `. Install a package from `PyPI`_: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip install SomePackage + [...] + Successfully installed SomePackage - $ python -m pip install SomePackage - [...] - Successfully installed SomePackage +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip install SomePackage - [...] - Successfully installed SomePackage + C:\> py -m pip install SomePackage + [...] + Successfully installed SomePackage 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip install SomePackage-1.0-py2.py3-none-any.whl + [...] + Successfully installed SomePackage - $ python -m pip install SomePackage-1.0-py2.py3-none-any.whl - [...] - Successfully installed SomePackage +.. tab:: Windows - .. group-tab:: Windows - - .. code-block:: console - - C:\> py -m pip install SomePackage-1.0-py2.py3-none-any.whl - [...] - Successfully installed SomePackage + .. code-block:: console + C:\> py -m pip install SomePackage-1.0-py2.py3-none-any.whl + [...] + Successfully installed SomePackage Show what files were installed: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip show --files SomePackage + Name: SomePackage + Version: 1.0 + Location: /my/env/lib/pythonx.x/site-packages + Files: + ../somepackage/__init__.py + [...] - $ python -m pip show --files SomePackage - Name: SomePackage - Version: 1.0 - Location: /my/env/lib/pythonx.x/site-packages - Files: - ../somepackage/__init__.py - [...] +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip show --files SomePackage - Name: SomePackage - Version: 1.0 - Location: /my/env/lib/pythonx.x/site-packages - Files: - ../somepackage/__init__.py - [...] + C:\> py -m pip show --files SomePackage + Name: SomePackage + Version: 1.0 + Location: /my/env/lib/pythonx.x/site-packages + Files: + ../somepackage/__init__.py + [...] List what packages are outdated: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip list --outdated + SomePackage (Current: 1.0 Latest: 2.0) - $ python -m pip list --outdated - SomePackage (Current: 1.0 Latest: 2.0) +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip list --outdated - SomePackage (Current: 1.0 Latest: 2.0) + C:\> py -m pip list --outdated + SomePackage (Current: 1.0 Latest: 2.0) Upgrade a package: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip install --upgrade SomePackage + [...] + Found existing installation: SomePackage 1.0 + Uninstalling SomePackage: + Successfully uninstalled SomePackage + Running setup.py install for SomePackage + Successfully installed SomePackage - $ python -m pip install --upgrade SomePackage - [...] - Found existing installation: SomePackage 1.0 - Uninstalling SomePackage: - Successfully uninstalled SomePackage - Running setup.py install for SomePackage - Successfully installed SomePackage +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip install --upgrade SomePackage - [...] - Found existing installation: SomePackage 1.0 - Uninstalling SomePackage: - Successfully uninstalled SomePackage - Running setup.py install for SomePackage - Successfully installed SomePackage + C:\> py -m pip install --upgrade SomePackage + [...] + Found existing installation: SomePackage 1.0 + Uninstalling SomePackage: + Successfully uninstalled SomePackage + Running setup.py install for SomePackage + Successfully installed SomePackage Uninstall a package: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip uninstall SomePackage + Uninstalling SomePackage: + /my/env/lib/pythonx.x/site-packages/somepackage + Proceed (y/n)? y + Successfully uninstalled SomePackage - $ python -m pip uninstall SomePackage - Uninstalling SomePackage: +.. tab:: Windows + + .. code-block:: console + + C:\> py -m pip uninstall SomePackage + Uninstalling SomePackage: /my/env/lib/pythonx.x/site-packages/somepackage - Proceed (y/n)? y - Successfully uninstalled SomePackage - - .. group-tab:: Windows - - .. code-block:: console - - C:\> py -m pip uninstall SomePackage - Uninstalling SomePackage: - /my/env/lib/pythonx.x/site-packages/somepackage - Proceed (y/n)? y - Successfully uninstalled SomePackage - + Proceed (y/n)? y + Successfully uninstalled SomePackage .. _PyPI: https://pypi.org/ diff --git a/docs/html/reference/pip.rst b/docs/html/reference/pip.rst index 9fd42c676..298a1101d 100644 --- a/docs/html/reference/pip.rst +++ b/docs/html/reference/pip.rst @@ -7,19 +7,17 @@ pip Usage ***** -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip [options] - python -m pip [options] +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip [options] + py -m pip [options] Description *********** @@ -232,19 +230,17 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + python setup.py BUILD COMMAND - python setup.py BUILD COMMAND +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py setup.py BUILD COMMAND + py setup.py BUILD COMMAND The options are passed unmodified, and presently offer direct access to the distutils command line. Use of ``--global-option`` and ``--build-option`` diff --git a/docs/html/reference/pip_cache.rst b/docs/html/reference/pip_cache.rst index 35e0dfcad..c443a6f3a 100644 --- a/docs/html/reference/pip_cache.rst +++ b/docs/html/reference/pip_cache.rst @@ -9,15 +9,13 @@ pip cache Usage ***** -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: cache "python -m pip" - .. pip-command-usage:: cache "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: cache "py -m pip" + .. pip-command-usage:: cache "py -m pip" Description *********** diff --git a/docs/html/reference/pip_check.rst b/docs/html/reference/pip_check.rst index d3bb457e1..3b2ecb511 100644 --- a/docs/html/reference/pip_check.rst +++ b/docs/html/reference/pip_check.rst @@ -10,15 +10,13 @@ pip check Usage ===== -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: check "python -m pip" - .. pip-command-usage:: check "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: check "py -m pip" + .. pip-command-usage:: check "py -m pip" Description @@ -32,66 +30,60 @@ Examples #. If all dependencies are compatible: - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip check + No broken requirements found. + $ echo $? + 0 - $ python -m pip check - No broken requirements found. - $ echo $? - 0 + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip check - No broken requirements found. - C:\> echo %errorlevel% - 0 + C:\> py -m pip check + No broken requirements found. + C:\> echo %errorlevel% + 0 #. If a package is missing: - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip check + pyramid 1.5.2 requires WebOb, which is not installed. + $ echo $? + 1 - $ python -m pip check - pyramid 1.5.2 requires WebOb, which is not installed. - $ echo $? - 1 + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip check - pyramid 1.5.2 requires WebOb, which is not installed. - C:\> echo %errorlevel% - 1 + C:\> py -m pip check + pyramid 1.5.2 requires WebOb, which is not installed. + C:\> echo %errorlevel% + 1 #. If a package has the wrong version: - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip check + pyramid 1.5.2 has requirement WebOb>=1.3.1, but you have WebOb 0.8. + $ echo $? + 1 - $ python -m pip check - pyramid 1.5.2 has requirement WebOb>=1.3.1, but you have WebOb 0.8. - $ echo $? - 1 + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip check - pyramid 1.5.2 has requirement WebOb>=1.3.1, but you have WebOb 0.8. - C:\> echo %errorlevel% - 1 + C:\> py -m pip check + pyramid 1.5.2 has requirement WebOb>=1.3.1, but you have WebOb 0.8. + C:\> echo %errorlevel% + 1 diff --git a/docs/html/reference/pip_config.rst b/docs/html/reference/pip_config.rst index d9bf0afc8..14b1ac775 100644 --- a/docs/html/reference/pip_config.rst +++ b/docs/html/reference/pip_config.rst @@ -11,15 +11,13 @@ pip config Usage ===== -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: config "python -m pip" - .. pip-command-usage:: config "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: config "py -m pip" + .. pip-command-usage:: config "py -m pip" Description diff --git a/docs/html/reference/pip_debug.rst b/docs/html/reference/pip_debug.rst index 2ef98228a..a077a169b 100644 --- a/docs/html/reference/pip_debug.rst +++ b/docs/html/reference/pip_debug.rst @@ -10,15 +10,13 @@ pip debug Usage ===== -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: debug "python -m pip" - .. pip-command-usage:: debug "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: debug "py -m pip" + .. pip-command-usage:: debug "py -m pip" .. warning:: diff --git a/docs/html/reference/pip_download.rst b/docs/html/reference/pip_download.rst index 7983bb95b..80acc1942 100644 --- a/docs/html/reference/pip_download.rst +++ b/docs/html/reference/pip_download.rst @@ -11,15 +11,13 @@ pip download Usage ===== -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: download "python -m pip" - .. pip-command-usage:: download "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: download "py -m pip" + .. pip-command-usage:: download "py -m pip" Description @@ -64,23 +62,21 @@ Examples #. Download a package and all of its dependencies - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip download SomePackage + python -m pip download -d . SomePackage # equivalent to above + python -m pip download --no-index --find-links=/tmp/wheelhouse -d /tmp/otherwheelhouse SomePackage - python -m pip download SomePackage - python -m pip download -d . SomePackage # equivalent to above - python -m pip download --no-index --find-links=/tmp/wheelhouse -d /tmp/otherwheelhouse SomePackage + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip download SomePackage - py -m pip download -d . SomePackage # equivalent to above - py -m pip download --no-index --find-links=/tmp/wheelhouse -d /tmp/otherwheelhouse SomePackage + py -m pip download SomePackage + py -m pip download -d . SomePackage # equivalent to above + py -m pip download --no-index --find-links=/tmp/wheelhouse -d /tmp/otherwheelhouse SomePackage #. Download a package and all of its dependencies with OSX specific interpreter constraints. @@ -90,122 +86,114 @@ 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:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip download \ + --only-binary=:all: \ + --platform macosx-10_10_x86_64 \ + --python-version 27 \ + --implementation cp \ + SomePackage - python -m pip download \ - --only-binary=:all: \ - --platform macosx-10_10_x86_64 \ - --python-version 27 \ - --implementation cp \ - SomePackage + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip download ^ - --only-binary=:all: ^ - --platform macosx-10_10_x86_64 ^ - --python-version 27 ^ - --implementation cp ^ - SomePackage + py -m pip download ^ + --only-binary=:all: ^ + --platform macosx-10_10_x86_64 ^ + --python-version 27 ^ + --implementation cp ^ + SomePackage #. Download a package and its dependencies with linux specific constraints. Force the interpreter to be any minor version of py3k, and only accept ``cp34m`` or ``none`` as the abi. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip download \ + --only-binary=:all: \ + --platform linux_x86_64 \ + --python-version 3 \ + --implementation cp \ + --abi cp34m \ + SomePackage - python -m pip download \ - --only-binary=:all: \ - --platform linux_x86_64 \ - --python-version 3 \ - --implementation cp \ - --abi cp34m \ - SomePackage + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip download ^ - --only-binary=:all: ^ - --platform linux_x86_64 ^ - --python-version 3 ^ - --implementation cp ^ - --abi cp34m ^ - SomePackage + py -m pip download ^ + --only-binary=:all: ^ + --platform linux_x86_64 ^ + --python-version 3 ^ + --implementation cp ^ + --abi cp34m ^ + SomePackage #. Force platform, implementation, and abi agnostic deps. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip download \ + --only-binary=:all: \ + --platform any \ + --python-version 3 \ + --implementation py \ + --abi none \ + SomePackage - python -m pip download \ - --only-binary=:all: \ - --platform any \ - --python-version 3 \ - --implementation py \ - --abi none \ - SomePackage + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip download ^ - --only-binary=:all: ^ - --platform any ^ - --python-version 3 ^ - --implementation py ^ - --abi none ^ - SomePackage + py -m pip download ^ + --only-binary=:all: ^ + --platform any ^ + --python-version 3 ^ + --implementation py ^ + --abi none ^ + SomePackage #. Even when overconstrained, this will still correctly fetch the pip universal wheel. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip download \ + --only-binary=:all: \ + --platform linux_x86_64 \ + --python-version 33 \ + --implementation cp \ + --abi cp34m \ + pip>=8 - $ python -m pip download \ - --only-binary=:all: \ - --platform linux_x86_64 \ - --python-version 33 \ - --implementation cp \ - --abi cp34m \ - pip>=8 + .. code-block:: console - .. code-block:: console + $ ls pip-8.1.1-py2.py3-none-any.whl + pip-8.1.1-py2.py3-none-any.whl - $ ls pip-8.1.1-py2.py3-none-any.whl - pip-8.1.1-py2.py3-none-any.whl + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console + C:\> py -m pip download ^ + --only-binary=:all: ^ + --platform linux_x86_64 ^ + --python-version 33 ^ + --implementation cp ^ + --abi cp34m ^ + pip>=8 - C:\> py -m pip download ^ - --only-binary=:all: ^ - --platform linux_x86_64 ^ - --python-version 33 ^ - --implementation cp ^ - --abi cp34m ^ - pip>=8 + .. code-block:: console - .. code-block:: console - - C:\> dir pip-8.1.1-py2.py3-none-any.whl - pip-8.1.1-py2.py3-none-any.whl + C:\> dir pip-8.1.1-py2.py3-none-any.whl + pip-8.1.1-py2.py3-none-any.whl diff --git a/docs/html/reference/pip_freeze.rst b/docs/html/reference/pip_freeze.rst index d4ed00bfb..152823a08 100644 --- a/docs/html/reference/pip_freeze.rst +++ b/docs/html/reference/pip_freeze.rst @@ -11,15 +11,13 @@ pip freeze Usage ===== -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: freeze "python -m pip" - .. pip-command-usage:: freeze "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: freeze "py -m pip" + .. pip-command-usage:: freeze "py -m pip" Description @@ -39,45 +37,40 @@ Examples #. Generate output suitable for a requirements file. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip freeze + docutils==0.11 + Jinja2==2.7.2 + MarkupSafe==0.19 + Pygments==1.6 + Sphinx==1.2.2 - $ python -m pip freeze - docutils==0.11 - Jinja2==2.7.2 - MarkupSafe==0.19 - Pygments==1.6 - Sphinx==1.2.2 + .. tab:: Windows - .. group-tab:: Windows - - .. code-block:: console - - C:\> py -m pip freeze - docutils==0.11 - Jinja2==2.7.2 - MarkupSafe==0.19 - Pygments==1.6 - Sphinx==1.2.2 + .. code-block:: console + C:\> py -m pip freeze + docutils==0.11 + Jinja2==2.7.2 + MarkupSafe==0.19 + Pygments==1.6 + Sphinx==1.2.2 #. Generate a requirements file and then install from it in another environment. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + env1/bin/python -m pip freeze > requirements.txt + env2/bin/python -m pip install -r requirements.txt - env1/bin/python -m pip freeze > requirements.txt - env2/bin/python -m pip install -r requirements.txt + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - env1\bin\python -m pip freeze > requirements.txt - env2\bin\python -m pip install -r requirements.txt + env1\bin\python -m pip freeze > requirements.txt + env2\bin\python -m pip install -r requirements.txt diff --git a/docs/html/reference/pip_hash.rst b/docs/html/reference/pip_hash.rst index 71e1cf4be..e9f5964dd 100644 --- a/docs/html/reference/pip_hash.rst +++ b/docs/html/reference/pip_hash.rst @@ -10,15 +10,13 @@ pip hash Usage ===== -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: hash "python -m pip" - .. pip-command-usage:: hash "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: hash "py -m pip" + .. pip-command-usage:: hash "py -m pip" Description @@ -49,30 +47,28 @@ Example Compute the hash of a downloaded archive: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip download SomePackage + Collecting SomePackage + Downloading SomePackage-2.2.tar.gz + Saved ./pip_downloads/SomePackage-2.2.tar.gz + Successfully downloaded SomePackage + $ python -m pip hash ./pip_downloads/SomePackage-2.2.tar.gz + ./pip_downloads/SomePackage-2.2.tar.gz: + --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 - $ python -m pip download SomePackage - Collecting SomePackage - Downloading SomePackage-2.2.tar.gz - Saved ./pip_downloads/SomePackage-2.2.tar.gz - Successfully downloaded SomePackage - $ python -m pip hash ./pip_downloads/SomePackage-2.2.tar.gz - ./pip_downloads/SomePackage-2.2.tar.gz: - --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip download SomePackage - Collecting SomePackage - Downloading SomePackage-2.2.tar.gz - Saved ./pip_downloads/SomePackage-2.2.tar.gz - Successfully downloaded SomePackage - C:\> py -m pip hash ./pip_downloads/SomePackage-2.2.tar.gz - ./pip_downloads/SomePackage-2.2.tar.gz: - --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 + C:\> py -m pip download SomePackage + Collecting SomePackage + Downloading SomePackage-2.2.tar.gz + Saved ./pip_downloads/SomePackage-2.2.tar.gz + Successfully downloaded SomePackage + C:\> py -m pip hash ./pip_downloads/SomePackage-2.2.tar.gz + ./pip_downloads/SomePackage-2.2.tar.gz: + --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 diff --git a/docs/html/reference/pip_install.rst b/docs/html/reference/pip_install.rst index cb97c8ee0..7d6b5471a 100644 --- a/docs/html/reference/pip_install.rst +++ b/docs/html/reference/pip_install.rst @@ -10,15 +10,13 @@ pip install Usage ===== -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: install "python -m pip" - .. pip-command-usage:: install "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: install "py -m pip" + .. pip-command-usage:: install "py -m pip" @@ -100,31 +98,29 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip install quux + ... + Installing collected packages baz, bar, foo, quux - $ python -m pip install quux - ... - Installing collected packages baz, bar, foo, quux + $ python -m pip install bar + ... + Installing collected packages foo, baz, bar - $ python -m pip install bar - ... - Installing collected packages foo, baz, bar +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console + C:\> py -m pip install quux + ... + Installing collected packages baz, bar, foo, quux - C:\> py -m pip install quux - ... - Installing collected packages baz, bar, foo, quux - - C:\> py -m pip install bar - ... - Installing collected packages foo, baz, bar + C:\> py -m pip install bar + ... + Installing collected packages foo, baz, bar Prior to v6.1.0, pip made no commitments about install order. @@ -416,19 +412,17 @@ If your repository layout is:: Then, to install from this repository, the syntax would be: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir" - python -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir" +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir" + py -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir" Git @@ -677,35 +671,33 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip install --require-hashes -r requirements.txt + ... + Hashes are required in --require-hashes mode (implicitly on when a hash is + specified for any package). These requirements were missing hashes, + leaving them open to tampering. These are the hashes the downloaded + archives actually had. You can add lines like these to your requirements + files to prevent tampering. + pyelasticsearch==1.0 --hash=sha256:44ddfb1225054d7d6b1d02e9338e7d4809be94edbe9929a2ec0807d38df993fa + more-itertools==2.2 --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 - $ python -m pip install --require-hashes -r requirements.txt - ... - Hashes are required in --require-hashes mode (implicitly on when a hash is - specified for any package). These requirements were missing hashes, - leaving them open to tampering. These are the hashes the downloaded - archives actually had. You can add lines like these to your requirements - files to prevent tampering. - pyelasticsearch==1.0 --hash=sha256:44ddfb1225054d7d6b1d02e9338e7d4809be94edbe9929a2ec0807d38df993fa - more-itertools==2.2 --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip install --require-hashes -r requirements.txt - ... - Hashes are required in --require-hashes mode (implicitly on when a hash is - specified for any package). These requirements were missing hashes, - leaving them open to tampering. These are the hashes the downloaded - archives actually had. You can add lines like these to your requirements - files to prevent tampering. - pyelasticsearch==1.0 --hash=sha256:44ddfb1225054d7d6b1d02e9338e7d4809be94edbe9929a2ec0807d38df993fa - more-itertools==2.2 --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 + C:\> py -m pip install --require-hashes -r requirements.txt + ... + Hashes are required in --require-hashes mode (implicitly on when a hash is + specified for any package). These requirements were missing hashes, + leaving them open to tampering. These are the hashes the downloaded + archives actually had. You can add lines like these to your requirements + files to prevent tampering. + pyelasticsearch==1.0 --hash=sha256:44ddfb1225054d7d6b1d02e9338e7d4809be94edbe9929a2ec0807d38df993fa + more-itertools==2.2 --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 This can be useful in deploy scripts, to ensure that the author of the @@ -736,54 +728,50 @@ Hash-checking mode also works with :ref:`pip download` and :ref:`pip wheel`. A .. warning:: - Beware of the ``setup_requires`` keyword arg in :file:`setup.py`. The - (rare) packages that use it will cause those dependencies to be downloaded - by setuptools directly, skipping pip's hash-checking. If you need to use - such a package, see :ref:`Controlling - setup_requires`. + Beware of the ``setup_requires`` keyword arg in :file:`setup.py`. The + (rare) packages that use it will cause those dependencies to be downloaded + by setuptools directly, skipping pip's hash-checking. If you need to use + such a package, see :ref:`Controlling + setup_requires`. .. warning:: - Be careful not to nullify all your security work when you install your - actual project by using setuptools directly: for example, by calling - ``python setup.py install``, ``python setup.py develop``, or - ``easy_install``. Setuptools will happily go out and download, unchecked, - anything you missed in your requirements file—and it’s easy to miss things - as your project evolves. To be safe, install your project using pip and - :ref:`--no-deps `. + Be careful not to nullify all your security work when you install your + actual project by using setuptools directly: for example, by calling + ``python setup.py install``, ``python setup.py develop``, or + ``easy_install``. Setuptools will happily go out and download, unchecked, + anything you missed in your requirements file—and it’s easy to miss things + as your project evolves. To be safe, install your project using pip and + :ref:`--no-deps `. - Instead of ``python setup.py develop``, use... + Instead of ``python setup.py develop``, use... - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install --no-deps -e . - python -m pip install --no-deps -e . + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install --no-deps -e . + py -m pip install --no-deps -e . - Instead of ``python setup.py install``, use... + Instead of ``python setup.py install``, use... - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install --no-deps . - python -m pip install --no-deps . + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install --no-deps . + py -m pip install --no-deps . Hashes from PyPI ^^^^^^^^^^^^^^^^ @@ -803,20 +791,17 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install path/to/SomeProject - python -m pip install path/to/SomeProject +.. tab:: Windows - .. group-tab:: Windows - - .. code-block:: shell - - py -m pip install path/to/SomeProject + .. 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 @@ -835,21 +820,19 @@ installs. You can install local projects or VCS projects in "editable" mode: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install -e path/to/SomeProject + python -m pip install -e git+http://repo/my_project.git#egg=SomeProject - python -m pip install -e path/to/SomeProject - python -m pip install -e git+http://repo/my_project.git#egg=SomeProject +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install -e path/to/SomeProject - py -m pip install -e git+http://repo/my_project.git#egg=SomeProject + py -m pip install -e path/to/SomeProject + py -m pip install -e git+http://repo/my_project.git#egg=SomeProject (See the :ref:`VCS Support` section above for more information on VCS-related syntax.) @@ -957,292 +940,256 @@ Examples #. Install ``SomePackage`` and its dependencies from `PyPI`_ using :ref:`Requirement Specifiers` - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install SomePackage # latest version + python -m pip install SomePackage==1.0.4 # specific version + python -m pip install 'SomePackage>=1.0.4' # minimum version - python -m pip install SomePackage # latest version - python -m pip install SomePackage==1.0.4 # specific version - python -m pip install 'SomePackage>=1.0.4' # minimum version + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install SomePackage # latest version - py -m pip install SomePackage==1.0.4 # specific version - py -m pip install 'SomePackage>=1.0.4' # minimum version + py -m pip install SomePackage # latest version + py -m pip install SomePackage==1.0.4 # specific version + py -m pip install 'SomePackage>=1.0.4' # minimum version #. Install a list of requirements specified in a file. See the :ref:`Requirements files `. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install -r requirements.txt - python -m pip install -r requirements.txt + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install -r requirements.txt + py -m pip install -r requirements.txt #. Upgrade an already installed ``SomePackage`` to the latest from PyPI. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install --upgrade SomePackage - python -m pip install --upgrade SomePackage + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install --upgrade SomePackage + py -m pip install --upgrade SomePackage #. Install a local project in "editable" mode. See the section on :ref:`Editable Installs `. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install -e . # project in current directory + python -m pip install -e path/to/project # project in another directory - python -m pip install -e . # project in current directory - python -m pip install -e path/to/project # project in another directory + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install -e . # project in current directory - py -m pip install -e path/to/project # project in another directory + py -m pip install -e . # project in current directory + py -m pip install -e path/to/project # project in another directory #. Install a project from VCS - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1 - python -m pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1 + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1 + py -m pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1 #. Install a project from VCS in "editable" mode. See the sections on :ref:`VCS Support ` and :ref:`Editable Installs `. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git + python -m pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial + python -m python -m pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn + 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 - python -m pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git - python -m pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial - python -m python -m pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn - 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 + .. tab:: Windows - .. group-tab:: Windows - - .. code-block:: shell - - py -m pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git - py -m pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial - py -m pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn - 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 + .. code-block:: shell + py -m pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git + py -m pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial + py -m pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn + 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:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install SomePackage[PDF] + python -m pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@master#subdirectory=subdir_path" + python -m pip install .[PDF] # project in current directory + python -m pip install SomePackage[PDF]==3.0 + python -m pip install SomePackage[PDF,EPUB] # multiple extras - python -m pip install SomePackage[PDF] - python -m pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@master#subdirectory=subdir_path" - python -m pip install .[PDF] # project in current directory - python -m pip install SomePackage[PDF]==3.0 - python -m pip install SomePackage[PDF,EPUB] # multiple extras + .. tab:: Windows - .. group-tab:: Windows - - .. code-block:: shell - - py -m pip install SomePackage[PDF] - py -m pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@master#subdirectory=subdir_path" - py -m pip install .[PDF] # project in current directory - py -m pip install SomePackage[PDF]==3.0 - py -m pip install SomePackage[PDF,EPUB] # multiple extras + .. code-block:: shell + py -m pip install SomePackage[PDF] + py -m pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@master#subdirectory=subdir_path" + py -m pip install .[PDF] # project in current directory + py -m pip install SomePackage[PDF]==3.0 + py -m pip install SomePackage[PDF,EPUB] # multiple extras #. Install a particular source archive file. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. 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 - python -m pip install ./downloads/SomePackage-1.0.4.tar.gz - python -m pip install http://my.package.repo/SomePackage-1.0.4.zip + .. tab:: Windows - .. group-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 + .. 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:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + 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/SomeProject-1.2.3-py33-none-any.whl" + python -m pip install SomeProject@http://my.package.repo/1.2.3.tar.gz - 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/SomeProject-1.2.3-py33-none-any.whl" - python -m pip install SomeProject@http://my.package.repo/1.2.3.tar.gz + .. tab:: Windows - .. group-tab:: Windows - - .. code-block:: shell - - 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/SomeProject-1.2.3-py33-none-any.whl" - py -m pip install SomeProject@http://my.package.repo/1.2.3.tar.gz + .. code-block:: shell + 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/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:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install --index-url http://my.package.repo/simple/ SomePackage - python -m pip install --index-url http://my.package.repo/simple/ SomePackage + .. tab:: Windows - .. group-tab:: Windows - - .. code-block:: shell - - py -m pip install --index-url http://my.package.repo/simple/ SomePackage + .. 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:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install --extra-index-url http://my.package.repo/simple SomePackage - python -m pip install --extra-index-url http://my.package.repo/simple SomePackage + .. tab:: Windows - .. group-tab:: Windows - - .. code-block:: shell - - py -m pip install --extra-index-url http://my.package.repo/simple SomePackage + .. 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:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install --no-index --find-links=file:///local/dir/ SomePackage + python -m pip install --no-index --find-links=/local/dir/ SomePackage + python -m pip install --no-index --find-links=relative/dir/ SomePackage - python -m pip install --no-index --find-links=file:///local/dir/ SomePackage - python -m pip install --no-index --find-links=/local/dir/ SomePackage - python -m pip install --no-index --find-links=relative/dir/ SomePackage + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install --no-index --find-links=file:///local/dir/ SomePackage - py -m pip install --no-index --find-links=/local/dir/ SomePackage - py -m pip install --no-index --find-links=relative/dir/ SomePackage + py -m pip install --no-index --find-links=file:///local/dir/ SomePackage + py -m pip install --no-index --find-links=/local/dir/ SomePackage + py -m pip install --no-index --find-links=relative/dir/ SomePackage #. Find pre-release and development versions, in addition to stable versions. By default, pip only finds stable versions. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install --pre SomePackage - python -m pip install --pre SomePackage + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install --pre SomePackage + py -m pip install --pre SomePackage #. Install packages from source. Do not use any binary packages - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install SomePackage1 SomePackage2 --no-binary :all: - python -m pip install SomePackage1 SomePackage2 --no-binary :all: + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install SomePackage1 SomePackage2 --no-binary :all: + py -m pip install SomePackage1 SomePackage2 --no-binary :all: Specify ``SomePackage1`` to be installed from source: - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1 - python -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1 + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1 + py -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1 ---- diff --git a/docs/html/reference/pip_list.rst b/docs/html/reference/pip_list.rst index 1489ed751..bda322a86 100644 --- a/docs/html/reference/pip_list.rst +++ b/docs/html/reference/pip_list.rst @@ -10,15 +10,13 @@ pip list Usage ===== -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: list "python -m pip" - .. pip-command-usage:: list "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: list "py -m pip" + .. pip-command-usage:: list "py -m pip" Description @@ -40,182 +38,165 @@ Examples #. List installed packages. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip list + docutils (0.10) + Jinja2 (2.7.2) + MarkupSafe (0.18) + Pygments (1.6) + Sphinx (1.2.1) - $ python -m pip list - docutils (0.10) - Jinja2 (2.7.2) - MarkupSafe (0.18) - Pygments (1.6) - Sphinx (1.2.1) + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip list - docutils (0.10) - Jinja2 (2.7.2) - MarkupSafe (0.18) - Pygments (1.6) - Sphinx (1.2.1) + C:\> py -m pip list + docutils (0.10) + Jinja2 (2.7.2) + MarkupSafe (0.18) + Pygments (1.6) + Sphinx (1.2.1) #. List outdated packages (excluding editables), and the latest version available. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip list --outdated + docutils (Current: 0.10 Latest: 0.11) + Sphinx (Current: 1.2.1 Latest: 1.2.2) - $ python -m pip list --outdated - docutils (Current: 0.10 Latest: 0.11) - Sphinx (Current: 1.2.1 Latest: 1.2.2) + .. tab:: Windows - .. group-tab:: Windows - - .. code-block:: console - - C:\> py -m pip list --outdated - docutils (Current: 0.10 Latest: 0.11) - Sphinx (Current: 1.2.1 Latest: 1.2.2) + .. code-block:: console + C:\> py -m pip list --outdated + docutils (Current: 0.10 Latest: 0.11) + Sphinx (Current: 1.2.1 Latest: 1.2.2) #. List installed packages with column formatting. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip list --format columns + Package Version + ------- ------- + docopt 0.6.2 + idlex 1.13 + jedi 0.9.0 - $ python -m pip list --format columns - Package Version - ------- ------- - docopt 0.6.2 - idlex 1.13 - jedi 0.9.0 + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip list --format columns - Package Version - ------- ------- - docopt 0.6.2 - idlex 1.13 - jedi 0.9.0 + C:\> py -m pip list --format columns + Package Version + ------- ------- + docopt 0.6.2 + idlex 1.13 + jedi 0.9.0 #. List outdated packages with column formatting. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip list -o --format columns + Package Version Latest Type + ---------- ------- ------ ----- + retry 0.8.1 0.9.1 wheel + setuptools 20.6.7 21.0.0 wheel - $ python -m pip list -o --format columns - Package Version Latest Type - ---------- ------- ------ ----- - retry 0.8.1 0.9.1 wheel - setuptools 20.6.7 21.0.0 wheel + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip list -o --format columns - Package Version Latest Type - ---------- ------- ------ ----- - retry 0.8.1 0.9.1 wheel - setuptools 20.6.7 21.0.0 wheel + C:\> py -m pip list -o --format columns + Package Version Latest Type + ---------- ------- ------ ----- + retry 0.8.1 0.9.1 wheel + setuptools 20.6.7 21.0.0 wheel #. List packages that are not dependencies of other packages. Can be combined with other options. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip list --outdated --not-required + docutils (Current: 0.10 Latest: 0.11) - $ python -m pip list --outdated --not-required - docutils (Current: 0.10 Latest: 0.11) + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip list --outdated --not-required - docutils (Current: 0.10 Latest: 0.11) + C:\> py -m pip list --outdated --not-required + docutils (Current: 0.10 Latest: 0.11) #. Use legacy formatting - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip list --format=legacy + colorama (0.3.7) + docopt (0.6.2) + idlex (1.13) + jedi (0.9.0) - $ python -m pip list --format=legacy - colorama (0.3.7) - docopt (0.6.2) - idlex (1.13) - jedi (0.9.0) + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip list --format=legacy - colorama (0.3.7) - docopt (0.6.2) - idlex (1.13) - jedi (0.9.0) + C:\> py -m pip list --format=legacy + colorama (0.3.7) + docopt (0.6.2) + idlex (1.13) + jedi (0.9.0) #. Use json formatting - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip list --format=json + [{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ... - $ python -m pip list --format=json - [{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ... + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip list --format=json - [{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ... + C:\> py -m pip list --format=json + [{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ... #. Use freeze formatting - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip list --format=freeze + colorama==0.3.7 + docopt==0.6.2 + idlex==1.13 + jedi==0.9.0 - $ python -m pip list --format=freeze - colorama==0.3.7 - docopt==0.6.2 - idlex==1.13 - jedi==0.9.0 + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip list --format=freeze - colorama==0.3.7 - docopt==0.6.2 - idlex==1.13 - jedi==0.9.0 + C:\> py -m pip list --format=freeze + colorama==0.3.7 + docopt==0.6.2 + idlex==1.13 + jedi==0.9.0 diff --git a/docs/html/reference/pip_search.rst b/docs/html/reference/pip_search.rst index fba629593..2d1a2aa69 100644 --- a/docs/html/reference/pip_search.rst +++ b/docs/html/reference/pip_search.rst @@ -10,15 +10,13 @@ pip search Usage ===== -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: search "python -m pip" - .. pip-command-usage:: search "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: search "py -m pip" + .. pip-command-usage:: search "py -m pip" Description @@ -38,20 +36,18 @@ Examples #. Search for "peppercorn" - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip search peppercorn + pepperedform - Helpers for using peppercorn with formprocess. + peppercorn - A library for converting a token stream into [...] - $ python -m pip search peppercorn - pepperedform - Helpers for using peppercorn with formprocess. - peppercorn - A library for converting a token stream into [...] + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip search peppercorn - pepperedform - Helpers for using peppercorn with formprocess. - peppercorn - A library for converting a token stream into [...] + C:\> py -m pip search peppercorn + pepperedform - Helpers for using peppercorn with formprocess. + peppercorn - A library for converting a token stream into [...] diff --git a/docs/html/reference/pip_show.rst b/docs/html/reference/pip_show.rst index 6bd3718b9..bcbe4e820 100644 --- a/docs/html/reference/pip_show.rst +++ b/docs/html/reference/pip_show.rst @@ -10,15 +10,13 @@ pip show Usage ===== -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: show "python -m pip" - .. pip-command-usage:: show "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: show "py -m pip" + .. pip-command-usage:: show "py -m pip" Description @@ -38,124 +36,120 @@ Examples #. Show information about a package: - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip show sphinx + Name: Sphinx + Version: 1.4.5 + Summary: Python documentation generator + Home-page: http://sphinx-doc.org/ + Author: Georg Brandl + Author-email: georg@python.org + License: BSD + Location: /my/env/lib/python2.7/site-packages + Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six - $ python -m pip show sphinx - Name: Sphinx - Version: 1.4.5 - Summary: Python documentation generator - Home-page: http://sphinx-doc.org/ - Author: Georg Brandl - Author-email: georg@python.org - License: BSD - Location: /my/env/lib/python2.7/site-packages - Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip show sphinx - Name: Sphinx - Version: 1.4.5 - Summary: Python documentation generator - Home-page: http://sphinx-doc.org/ - Author: Georg Brandl - Author-email: georg@python.org - License: BSD - Location: /my/env/lib/python2.7/site-packages - Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six + C:\> py -m pip show sphinx + Name: Sphinx + Version: 1.4.5 + Summary: Python documentation generator + Home-page: http://sphinx-doc.org/ + Author: Georg Brandl + Author-email: georg@python.org + License: BSD + Location: /my/env/lib/python2.7/site-packages + Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six #. Show all information about a package - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip show --verbose sphinx + Name: Sphinx + Version: 1.4.5 + Summary: Python documentation generator + Home-page: http://sphinx-doc.org/ + Author: Georg Brandl + Author-email: georg@python.org + License: BSD + Location: /my/env/lib/python2.7/site-packages + Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six + Metadata-Version: 2.0 + Installer: + Classifiers: + Development Status :: 5 - Production/Stable + Environment :: Console + Environment :: Web Environment + Intended Audience :: Developers + Intended Audience :: Education + License :: OSI Approved :: BSD License + Operating System :: OS Independent + Programming Language :: Python + Programming Language :: Python :: 2 + Programming Language :: Python :: 3 + Framework :: Sphinx + Framework :: Sphinx :: Extension + Framework :: Sphinx :: Theme + Topic :: Documentation + Topic :: Documentation :: Sphinx + Topic :: Text Processing + Topic :: Utilities + Entry-points: + [console_scripts] + sphinx-apidoc = sphinx.apidoc:main + sphinx-autogen = sphinx.ext.autosummary.generate:main + sphinx-build = sphinx:main + sphinx-quickstart = sphinx.quickstart:main + [distutils.commands] + build_sphinx = sphinx.setup_command:BuildDoc - $ python -m pip show --verbose sphinx - Name: Sphinx - Version: 1.4.5 - Summary: Python documentation generator - Home-page: http://sphinx-doc.org/ - Author: Georg Brandl - Author-email: georg@python.org - License: BSD - Location: /my/env/lib/python2.7/site-packages - Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six - Metadata-Version: 2.0 - Installer: - Classifiers: - Development Status :: 5 - Production/Stable - Environment :: Console - Environment :: Web Environment - Intended Audience :: Developers - Intended Audience :: Education - License :: OSI Approved :: BSD License - Operating System :: OS Independent - Programming Language :: Python - Programming Language :: Python :: 2 - Programming Language :: Python :: 3 - Framework :: Sphinx - Framework :: Sphinx :: Extension - Framework :: Sphinx :: Theme - Topic :: Documentation - Topic :: Documentation :: Sphinx - Topic :: Text Processing - Topic :: Utilities - Entry-points: - [console_scripts] - sphinx-apidoc = sphinx.apidoc:main - sphinx-autogen = sphinx.ext.autosummary.generate:main - sphinx-build = sphinx:main - sphinx-quickstart = sphinx.quickstart:main - [distutils.commands] - build_sphinx = sphinx.setup_command:BuildDoc + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip show --verbose sphinx - Name: Sphinx - Version: 1.4.5 - Summary: Python documentation generator - Home-page: http://sphinx-doc.org/ - Author: Georg Brandl - Author-email: georg@python.org - License: BSD - Location: /my/env/lib/python2.7/site-packages - Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six - Metadata-Version: 2.0 - Installer: - Classifiers: - Development Status :: 5 - Production/Stable - Environment :: Console - Environment :: Web Environment - Intended Audience :: Developers - Intended Audience :: Education - License :: OSI Approved :: BSD License - Operating System :: OS Independent - Programming Language :: Python - Programming Language :: Python :: 2 - Programming Language :: Python :: 3 - Framework :: Sphinx - Framework :: Sphinx :: Extension - Framework :: Sphinx :: Theme - Topic :: Documentation - Topic :: Documentation :: Sphinx - Topic :: Text Processing - Topic :: Utilities - Entry-points: - [console_scripts] - sphinx-apidoc = sphinx.apidoc:main - sphinx-autogen = sphinx.ext.autosummary.generate:main - sphinx-build = sphinx:main - sphinx-quickstart = sphinx.quickstart:main - [distutils.commands] - build_sphinx = sphinx.setup_command:BuildDoc + C:\> py -m pip show --verbose sphinx + Name: Sphinx + Version: 1.4.5 + Summary: Python documentation generator + Home-page: http://sphinx-doc.org/ + Author: Georg Brandl + Author-email: georg@python.org + License: BSD + Location: /my/env/lib/python2.7/site-packages + Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six + Metadata-Version: 2.0 + Installer: + Classifiers: + Development Status :: 5 - Production/Stable + Environment :: Console + Environment :: Web Environment + Intended Audience :: Developers + Intended Audience :: Education + License :: OSI Approved :: BSD License + Operating System :: OS Independent + Programming Language :: Python + Programming Language :: Python :: 2 + Programming Language :: Python :: 3 + Framework :: Sphinx + Framework :: Sphinx :: Extension + Framework :: Sphinx :: Theme + Topic :: Documentation + Topic :: Documentation :: Sphinx + Topic :: Text Processing + Topic :: Utilities + Entry-points: + [console_scripts] + sphinx-apidoc = sphinx.apidoc:main + sphinx-autogen = sphinx.ext.autosummary.generate:main + sphinx-build = sphinx:main + sphinx-quickstart = sphinx.quickstart:main + [distutils.commands] + build_sphinx = sphinx.setup_command:BuildDoc diff --git a/docs/html/reference/pip_uninstall.rst b/docs/html/reference/pip_uninstall.rst index 8b31c5673..fbbeddd45 100644 --- a/docs/html/reference/pip_uninstall.rst +++ b/docs/html/reference/pip_uninstall.rst @@ -10,15 +10,13 @@ pip uninstall Usage ===== -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: uninstall "python -m pip" - .. pip-command-usage:: uninstall "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: uninstall "py -m pip" + .. pip-command-usage:: uninstall "py -m pip" Description @@ -38,26 +36,24 @@ Examples #. Uninstall a package. - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip uninstall simplejson + Uninstalling simplejson: + /home/me/env/lib/python2.7/site-packages/simplejson + /home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info + Proceed (y/n)? y + Successfully uninstalled simplejson - $ python -m pip uninstall simplejson - Uninstalling simplejson: - /home/me/env/lib/python2.7/site-packages/simplejson - /home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info - Proceed (y/n)? y - Successfully uninstalled simplejson + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip uninstall simplejson - Uninstalling simplejson: - /home/me/env/lib/python2.7/site-packages/simplejson - /home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info - Proceed (y/n)? y - Successfully uninstalled simplejson + C:\> py -m pip uninstall simplejson + Uninstalling simplejson: + /home/me/env/lib/python2.7/site-packages/simplejson + /home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info + Proceed (y/n)? y + Successfully uninstalled simplejson diff --git a/docs/html/reference/pip_wheel.rst b/docs/html/reference/pip_wheel.rst index c1bdf37f8..f6430bfed 100644 --- a/docs/html/reference/pip_wheel.rst +++ b/docs/html/reference/pip_wheel.rst @@ -11,15 +11,13 @@ pip wheel Usage ===== -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. pip-command-usage:: wheel "python -m pip" - .. pip-command-usage:: wheel "python -m pip" +.. tab:: Windows - .. group-tab:: Windows - - .. pip-command-usage:: wheel "py -m pip" + .. pip-command-usage:: wheel "py -m pip" Description @@ -34,19 +32,17 @@ Build System Interface In order for pip to build a wheel, ``setup.py`` must implement the ``bdist_wheel`` command with the following syntax: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python setup.py bdist_wheel -d TARGET - python setup.py bdist_wheel -d TARGET +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py setup.py bdist_wheel -d TARGET + py setup.py bdist_wheel -d TARGET This command must create a wheel compatible with the invoking Python @@ -62,19 +58,17 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip wheel --global-option bdist_ext --global-option -DFOO wheel - python -m pip wheel --global-option bdist_ext --global-option -DFOO wheel +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip wheel --global-option bdist_ext --global-option -DFOO wheel + py -m pip wheel --global-option bdist_ext --global-option -DFOO wheel will result in a build command of @@ -103,34 +97,30 @@ Examples #. Build wheels for a requirement (and all its dependencies), and then install - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip wheel --wheel-dir=/tmp/wheelhouse SomePackage + python -m pip install --no-index --find-links=/tmp/wheelhouse SomePackage - python -m pip wheel --wheel-dir=/tmp/wheelhouse SomePackage - python -m pip install --no-index --find-links=/tmp/wheelhouse SomePackage + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip wheel --wheel-dir=/tmp/wheelhouse SomePackage - py -m pip install --no-index --find-links=/tmp/wheelhouse SomePackage + py -m pip wheel --wheel-dir=/tmp/wheelhouse SomePackage + py -m pip install --no-index --find-links=/tmp/wheelhouse SomePackage #. Build a wheel for a package from source - .. tabs:: + .. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip wheel --no-binary SomePackage SomePackage - python -m pip wheel --no-binary SomePackage SomePackage + .. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip wheel --no-binary SomePackage SomePackage + py -m pip wheel --no-binary SomePackage SomePackage diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index a2d13c433..3c9cfec63 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -11,26 +11,24 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip - python -m pip + ``python -m pip`` executes pip using the Python interpreter you + specified as python. So ``/usr/bin/python3.7 -m pip`` means + you are executing pip for your interpreter located at /usr/bin/python3.7. - ``python -m pip`` executes pip using the Python interpreter you - specified as python. So ``/usr/bin/python3.7 -m pip`` means - you are executing pip for your interpreter located at /usr/bin/python3.7. +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell + py -m pip - py -m pip - - ``py -m pip`` executes pip using the latest Python interpreter you - have installed. For more details, read the `Python Windows launcher`_ docs. + ``py -m pip`` executes pip using the latest Python interpreter you + have installed. For more details, read the `Python Windows launcher`_ docs. Installing Packages @@ -43,23 +41,21 @@ directly from distribution files. The most common scenario is to install from `PyPI`_ using :ref:`Requirement Specifiers` -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install SomePackage # latest version + python -m pip install SomePackage==1.0.4 # specific version + python -m pip install 'SomePackage>=1.0.4' # minimum version - python -m pip install SomePackage # latest version - python -m pip install SomePackage==1.0.4 # specific version - python -m pip install 'SomePackage>=1.0.4' # minimum version +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install SomePackage # latest version - py -m pip install SomePackage==1.0.4 # specific version - py -m pip install 'SomePackage>=1.0.4' # minimum version + py -m pip install SomePackage # latest version + py -m pip install SomePackage==1.0.4 # specific version + py -m pip install 'SomePackage>=1.0.4' # minimum version For more information and examples, see the :ref:`pip install` reference. @@ -162,19 +158,17 @@ Requirements Files "Requirements files" are files containing a list of items to be installed using :ref:`pip install` like so: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install -r requirements.txt - python -m pip install -r requirements.txt +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install -r requirements.txt + py -m pip install -r requirements.txt Details on the format of the files are here: :ref:`Requirements File Format`. @@ -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,19 +262,17 @@ installation of the package. Use a constraints file like so: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install -c constraints.txt - python -m pip install -c constraints.txt +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install -c constraints.txt + py -m pip install -c constraints.txt Constraints files are used for exactly the same reason as requirements files when you don't know exactly what things you want to install. For instance, say @@ -320,19 +310,17 @@ archives. To install directly from a wheel archive: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install SomePackage-1.0-py2.py3-none-any.whl - python -m pip install SomePackage-1.0-py2.py3-none-any.whl +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install SomePackage-1.0-py2.py3-none-any.whl + py -m pip install SomePackage-1.0-py2.py3-none-any.whl For the cases where wheels are not available, pip offers :ref:`pip wheel` as a @@ -345,38 +333,34 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install wheel + python -m pip wheel --wheel-dir=/local/wheels -r requirements.txt - python -m pip install wheel - python -m pip wheel --wheel-dir=/local/wheels -r requirements.txt +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install wheel - py -m pip wheel --wheel-dir=/local/wheels -r requirements.txt + py -m pip install wheel + py -m pip wheel --wheel-dir=/local/wheels -r requirements.txt And *then* to install those requirements just using your local directory of wheels (and not from PyPI): -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install --no-index --find-links=/local/wheels -r requirements.txt - python -m pip install --no-index --find-links=/local/wheels -r requirements.txt +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install --no-index --find-links=/local/wheels -r requirements.txt + py -m pip install --no-index --find-links=/local/wheels -r requirements.txt Uninstalling Packages @@ -384,19 +368,17 @@ Uninstalling Packages pip is able to uninstall most packages like so: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip uninstall SomePackage - python -m pip uninstall SomePackage +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip uninstall SomePackage + py -m pip uninstall SomePackage pip also performs an automatic uninstall of an old version of a package @@ -410,75 +392,68 @@ Listing Packages To list installed packages: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip list + docutils (0.9.1) + Jinja2 (2.6) + Pygments (1.5) + Sphinx (1.1.2) - $ python -m pip list - docutils (0.9.1) - Jinja2 (2.6) - Pygments (1.5) - Sphinx (1.1.2) +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip list - docutils (0.9.1) - Jinja2 (2.6) - Pygments (1.5) - Sphinx (1.1.2) + C:\> py -m pip list + docutils (0.9.1) + Jinja2 (2.6) + Pygments (1.5) + Sphinx (1.1.2) To list outdated packages, and show the latest version available: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip list --outdated + docutils (Current: 0.9.1 Latest: 0.10) + Sphinx (Current: 1.1.2 Latest: 1.1.3) - $ python -m pip list --outdated - docutils (Current: 0.9.1 Latest: 0.10) - Sphinx (Current: 1.1.2 Latest: 1.1.3) +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip list --outdated - docutils (Current: 0.9.1 Latest: 0.10) - Sphinx (Current: 1.1.2 Latest: 1.1.3) + C:\> py -m pip list --outdated + docutils (Current: 0.9.1 Latest: 0.10) + Sphinx (Current: 1.1.2 Latest: 1.1.3) To show details about an installed package: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip show sphinx + --- + Name: Sphinx + Version: 1.1.3 + Location: /my/env/lib/pythonx.x/site-packages + Requires: Pygments, Jinja2, docutils - $ python -m pip show sphinx - --- - Name: Sphinx - Version: 1.1.3 - Location: /my/env/lib/pythonx.x/site-packages - Requires: Pygments, Jinja2, docutils +.. tab:: Windows - .. group-tab:: Windows - - .. code-block:: console - - C:\> py -m pip show sphinx - --- - Name: Sphinx - Version: 1.1.3 - Location: /my/env/lib/pythonx.x/site-packages - Requires: Pygments, Jinja2, docutils + .. code-block:: console + C:\> py -m pip show sphinx + --- + Name: Sphinx + Version: 1.1.3 + 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,19 +465,17 @@ Searching for Packages pip can search `PyPI`_ for packages using the ``pip search`` command: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip search "query" - python -m pip search "query" +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip search "query" + py -m pip search "query" The query will be used to search the names and summaries of all packages. @@ -664,70 +637,60 @@ underscores (``_``). For example, to set the default timeout: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + export PIP_DEFAULT_TIMEOUT=60 - export PIP_DEFAULT_TIMEOUT=60 +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - set PIP_DEFAULT_TIMEOUT=60 + set PIP_DEFAULT_TIMEOUT=60 This is the same as passing the option to pip directly: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip --default-timeout=60 [...] - python -m pip --default-timeout=60 [...] +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip --default-timeout=60 [...] + py -m pip --default-timeout=60 [...] For command line options which can be repeated, use a space to separate multiple values. For example: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com" - export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com" +.. tab:: Windows - .. group-tab:: Windows - - .. code-block:: shell - - set PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com" + .. code-block:: shell + set PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com" is the same as calling: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com - python -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com +.. tab:: Windows - .. group-tab:: Windows - - .. code-block:: shell - - py -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com + .. 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,20 +762,17 @@ to PyPI. First, download the archives that fulfill your requirements: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip download --destination-directory DIR -r requirements.txt - python -m pip download --destination-directory DIR -r requirements.txt +.. tab:: Windows - .. group-tab:: Windows - - .. code-block:: shell - - py -m pip download --destination-directory DIR -r requirements.txt + .. 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 @@ -820,36 +780,32 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip wheel --wheel-dir DIR -r requirements.txt - python -m pip wheel --wheel-dir DIR -r requirements.txt +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip wheel --wheel-dir DIR -r requirements.txt + py -m pip wheel --wheel-dir DIR -r requirements.txt Then, to install from local only, you'll be using :ref:`--find-links ` and :ref:`--no-index ` like so: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install --no-index --find-links=DIR -r requirements.txt - python -m pip install --no-index --find-links=DIR -r requirements.txt +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install --no-index --find-links=DIR -r requirements.txt + py -m pip install --no-index --find-links=DIR -r requirements.txt "Only if needed" Recursive Upgrade @@ -870,21 +826,19 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install --upgrade --no-deps SomePackage + python -m pip install SomePackage - python -m pip install --upgrade --no-deps SomePackage - python -m pip install SomePackage +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install --upgrade --no-deps SomePackage - py -m pip install SomePackage + py -m pip install --upgrade --no-deps SomePackage + py -m pip install SomePackage A proposal for an ``upgrade-all`` command is being considered as a safer @@ -910,21 +864,19 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + export PYTHONUSERBASE=/myappenv + python -m pip install --user SomePackage - export PYTHONUSERBASE=/myappenv - python -m pip install --user SomePackage +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - set PYTHONUSERBASE=c:/myappenv - py -m pip install --user SomePackage + set PYTHONUSERBASE=c:/myappenv + py -m pip install --user SomePackage ``pip install --user`` follows four rules: @@ -946,126 +898,115 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip install --user SomePackage + Can not perform a '--user' install. User site-packages are not visible in this virtualenv. - $ python -m pip install --user SomePackage - Can not perform a '--user' install. User site-packages are not visible in this virtualenv. +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip install --user SomePackage - Can not perform a '--user' install. User site-packages are not visible in this virtualenv. + C:\> py -m pip install --user SomePackage + Can not perform a '--user' install. User site-packages are not visible in this virtualenv. From within a ``--system-site-packages`` virtualenv where ``SomePackage==0.3`` is already installed in the virtualenv: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. 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 - $ python -m pip install --user SomePackage==0.4 - Will not install to the user site because it will lack sys.path precedence +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip install --user SomePackage==0.4 - Will not install to the user site because it will lack sys.path precedence + C:\> py -m pip install --user SomePackage==0.4 + Will not install to the user site because it will lack sys.path precedence From within a real python, where ``SomePackage`` is *not* installed globally: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip install --user SomePackage + [...] + Successfully installed SomePackage - $ python -m pip install --user SomePackage - [...] - Successfully installed SomePackage +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip install --user SomePackage - [...] - Successfully installed SomePackage + C:\> py -m pip install --user SomePackage + [...] + Successfully installed SomePackage From within a real python, where ``SomePackage`` *is* installed globally, but is *not* the latest version: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip install --user SomePackage + [...] + Requirement already satisfied (use --upgrade to upgrade) + $ python -m pip install --user --upgrade SomePackage + [...] + Successfully installed SomePackage - $ python -m pip install --user SomePackage - [...] - Requirement already satisfied (use --upgrade to upgrade) - $ python -m pip install --user --upgrade SomePackage - [...] - Successfully installed SomePackage +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip install --user SomePackage - [...] - Requirement already satisfied (use --upgrade to upgrade) - C:\> py -m pip install --user --upgrade SomePackage - [...] - Successfully installed SomePackage + C:\> py -m pip install --user SomePackage + [...] + Requirement already satisfied (use --upgrade to upgrade) + C:\> py -m pip install --user --upgrade SomePackage + [...] + Successfully installed SomePackage From within a real python, where ``SomePackage`` *is* installed globally, and is the latest version: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: console - .. code-block:: console + $ python -m pip install --user SomePackage + [...] + Requirement already satisfied (use --upgrade to upgrade) + $ python -m pip install --user --upgrade SomePackage + [...] + Requirement already up-to-date: SomePackage + # force the install + $ python -m pip install --user --ignore-installed SomePackage + [...] + Successfully installed SomePackage - $ python -m pip install --user SomePackage - [...] - Requirement already satisfied (use --upgrade to upgrade) - $ python -m pip install --user --upgrade SomePackage - [...] - Requirement already up-to-date: SomePackage - # force the install - $ python -m pip install --user --ignore-installed SomePackage - [...] - Successfully installed SomePackage +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: console - .. code-block:: console - - C:\> py -m pip install --user SomePackage - [...] - Requirement already satisfied (use --upgrade to upgrade) - C:\> py -m pip install --user --upgrade SomePackage - [...] - Requirement already up-to-date: SomePackage - # force the install - C:\> py -m pip install --user --ignore-installed SomePackage - [...] - Successfully installed SomePackage + C:\> py -m pip install --user SomePackage + [...] + Requirement already satisfied (use --upgrade to upgrade) + C:\> py -m pip install --user --upgrade SomePackage + [...] + Requirement already up-to-date: SomePackage + # force the install + C:\> py -m pip install --user --ignore-installed SomePackage + [...] + Successfully installed SomePackage .. _`Repeatability`: @@ -1171,19 +1112,17 @@ Understanding your error message When you get a ``ResolutionImpossible`` error, you might see something like this: -.. tabs:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install package_coffee==0.44.1 package_tea==4.3.0 - python -m pip install package_coffee==0.44.1 package_tea==4.3.0 +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install package_coffee==0.44.1 package_tea==4.3.0 + py -m pip install package_coffee==0.44.1 package_tea==4.3.0 :: @@ -1289,19 +1228,17 @@ 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:: +.. tab:: Unix/macOS - .. group-tab:: Unix/macOS + .. code-block:: shell - .. code-block:: shell + python -m pip install package_coffee==0.44.1b0 package_tea - python -m pip install package_coffee==0.44.1b0 package_tea +.. tab:: Windows - .. group-tab:: Windows + .. code-block:: shell - .. code-block:: shell - - py -m pip install package_coffee==0.44.1b0 package_tea + py -m pip install package_coffee==0.44.1b0 package_tea This will result in: diff --git a/tools/requirements/docs.txt b/tools/requirements/docs.txt index dc93a60ff..77a940c08 100644 --- a/tools/requirements/docs.txt +++ b/tools/requirements/docs.txt @@ -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.