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

Merge branch 'master' into release/20.2.4

This commit is contained in:
Pradyun Gedam 2020-10-16 18:22:56 +05:30
parent c73f06f447 3fe826c699
commit d0051aafb0
No known key found for this signature in database
GPG Key ID: FF99710C4332258E
196 changed files with 3382 additions and 1417 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.azure-pipelines/steps/run-tests-windows.yml
View File

@ -43,7 +43,7 @@ steps:
# https://bugs.python.org/issue18199 # https://bugs.python.org/issue18199
$env:TEMP = "R:\Temp" $env:TEMP = "R:\Temp"
tox -e py -- -m integration -n auto --duration=5 --junit-xml=junit/integration-test.xml tox -e py -- -m integration -n auto --durations=5 --junit-xml=junit/integration-test.xml
displayName: Tox run integration tests displayName: Tox run integration tests
- task: PublishTestResults@2 - task: PublishTestResults@2

4
.azure-pipelines/steps/run-tests.yml
View File

@ -11,10 +11,10 @@ steps:
displayName: Tox run unit tests displayName: Tox run unit tests
# Run integration tests in two groups so we will fail faster if there is a failure in the first group # Run integration tests in two groups so we will fail faster if there is a failure in the first group
- script: tox -e py -- -m integration -n auto --duration=5 -k "not test_install" --junit-xml=junit/integration-test-group0.xml - script: tox -e py -- -m integration -n auto --durations=5 -k "not test_install" --junit-xml=junit/integration-test-group0.xml
displayName: Tox run Group 0 integration tests displayName: Tox run Group 0 integration tests
- script: tox -e py -- -m integration -n auto --duration=5 -k "test_install" --junit-xml=junit/integration-test-group1.xml - script: tox -e py -- -m integration -n auto --durations=5 -k "test_install" --junit-xml=junit/integration-test-group1.xml
displayName: Tox run Group 1 integration tests displayName: Tox run Group 1 integration tests
- task: PublishTestResults@2 - task: PublishTestResults@2

5
.github/ISSUE_TEMPLATE/config.yml vendored
View File

@ -1,7 +1,7 @@
# Ref: https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser # Ref: https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
blank_issues_enabled: true # default blank_issues_enabled: true # default
contact_links: contact_links:
- name: 🤷💻🤦 Discourse - name: 💬 Discourse
url: https://discuss.python.org/c/packaging url: https://discuss.python.org/c/packaging
about: | about: |
Please ask typical Q&A here: general ideas for Python packaging, Please ask typical Q&A here: general ideas for Python packaging,
@ -9,6 +9,3 @@ contact_links:
- name: '💬 IRC: #pypa @ Freenode' - name: '💬 IRC: #pypa @ Freenode'
url: https://webchat.freenode.net/#pypa url: https://webchat.freenode.net/#pypa
about: Chat with devs about: Chat with devs
- name: 📝 PyPA Code of Conduct
url: https://www.pypa.io/en/latest/code-of-conduct/
about: ❤ Be nice to other members of the community. ☮ Behave.

61
.pre-commit-config.yaml
View File

@ -2,7 +2,7 @@ exclude: 'src/pip/_vendor/'
repos: repos:
- repo: https://github.com/pre-commit/pre-commit-hooks - repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.5.0 rev: v3.2.0
hooks: hooks:
- id: check-builtin-literals - id: check-builtin-literals
- id: check-added-large-files - id: check-added-large-files
@ -16,8 +16,44 @@ repos:
- id: trailing-whitespace - id: trailing-whitespace
exclude: .patch exclude: .patch
- repo: https://github.com/psf/black
rev: 20.8b1
hooks:
- id: black
exclude: |
(?x)
^docs/|
^src/pip/_internal/cli|
^src/pip/_internal/commands|
^src/pip/_internal/distributions|
^src/pip/_internal/index|
^src/pip/_internal/models|
^src/pip/_internal/network|
^src/pip/_internal/operations|
^src/pip/_internal/req|
^src/pip/_internal/resolution|
^src/pip/_internal/utils|
^src/pip/_internal/vcs|
^src/pip/_internal/\w+\.py$|
^src/pip/__main__.py$|
^tools/|
# Tests
^tests/conftest.py|
^tests/yaml|
^tests/lib|
^tests/data|
^tests/unit|
^tests/functional/(?!test_install)|
^tests/functional/test_install|
# Files in the root of the repository
^setup.py|
^noxfile.py|
# A blank ignore, to avoid merge conflicts later.
^$
- repo: https://gitlab.com/pycqa/flake8 - repo: https://gitlab.com/pycqa/flake8
rev: 3.8.1 rev: 3.8.3
hooks: hooks:
- id: flake8 - id: flake8
additional_dependencies: [ additional_dependencies: [
@ -27,7 +63,7 @@ repos:
exclude: tests/data exclude: tests/data
- repo: https://github.com/timothycrosley/isort - repo: https://github.com/timothycrosley/isort
rev: 4.3.21 rev: 5.5.3
hooks: hooks:
- id: isort - id: isort
files: \.py$ files: \.py$
@ -44,18 +80,25 @@ repos:
args: ["--pretty", "-2"] args: ["--pretty", "-2"]
- repo: https://github.com/pre-commit/pygrep-hooks - repo: https://github.com/pre-commit/pygrep-hooks
rev: v1.5.1 rev: v1.6.0
hooks: hooks:
- id: python-no-log-warn - id: python-no-log-warn
- id: python-no-eval - id: python-no-eval
- id: rst-backticks - id: rst-backticks
# Validate existing ReST files and NEWS fragments. files: .*\.rst$
files: .*\.rst$|^news/.*
types: [file] types: [file]
# The errors flagged in NEWS.rst are old. exclude: NEWS.rst # The errors flagged in NEWS.rst are old.
exclude: NEWS.rst
- repo: local
hooks:
- id: news-fragment-filenames
name: NEWS fragment
language: fail
entry: NEWS fragment files must be named *.(process|removal|feature|bugfix|vendor|doc|trivial).rst
exclude: ^news/(.gitignore|.*\.(process|removal|feature|bugfix|vendor|doc|trivial).rst)
files: ^news/
- repo: https://github.com/mgedmin/check-manifest - repo: https://github.com/mgedmin/check-manifest
rev: '0.42' rev: '0.43'
hooks: hooks:
- id: check-manifest - id: check-manifest

2
LICENSE.txt
View File

@ -1,4 +1,4 @@
Copyright (c) 2008-2019 The pip developers (see AUTHORS.txt file) Copyright (c) 2008-2020 The pip developers (see AUTHORS.txt file)
Permission is hereby granted, free of charge, to any person obtaining Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the a copy of this software and associated documentation files (the

2
MANIFEST.in
View File

@ -22,7 +22,7 @@ exclude noxfile.py
recursive-include src/pip/_vendor *.pem recursive-include src/pip/_vendor *.pem
recursive-include src/pip/_vendor py.typed recursive-include src/pip/_vendor py.typed
recursive-include docs Makefile *.rst *.py *.bat recursive-include docs *.css *.rst *.py
exclude src/pip/_vendor/six exclude src/pip/_vendor/six
exclude src/pip/_vendor/six/moves exclude src/pip/_vendor/six/moves

4
README.rst
View File

@ -38,7 +38,7 @@ Code of Conduct
--------------- ---------------
Everyone interacting in the pip project's codebases, issue trackers, chat Everyone interacting in the pip project's codebases, issue trackers, chat
rooms, and mailing lists is expected to follow the `PyPA Code of Conduct`_. rooms, and mailing lists is expected to follow the `PSF Code of Conduct`_.
.. _package installer: https://packaging.python.org/guides/tool-recommendations/ .. _package installer: https://packaging.python.org/guides/tool-recommendations/
.. _Python Package Index: https://pypi.org .. _Python Package Index: https://pypi.org
@ -54,4 +54,4 @@ rooms, and mailing lists is expected to follow the `PyPA Code of Conduct`_.
.. _Development mailing list: https://mail.python.org/mailman3/lists/distutils-sig.python.org/ .. _Development mailing list: https://mail.python.org/mailman3/lists/distutils-sig.python.org/
.. _User IRC: https://webchat.freenode.net/?channels=%23pypa .. _User IRC: https://webchat.freenode.net/?channels=%23pypa
.. _Development IRC: https://webchat.freenode.net/?channels=%23pypa-dev .. _Development IRC: https://webchat.freenode.net/?channels=%23pypa-dev
.. _PyPA Code of Conduct: https://www.pypa.io/en/latest/code-of-conduct/ .. _PSF Code of Conduct: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md

165
docs/docs_feedback_sphinxext.py Normal file
View File

@ -0,0 +1,165 @@
"""A sphinx extension for collecting per doc feedback."""
from __future__ import annotations
from itertools import chain
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from typing import Dict, List, Union
from sphinx.application import Sphinx
DEFAULT_DOC_LINES_THRESHOLD = 250
RST_INDENT = 4
EMAIL_INDENT = 6
def _modify_rst_document_source_on_read(
app: Sphinx,
docname: str,
source: List[str],
) -> None:
"""Add info block to top and bottom of each document source.
This function modifies RST source in-place by adding an admonition
block at the top and the bottom of each document right after it's
been read from disk preserving :orphan: at top, if present.
"""
admonition_type = app.config.docs_feedback_admonition_type
big_doc_lines = app.config.docs_feedback_big_doc_lines
escaped_email = app.config.docs_feedback_email.replace(' ', r'\ ')
excluded_documents = set(app.config.docs_feedback_excluded_documents)
questions_list = app.config.docs_feedback_questions_list
valid_admonitions = {
'attention', 'caution', 'danger', 'error', 'hint',
'important', 'note', 'tip', 'warning', 'admonition',
}
if admonition_type not in valid_admonitions:
raise ValueError(
'Expected `docs_feedback_admonition_type` to be one of '
f'{valid_admonitions} but got {admonition_type}.'
)
if not questions_list:
raise ValueError(
'Expected `docs_feedback_questions_list` to list questions '
'but got none.'
)
if docname in excluded_documents:
# NOTE: Completely ignore any document
# NOTE: listed in 'docs_feedback_excluded_documents'.
return
is_doc_big = source[0].count('\n') >= big_doc_lines
questions_list_rst = '\n'.join(
f'{" " * RST_INDENT}{number!s}. {question}'
for number, question in enumerate(questions_list, 1)
)
questions_list_urlencoded = (
'\n'.join(
f'\n{" " * RST_INDENT}{number!s}. {question} '
for number, question in enumerate(
chain(
(f'Document: {docname}. Page URL: https://', ),
questions_list,
),
)
).
rstrip('\r\n\t ').
replace('\r', '%0D').
replace('\n', '%0A').
replace(' ', '%20')
)
admonition_msg = rf"""
**Did this article help?**
We are currently doing research to improve pip's documentation
and would love your feedback.
Please `email us`_ and let us know{{let_us_know_ending}}
{{questions_list_rst}}
.. _email us:
mailto:{escaped_email}\
?subject=[Doc:\ {docname}]\ Pip\ docs\ feedback\ \
(URL\:\ https\://)\
&body={questions_list_urlencoded}
"""
let_us_know_ending = ':'
info_block_bottom = (
f'.. {admonition_type}::\n\t\t{admonition_msg.format_map(locals())}\n'
)
questions_list_rst = ''
let_us_know_ending = (
' why you came to this page and what on it helped '
'you and what did not. '
'(:issue:`Read more about this research <8517>`)'
)
info_block_top = '' if is_doc_big else (
f'.. {admonition_type}::\n\t\t{admonition_msg.format_map(locals())}\n'
)
orphan_mark = ':orphan:'
is_orphan = orphan_mark in source[0]
if is_orphan:
source[0].replace(orphan_mark, '')
else:
orphan_mark = ''
source[0] = '\n\n'.join((
orphan_mark, info_block_top, source[0], info_block_bottom,
))
def setup(app: Sphinx) -> Dict[str, Union[bool, str]]:
"""Initialize the Sphinx extension.
This function adds a callback for modifying the document sources
in-place on read.
It also declares the extension settings changable via :file:`conf.py`.
"""
rebuild_trigger = 'html' # rebuild full html on settings change
app.add_config_value(
'docs_feedback_admonition_type',
default='important',
rebuild=rebuild_trigger,
)
app.add_config_value(
'docs_feedback_big_doc_lines',
default=DEFAULT_DOC_LINES_THRESHOLD,
rebuild=rebuild_trigger,
)
app.add_config_value(
'docs_feedback_email',
default='Docs UX Team <docs-feedback+ux/pip.pypa.io@pypa.io>',
rebuild=rebuild_trigger,
)
app.add_config_value(
'docs_feedback_excluded_documents',
default=set(),
rebuild=rebuild_trigger,
)
app.add_config_value(
'docs_feedback_questions_list',
default=(),
rebuild=rebuild_trigger,
)
app.add_css_file('important-admonition.css')
app.connect('source-read', _modify_rst_document_source_on_read)
return {
'parallel_read_safe': True,
'parallel_write_safe': True,
'version': 'builtin',
}

8
docs/html/_static/important-admonition.css Normal file
View File

@ -0,0 +1,8 @@
.admonition.important {
background-color: rgb(219, 250, 244);
border: 1px solid rgb(26, 188, 156);
}
.admonition.important>.admonition-title {
color: rgb(26, 188, 156);
}

36
docs/html/conf.py
View File

@ -30,7 +30,16 @@ sys.path.insert(0, docs_dir)
# Add any Sphinx extension module names here, as strings. They can be # Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
# extensions = ['sphinx.ext.autodoc'] # extensions = ['sphinx.ext.autodoc']
extensions = ['sphinx.ext.extlinks', 'pip_sphinxext', 'sphinx.ext.intersphinx'] extensions = [
# native:
'sphinx.ext.extlinks',
'sphinx.ext.intersphinx',
# third-party:
'sphinx_tabs.tabs',
# in-tree:
'docs_feedback_sphinxext',
'pip_sphinxext',
]
# intersphinx # intersphinx
intersphinx_cache_limit = 0 intersphinx_cache_limit = 0
@ -130,6 +139,9 @@ extlinks = {
'pypi': ('https://pypi.org/project/%s/', ''), 'pypi': ('https://pypi.org/project/%s/', ''),
} }
# Turn off sphinx build warnings because of sphinx tabs during man pages build
sphinx_tabs_nowarn = True
# -- Options for HTML output -------------------------------------------------- # -- Options for HTML output --------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with # The theme to use for HTML and HTML Help pages. Major themes that come with
@ -143,7 +155,9 @@ html_theme_options = {
'collapsiblesidebar': True, 'collapsiblesidebar': True,
'externalrefs': True, 'externalrefs': True,
'navigation_depth': 3, 'navigation_depth': 3,
'issues_url': 'https://github.com/pypa/pip/issues' 'issues_url': 'https://github.com/pypa/pip/issues',
'codebgcolor': '#eeffcc',
'codetextcolor': '#333333',
} }
# Add any paths that contain custom themes here, relative to this directory. # Add any paths that contain custom themes here, relative to this directory.
@ -167,7 +181,7 @@ html_theme_options = {
# Add any paths that contain custom static files (such as style sheets) here, # Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = [] html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format. # using the given strftime format.
@ -298,3 +312,19 @@ for fname in raw_subcommands:
) )
man_pages.append((fname_base, outname, description, u'pip developers', 1)) man_pages.append((fname_base, outname, description, u'pip developers', 1))
# -- Options for docs_feedback_sphinxext --------------------------------------
# NOTE: Must be one of 'attention', 'caution', 'danger', 'error', 'hint',
# NOTE: 'important', 'note', 'tip', 'warning' or 'admonition'.
docs_feedback_admonition_type = 'important'
docs_feedback_big_doc_lines = 50 # bigger docs will have a banner on top
docs_feedback_email = 'Docs UX Team <docs-feedback+ux/pip.pypa.io@pypa.io>'
docs_feedback_excluded_documents = { # these won't have any banners
'news',
}
docs_feedback_questions_list = (
'What problem were you trying to solve when you came to this page?',
'What content was useful?',
'What content was not useful?',
)

1
docs/html/development/architecture/configuration-files.rst
View File

@ -109,6 +109,7 @@ manipulated. In addition to the methods discussed in the previous section,
the methods used would be: the methods used would be:
.. py:class:: Configuration .. py:class:: Configuration
:noindex:
.. py:method:: get_file_to_edit() .. py:method:: get_file_to_edit()

20
docs/html/development/contributing.rst
View File

@ -70,15 +70,17 @@ such, but it is preferred to have a dedicated issue (for example, in case the
PR ends up rejected due to code quality reasons). PR ends up rejected due to code quality reasons).
Once you have an issue or pull request, you take the number and you create a Once you have an issue or pull request, you take the number and you create a
file inside of the ``news/`` directory named after that issue number with an file inside of the ``news/`` directory, named after that issue number with a
extension of ``removal``, ``feature``, ``bugfix``, or ``doc``. Thus if your "type" of ``removal``, ``feature``, ``bugfix``, or ``doc`` associated with it.
issue or PR number is ``1234`` and this change is fixing a bug, then you would
create a file ``news/1234.bugfix``. PRs can span multiple categories by creating If your issue or PR number is ``1234`` and this change is fixing a bug,
multiple files (for instance, if you added a feature and deprecated/removed the then you would create a file ``news/1234.bugfix.rst``. PRs can span multiple
old feature at the same time, you would create ``news/NNNN.feature`` and categories by creating multiple files (for instance, if you added a feature and
``news/NNNN.removal``). Likewise if a PR touches multiple issues/PRs you may deprecated/removed the old feature at the same time, you would create
create a file for each of them with the exact same contents and Towncrier will ``news/NNNN.feature.rst`` and ``news/NNNN.removal.rst``).
deduplicate them.
If a PR touches multiple issues/PRs, you may create a file for each of them
with the exact same contents and Towncrier will deduplicate them.
Contents of a NEWS entry Contents of a NEWS entry
------------------------ ------------------------

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

@ -38,13 +38,25 @@ To run the pip executable from your source tree during development, install pip
locally using editable installation (inside a virtualenv). locally using editable installation (inside a virtualenv).
You can then invoke your local source tree pip normally. You can then invoke your local source tree pip normally.
.. code-block:: console .. tabs::
$ virtualenv venv # You can also use "python -m venv venv" from python3.3+ .. group-tab:: Unix/macOS
$ source venv/bin/activate
$ python -m pip install -e .
$ python -m pip --version
.. 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
.. group-tab:: Windows
.. 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
Running Tests Running Tests
============= =============

4
docs/html/index.rst
View File

@ -36,7 +36,7 @@ Code of Conduct
=============== ===============
Everyone interacting in the pip project's codebases, issue trackers, chat Everyone interacting in the pip project's codebases, issue trackers, chat
rooms, and mailing lists is expected to follow the `PyPA Code of Conduct`_. rooms, and mailing lists is expected to follow the `PSF Code of Conduct`_.
.. _package installer: https://packaging.python.org/guides/tool-recommendations/ .. _package installer: https://packaging.python.org/guides/tool-recommendations/
.. _Python Package Index: https://pypi.org .. _Python Package Index: https://pypi.org
@ -51,4 +51,4 @@ rooms, and mailing lists is expected to follow the `PyPA Code of Conduct`_.
.. _Development mailing list: https://mail.python.org/mailman3/lists/distutils-sig.python.org/ .. _Development mailing list: https://mail.python.org/mailman3/lists/distutils-sig.python.org/
.. _User IRC: https://webchat.freenode.net/?channels=%23pypa .. _User IRC: https://webchat.freenode.net/?channels=%23pypa
.. _Development IRC: https://webchat.freenode.net/?channels=%23pypa-dev .. _Development IRC: https://webchat.freenode.net/?channels=%23pypa-dev
.. _PyPA Code of Conduct: https://www.pypa.io/en/latest/code-of-conduct/ .. _PSF Code of Conduct: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md

94
docs/html/installing.rst
View File

@ -26,9 +26,21 @@ this link: `get-pip.py
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
Then run the following command in the folder where you Then run the following command in the folder where you
have downloaded ``get-pip.py``:: have downloaded ``get-pip.py``:
python get-pip.py .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python get-pip.py
.. group-tab:: Windows
.. code-block:: shell
py get-pip.py
.. warning:: .. warning::
@ -67,23 +79,70 @@ get-pip.py options
install Options>` and the :ref:`general options <General Options>`. Below are install Options>` and the :ref:`general options <General Options>`. Below are
some examples: some examples:
Install from local copies of pip and setuptools:: Install from local copies of pip and setuptools:
python get-pip.py --no-index --find-links=/local/copies .. tabs::
Install to the user site [3]_:: .. group-tab:: Unix/macOS
python get-pip.py --user .. code-block:: shell
Install behind a proxy:: python get-pip.py --no-index --find-links=/local/copies
python get-pip.py --proxy="http://[user:passwd@]proxy.server:port" .. group-tab:: Windows
.. code-block:: shell
py get-pip.py --no-index --find-links=/local/copies
Install to the user site [3]_:
.. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python get-pip.py --user
.. group-tab:: Windows
.. code-block:: shell
py get-pip.py --user
Install behind a proxy:
.. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python get-pip.py --proxy="http://[user:passwd@]proxy.server:port"
.. group-tab:: Windows
.. code-block:: shell
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``, ``get-pip.py`` can also be used to install a specified combination of ``pip``,
``setuptools``, and ``wheel`` using the same requirements syntax as pip:: ``setuptools``, and ``wheel`` using the same requirements syntax as pip:
python get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 .. tabs::
.. group-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
.. code-block:: shell
py get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0
Using Linux Package Managers Using Linux Package Managers
============================ ============================
@ -97,14 +156,19 @@ the `Python Packaging User Guide
Upgrading pip Upgrading pip
============= =============
On Linux or macOS:: .. tabs::
pip install -U pip .. group-tab:: Unix/macOS
.. code-block:: shell
On Windows [4]_:: python -m pip install -U pip
python -m pip install -U pip .. group-tab:: Windows
.. code-block:: shell
py -m pip install -U pip
.. _compatibility-requirements: .. _compatibility-requirements:
@ -134,5 +198,3 @@ pip works on Unix/Linux, macOS, and Windows.
``--user`` installs for pip itself, should not be considered to be fully ``--user`` installs for pip itself, should not be considered to be fully
tested or endorsed. For discussion, see `Issue 1668 tested or endorsed. For discussion, see `Issue 1668
<https://github.com/pypa/pip/issues/1668>`_. <https://github.com/pypa/pip/issues/1668>`_.
.. [4] https://github.com/pypa/pip/issues/1299

149
docs/html/quickstart.rst
View File

@ -6,62 +6,145 @@ First, :doc:`install pip <installing>`.
Install a package from `PyPI`_: Install a package from `PyPI`_:
:: .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: console
$ python -m pip install SomePackage
[...]
Successfully installed SomePackage
.. group-tab:: Windows
.. code-block:: console
C:\> py -m pip install SomePackage
[...]
Successfully installed SomePackage
$ pip install SomePackage
[...]
Successfully installed SomePackage
Install a package that's already been downloaded from `PyPI`_ or 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 obtained from elsewhere. This is useful if the target machine does not have a
network connection: network connection:
:: .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: console
$ python -m pip install SomePackage-1.0-py2.py3-none-any.whl
[...]
Successfully installed SomePackage
.. group-tab:: Windows
.. code-block:: console
C:\> py -m pip install SomePackage-1.0-py2.py3-none-any.whl
[...]
Successfully installed SomePackage
$ pip install SomePackage-1.0-py2.py3-none-any.whl
[...]
Successfully installed SomePackage
Show what files were installed: Show what files were installed:
:: .. tabs::
$ pip show --files SomePackage .. group-tab:: Unix/macOS
Name: SomePackage
Version: 1.0 .. code-block:: console
Location: /my/env/lib/pythonx.x/site-packages
Files: $ python -m pip show --files SomePackage
../somepackage/__init__.py Name: SomePackage
[...] Version: 1.0
Location: /my/env/lib/pythonx.x/site-packages
Files:
../somepackage/__init__.py
[...]
.. group-tab:: Windows
.. 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
[...]
List what packages are outdated: List what packages are outdated:
:: .. tabs::
$ pip list --outdated .. group-tab:: Unix/macOS
SomePackage (Current: 1.0 Latest: 2.0)
.. code-block:: console
$ python -m pip list --outdated
SomePackage (Current: 1.0 Latest: 2.0)
.. group-tab:: Windows
.. code-block:: console
C:\> py -m pip list --outdated
SomePackage (Current: 1.0 Latest: 2.0)
Upgrade a package: Upgrade a package:
:: .. tabs::
$ pip install --upgrade SomePackage .. group-tab:: Unix/macOS
[...]
Found existing installation: SomePackage 1.0 .. code-block:: console
Uninstalling SomePackage:
Successfully uninstalled SomePackage $ python -m pip install --upgrade SomePackage
Running setup.py install for SomePackage [...]
Successfully installed SomePackage Found existing installation: SomePackage 1.0
Uninstalling SomePackage:
Successfully uninstalled SomePackage
Running setup.py install for SomePackage
Successfully installed SomePackage
.. group-tab:: Windows
.. 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
Uninstall a package: Uninstall a package:
:: .. tabs::
$ pip uninstall SomePackage .. group-tab:: Unix/macOS
Uninstalling SomePackage:
/my/env/lib/pythonx.x/site-packages/somepackage .. code-block:: console
Proceed (y/n)? y
Successfully uninstalled SomePackage $ python -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
.. _PyPI: https://pypi.org/ .. _PyPI: https://pypi.org/

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

@ -7,10 +7,19 @@ pip
Usage Usage
***** *****
:: .. tabs::
pip <command> [options] .. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip <command> [options]
.. group-tab:: Windows
.. code-block:: shell
py -m pip <command> [options]
Description Description
*********** ***********
@ -221,9 +230,21 @@ Build Options
The ``--global-option`` and ``--build-option`` arguments to the ``pip install`` The ``--global-option`` and ``--build-option`` arguments to the ``pip install``
and ``pip wheel`` inject additional arguments into the ``setup.py`` command and ``pip wheel`` inject additional arguments into the ``setup.py`` command
(``--build-option`` is only available in ``pip wheel``). These arguments are (``--build-option`` is only available in ``pip wheel``). These arguments are
included in the command as follows:: included in the command as follows:
python setup.py <global_options> BUILD COMMAND <build_options> .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: console
python setup.py <global_options> BUILD COMMAND <build_options>
.. group-tab:: Windows
.. code-block:: shell
py setup.py <global_options> BUILD COMMAND <build_options>
The options are passed unmodified, and presently offer direct access to the The options are passed unmodified, and presently offer direct access to the
distutils command line. Use of ``--global-option`` and ``--build-option`` distutils command line. Use of ``--global-option`` and ``--build-option``

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

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

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

@ -10,7 +10,15 @@ pip check
Usage Usage
===== =====
.. pip-command-usage:: check .. tabs::
.. group-tab:: Unix/macOS
.. pip-command-usage:: check "python -m pip"
.. group-tab:: Windows
.. pip-command-usage:: check "py -m pip"
Description Description
@ -24,27 +32,66 @@ Examples
#. If all dependencies are compatible: #. If all dependencies are compatible:
:: .. tabs::
$ pip check .. group-tab:: Unix/macOS
No broken requirements found.
$ echo $? .. code-block:: console
0
$ python -m pip check
No broken requirements found.
$ echo $?
0
.. group-tab:: Windows
.. code-block:: console
C:\> py -m pip check
No broken requirements found.
C:\> echo %errorlevel%
0
#. If a package is missing: #. If a package is missing:
:: .. tabs::
$ pip check .. group-tab:: Unix/macOS
pyramid 1.5.2 requires WebOb, which is not installed.
$ echo $? .. code-block:: console
1
$ python -m pip check
pyramid 1.5.2 requires WebOb, which is not installed.
$ echo $?
1
.. group-tab:: Windows
.. code-block:: console
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: #. If a package has the wrong version:
:: .. tabs::
$ pip check .. group-tab:: Unix/macOS
pyramid 1.5.2 has requirement WebOb>=1.3.1, but you have WebOb 0.8.
$ echo $? .. code-block:: console
1
$ python -m pip check
pyramid 1.5.2 has requirement WebOb>=1.3.1, but you have WebOb 0.8.
$ echo $?
1
.. group-tab:: Windows
.. 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

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

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

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

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

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

@ -11,7 +11,15 @@ pip download
Usage Usage
===== =====
.. pip-command-usage:: download .. tabs::
.. group-tab:: Unix/macOS
.. pip-command-usage:: download "python -m pip"
.. group-tab:: Windows
.. pip-command-usage:: download "py -m pip"
Description Description
@ -56,64 +64,148 @@ Examples
#. Download a package and all of its dependencies #. Download a package and all of its dependencies
:: .. tabs::
.. group-tab:: Unix/macOS
.. 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
.. group-tab:: Windows
.. 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
$ pip download SomePackage
$ pip download -d . SomePackage # equivalent to above
$ 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. #. Download a package and all of its dependencies with OSX specific interpreter constraints.
This forces OSX 10.10 or lower compatibility. Since OSX deps are forward compatible, This forces OSX 10.10 or lower compatibility. Since OSX deps are forward compatible,
this will also match ``macosx-10_9_x86_64``, ``macosx-10_8_x86_64``, ``macosx-10_8_intel``, this will also match ``macosx-10_9_x86_64``, ``macosx-10_8_x86_64``, ``macosx-10_8_intel``,
etc. etc.
It will also match deps with platform ``any``. Also force the interpreter version to ``27`` 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``). (or more generic, i.e. ``2``) and implementation to ``cp`` (or more generic, i.e. ``py``).
:: .. tabs::
$ pip download \ .. group-tab:: Unix/macOS
--only-binary=:all: \
--platform macosx-10_10_x86_64 \ .. code-block:: shell
--python-version 27 \
--implementation cp \ python -m pip download \
SomePackage --only-binary=:all: \
--platform macosx-10_10_x86_64 \
--python-version 27 \
--implementation cp \
SomePackage
.. group-tab:: Windows
.. code-block:: shell
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. #. Download a package and its dependencies with linux specific constraints.
Force the interpreter to be any minor version of py3k, and only accept Force the interpreter to be any minor version of py3k, and only accept
``cp34m`` or ``none`` as the abi. ``cp34m`` or ``none`` as the abi.
:: .. tabs::
$ pip download \ .. group-tab:: Unix/macOS
--only-binary=:all: \
--platform linux_x86_64 \ .. code-block:: shell
--python-version 3 \
--implementation cp \ python -m pip download \
--abi cp34m \ --only-binary=:all: \
SomePackage --platform linux_x86_64 \
--python-version 3 \
--implementation cp \
--abi cp34m \
SomePackage
.. group-tab:: Windows
.. code-block:: shell
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. #. Force platform, implementation, and abi agnostic deps.
:: .. tabs::
$ pip download \ .. group-tab:: Unix/macOS
--only-binary=:all: \
--platform any \ .. code-block:: shell
--python-version 3 \
--implementation py \ python -m pip download \
--abi none \ --only-binary=:all: \
SomePackage --platform any \
--python-version 3 \
--implementation py \
--abi none \
SomePackage
.. group-tab:: Windows
.. code-block:: shell
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. #. Even when overconstrained, this will still correctly fetch the pip universal wheel.
:: .. tabs::
$ pip download \ .. group-tab:: Unix/macOS
--only-binary=:all: \
--platform linux_x86_64 \ .. code-block:: console
--python-version 33 \
--implementation cp \ $ python -m pip download \
--abi cp34m \ --only-binary=:all: \
pip>=8 --platform linux_x86_64 \
$ ls pip-8.1.1-py2.py3-none-any.whl --python-version 33 \
pip-8.1.1-py2.py3-none-any.whl --implementation cp \
--abi cp34m \
pip>=8
.. code-block:: console
$ ls pip-8.1.1-py2.py3-none-any.whl
pip-8.1.1-py2.py3-none-any.whl
.. group-tab:: Windows
.. code-block:: console
C:\> py -m pip download ^
--only-binary=:all: ^
--platform linux_x86_64 ^
--python-version 33 ^
--implementation cp ^
--abi cp34m ^
pip>=8
.. code-block:: console
C:\> dir pip-8.1.1-py2.py3-none-any.whl
pip-8.1.1-py2.py3-none-any.whl

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

@ -11,7 +11,15 @@ pip freeze
Usage Usage
===== =====
.. pip-command-usage:: freeze .. tabs::
.. group-tab:: Unix/macOS
.. pip-command-usage:: freeze "python -m pip"
.. group-tab:: Windows
.. pip-command-usage:: freeze "py -m pip"
Description Description
@ -31,19 +39,45 @@ Examples
#. Generate output suitable for a requirements file. #. Generate output suitable for a requirements file.
:: .. tabs::
$ pip freeze .. group-tab:: Unix/macOS
docutils==0.11
Jinja2==2.7.2 .. code-block:: console
MarkupSafe==0.19
Pygments==1.6 $ python -m pip freeze
Sphinx==1.2.2 docutils==0.11
Jinja2==2.7.2
MarkupSafe==0.19
Pygments==1.6
Sphinx==1.2.2
.. 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
#. Generate a requirements file and then install from it in another environment. #. Generate a requirements file and then install from it in another environment.
:: .. tabs::
$ env1/bin/pip freeze > requirements.txt .. group-tab:: Unix/macOS
$ env2/bin/pip install -r requirements.txt
.. code-block:: shell
env1/bin/python -m pip freeze > requirements.txt
env2/bin/python -m pip install -r requirements.txt
.. group-tab:: Windows
.. code-block:: shell
env1\bin\python -m pip freeze > requirements.txt
env2\bin\python -m pip install -r requirements.txt

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

@ -10,7 +10,15 @@ pip hash
Usage Usage
===== =====
.. pip-command-usage:: hash .. tabs::
.. group-tab:: Unix/macOS
.. pip-command-usage:: hash "python -m pip"
.. group-tab:: Windows
.. pip-command-usage:: hash "py -m pip"
Description Description
@ -39,13 +47,32 @@ Options
Example Example
======= =======
Compute the hash of a downloaded archive:: Compute the hash of a downloaded archive:
$ pip download SomePackage .. tabs::
Collecting SomePackage
Downloading SomePackage-2.2.tar.gz .. group-tab:: Unix/macOS
Saved ./pip_downloads/SomePackage-2.2.tar.gz
Successfully downloaded SomePackage .. code-block:: console
$ pip hash ./pip_downloads/SomePackage-2.2.tar.gz
./pip_downloads/SomePackage-2.2.tar.gz: $ python -m pip download SomePackage
--hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 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
.. group-tab:: Windows
.. 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

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

@ -10,7 +10,16 @@ pip install
Usage Usage
===== =====
.. pip-command-usage:: install .. tabs::
.. group-tab:: Unix/macOS
.. pip-command-usage:: install "python -m pip"
.. group-tab:: Windows
.. pip-command-usage:: install "py -m pip"
Description Description
@ -89,15 +98,33 @@ implementation (which might possibly change later) has it such that the first
encountered member of the cycle is installed last. encountered member of the cycle is installed last.
For instance, if quux depends on foo which depends on bar which depends on baz, For instance, if quux depends on foo which depends on bar which depends on baz,
which depends on foo:: which depends on foo:
pip install quux .. tabs::
...
Installing collected packages baz, bar, foo, quux
pip install bar .. group-tab:: Unix/macOS
...
Installing collected packages foo, baz, bar .. code-block:: console
$ python -m pip install quux
...
Installing collected packages baz, bar, foo, quux
$ python -m pip install bar
...
Installing collected packages foo, baz, bar
.. group-tab:: Windows
.. code-block:: console
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
Prior to v6.1.0, pip made no commitments about install order. Prior to v6.1.0, pip made no commitments about install order.
@ -387,9 +414,21 @@ If your repository layout is::
└── some_file └── some_file
some_other_file some_other_file
Then, to install from this repository, the syntax would be:: Then, to install from this repository, the syntax would be:
$ pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir" .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
.. group-tab:: Windows
.. code-block:: shell
py -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
Git Git
@ -636,17 +675,38 @@ against any requirement not only checks that hash but also activates a global
.. _`--require-hashes`: .. _`--require-hashes`:
Hash-checking mode can be forced on with the ``--require-hashes`` command-line Hash-checking mode can be forced on with the ``--require-hashes`` command-line
option:: option:
.. tabs::
.. group-tab:: Unix/macOS
.. 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
.. group-tab:: Windows
.. 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
$ 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 This can be useful in deploy scripts, to ensure that the author of the
requirements file provided hashes. It is also a convenient way to bootstrap requirements file provided hashes. It is also a convenient way to bootstrap
@ -692,14 +752,38 @@ Hash-checking mode also works with :ref:`pip download` and :ref:`pip wheel`. A
as your project evolves. To be safe, install your project using pip and as your project evolves. To be safe, install your project using pip and
:ref:`--no-deps <install_--no-deps>`. :ref:`--no-deps <install_--no-deps>`.
Instead of ``python setup.py develop``, use... :: Instead of ``python setup.py develop``, use...
pip install --no-deps -e . .. tabs::
Instead of ``python setup.py install``, use... :: .. group-tab:: Unix/macOS
pip install --no-deps . .. code-block:: shell
python -m pip install --no-deps -e .
.. group-tab:: Windows
.. code-block:: shell
py -m pip install --no-deps -e .
Instead of ``python setup.py install``, use...
.. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install --no-deps .
.. group-tab:: Windows
.. code-block:: shell
py -m pip install --no-deps .
Hashes from PyPI Hashes from PyPI
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
@ -717,9 +801,22 @@ Local project installs
---------------------- ----------------------
pip supports installing local project in both regular mode and editable mode. pip supports installing local project in both regular mode and editable mode.
You can install local projects by specifying the project path to pip:: You can install local projects by specifying the project path to pip:
.. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install path/to/SomeProject
.. group-tab:: Windows
.. code-block:: shell
py -m pip install path/to/SomeProject
$ pip install path/to/SomeProject
During regular installation, pip will copy the entire project directory to a During regular installation, pip will copy the entire project directory to a
temporary location and install from there. The exception is that pip will temporary location and install from there. The exception is that pip will
@ -736,10 +833,24 @@ being copied.
<https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode>`_ <https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode>`_
installs. installs.
You can install local projects or VCS projects in "editable" mode:: You can install local projects or VCS projects in "editable" mode:
.. tabs::
.. group-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
.. code-block:: shell
py -m pip install -e path/to/SomeProject
py -m pip install -e git+http://repo/my_project.git#egg=SomeProject
$ pip install -e path/to/SomeProject
$ 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.) (See the :ref:`VCS Support` section above for more information on VCS-related syntax.)
@ -846,113 +957,292 @@ Examples
#. Install ``SomePackage`` and its dependencies from `PyPI`_ using :ref:`Requirement Specifiers` #. Install ``SomePackage`` and its dependencies from `PyPI`_ using :ref:`Requirement Specifiers`
:: .. tabs::
$ pip install SomePackage # latest version .. group-tab:: Unix/macOS
$ pip install SomePackage==1.0.4 # specific version
$ pip install 'SomePackage>=1.0.4' # minimum version .. 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
.. group-tab:: Windows
.. 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
#. Install a list of requirements specified in a file. See the :ref:`Requirements files <Requirements Files>`. #. Install a list of requirements specified in a file. See the :ref:`Requirements files <Requirements Files>`.
:: .. tabs::
$ pip install -r requirements.txt .. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install -r requirements.txt
.. group-tab:: Windows
.. code-block:: shell
py -m pip install -r requirements.txt
#. Upgrade an already installed ``SomePackage`` to the latest from PyPI. #. Upgrade an already installed ``SomePackage`` to the latest from PyPI.
:: .. tabs::
$ pip install --upgrade SomePackage .. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install --upgrade SomePackage
.. group-tab:: Windows
.. code-block:: shell
py -m pip install --upgrade SomePackage
#. Install a local project in "editable" mode. See the section on :ref:`Editable Installs <editable-installs>`. #. Install a local project in "editable" mode. See the section on :ref:`Editable Installs <editable-installs>`.
:: .. tabs::
$ pip install -e . # project in current directory .. group-tab:: Unix/macOS
$ pip install -e path/to/project # project in another directory
.. 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
.. code-block:: shell
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 #. Install a project from VCS
:: .. tabs::
$ pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1 .. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1
.. group-tab:: Windows
.. code-block:: shell
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 <VCS Support>` and :ref:`Editable Installs <editable-installs>`. #. 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
.. 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
.. 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
$ pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git
$ pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial
$ pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn
$ pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomePackage # from 'feature' branch
$ 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`_. #. Install a package with `setuptools extras`_.
:: .. tabs::
$ pip install SomePackage[PDF] .. group-tab:: Unix/macOS
$ pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@master#subdirectory=subdir_path"
$ pip install .[PDF] # project in current directory .. code-block:: shell
$ pip install SomePackage[PDF]==3.0
$ 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
.. 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
#. Install a particular source archive file. #. Install a particular source archive file.
:: .. tabs::
$ pip install ./downloads/SomePackage-1.0.4.tar.gz .. group-tab:: Unix/macOS
$ pip install http://my.package.repo/SomePackage-1.0.4.zip
.. 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
.. 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. #. Install a particular source archive file following :pep:`440` direct references.
:: .. tabs::
$ pip install SomeProject@http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl .. group-tab:: Unix/macOS
$ pip install "SomeProject @ http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl"
$ pip install SomeProject@http://my.package.repo/1.2.3.tar.gz .. 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
.. 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
#. Install from alternative package repositories. #. Install from alternative package repositories.
Install from a different index, and not `PyPI`_ :: Install from a different index, and not `PyPI`_
$ pip install --index-url http://my.package.repo/simple/ SomePackage .. tabs::
Search an additional index during install, in addition to `PyPI`_ :: .. group-tab:: Unix/macOS
$ pip install --extra-index-url http://my.package.repo/simple SomePackage .. code-block:: shell
Install from a local flat directory containing archives (and don't scan indexes):: python -m pip install --index-url http://my.package.repo/simple/ SomePackage
$ pip install --no-index --find-links=file:///local/dir/ SomePackage .. group-tab:: Windows
$ pip install --no-index --find-links=/local/dir/ SomePackage
$ pip install --no-index --find-links=relative/dir/ 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::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install --extra-index-url http://my.package.repo/simple SomePackage
.. group-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
.. 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
.. group-tab:: Windows
.. 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
#. Find pre-release and development versions, in addition to stable versions. By default, pip only finds stable versions. #. Find pre-release and development versions, in addition to stable versions. By default, pip only finds stable versions.
:: .. tabs::
$ pip install --pre SomePackage .. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install --pre SomePackage
.. group-tab:: Windows
.. code-block:: shell
py -m pip install --pre SomePackage
#. Install packages from source. #. Install packages from source.
Do not use any binary packages:: Do not use any binary packages
$ pip install SomePackage1 SomePackage2 --no-binary :all: .. tabs::
Specify ``SomePackage1`` to be installed from source:: .. group-tab:: Unix/macOS
$ pip install SomePackage1 SomePackage2 --no-binary SomePackage1 .. code-block:: shell
python -m pip install SomePackage1 SomePackage2 --no-binary :all:
.. group-tab:: Windows
.. code-block:: shell
py -m pip install SomePackage1 SomePackage2 --no-binary :all:
Specify ``SomePackage1`` to be installed from source:
.. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1
.. group-tab:: Windows
.. code-block:: shell
py -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1
---- ----

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

@ -10,7 +10,15 @@ pip list
Usage Usage
===== =====
.. pip-command-usage:: list .. tabs::
.. group-tab:: Unix/macOS
.. pip-command-usage:: list "python -m pip"
.. group-tab:: Windows
.. pip-command-usage:: list "py -m pip"
Description Description
@ -32,75 +40,182 @@ Examples
#. List installed packages. #. List installed packages.
:: .. tabs::
$ pip list .. group-tab:: Unix/macOS
docutils (0.10)
Jinja2 (2.7.2) .. code-block:: console
MarkupSafe (0.18)
Pygments (1.6) $ python -m pip list
Sphinx (1.2.1) docutils (0.10)
Jinja2 (2.7.2)
MarkupSafe (0.18)
Pygments (1.6)
Sphinx (1.2.1)
.. group-tab:: Windows
.. 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)
#. List outdated packages (excluding editables), and the latest version available. #. List outdated packages (excluding editables), and the latest version available.
:: .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: console
$ python -m pip list --outdated
docutils (Current: 0.10 Latest: 0.11)
Sphinx (Current: 1.2.1 Latest: 1.2.2)
.. 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)
$ 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. #. List installed packages with column formatting.
:: .. tabs::
$ pip list --format columns .. group-tab:: Unix/macOS
Package Version
------- ------- .. code-block:: console
docopt 0.6.2
idlex 1.13 $ python -m pip list --format columns
jedi 0.9.0 Package Version
------- -------
docopt 0.6.2
idlex 1.13
jedi 0.9.0
.. group-tab:: Windows
.. code-block:: console
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. #. List outdated packages with column formatting.
:: .. tabs::
$ pip list -o --format columns .. group-tab:: Unix/macOS
Package Version Latest Type
---------- ------- ------ ----- .. code-block:: console
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
.. group-tab:: Windows
.. 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
#. List packages that are not dependencies of other packages. Can be combined with #. List packages that are not dependencies of other packages. Can be combined with
other options. other options.
:: .. tabs::
$ pip list --outdated --not-required .. group-tab:: Unix/macOS
docutils (Current: 0.10 Latest: 0.11)
.. code-block:: console
$ python -m pip list --outdated --not-required
docutils (Current: 0.10 Latest: 0.11)
.. group-tab:: Windows
.. code-block:: console
C:\> py -m pip list --outdated --not-required
docutils (Current: 0.10 Latest: 0.11)
#. Use legacy formatting #. Use legacy formatting
:: .. tabs::
$ pip list --format=legacy .. group-tab:: Unix/macOS
colorama (0.3.7)
docopt (0.6.2) .. code-block:: console
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)
.. group-tab:: Windows
.. 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)
#. Use json formatting #. Use json formatting
:: .. tabs::
$ pip list --format=json .. group-tab:: Unix/macOS
[{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ...
.. code-block:: console
$ python -m pip list --format=json
[{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ...
.. group-tab:: Windows
.. code-block:: console
C:\> py -m pip list --format=json
[{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ...
#. Use freeze formatting #. Use freeze formatting
:: .. tabs::
$ pip list --format=freeze .. group-tab:: Unix/macOS
colorama==0.3.7
docopt==0.6.2 .. code-block:: console
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
.. group-tab:: Windows
.. 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

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

@ -10,7 +10,15 @@ pip search
Usage Usage
===== =====
.. pip-command-usage:: search .. tabs::
.. group-tab:: Unix/macOS
.. pip-command-usage:: search "python -m pip"
.. group-tab:: Windows
.. pip-command-usage:: search "py -m pip"
Description Description
@ -30,8 +38,20 @@ Examples
#. Search for "peppercorn" #. Search for "peppercorn"
:: .. tabs::
$ pip search peppercorn .. group-tab:: Unix/macOS
pepperedform - Helpers for using peppercorn with formprocess.
peppercorn - A library for converting a token stream into [...] .. code-block:: console
$ python -m pip search peppercorn
pepperedform - Helpers for using peppercorn with formprocess.
peppercorn - A library for converting a token stream into [...]
.. group-tab:: Windows
.. 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 [...]

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

@ -10,7 +10,15 @@ pip show
Usage Usage
===== =====
.. pip-command-usage:: show .. tabs::
.. group-tab:: Unix/macOS
.. pip-command-usage:: show "python -m pip"
.. group-tab:: Windows
.. pip-command-usage:: show "py -m pip"
Description Description
@ -30,58 +38,124 @@ Examples
#. Show information about a package: #. Show information about a package:
:: .. tabs::
$ pip show sphinx .. group-tab:: Unix/macOS
Name: Sphinx
Version: 1.4.5 .. code-block:: console
Summary: Python documentation generator
Home-page: http://sphinx-doc.org/ $ python -m pip show sphinx
Author: Georg Brandl Name: Sphinx
Author-email: georg@python.org Version: 1.4.5
License: BSD Summary: Python documentation generator
Location: /my/env/lib/python2.7/site-packages Home-page: http://sphinx-doc.org/
Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six 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
.. group-tab:: Windows
.. 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
#. Show all information about a package #. Show all information about a package
:: .. tabs::
$ pip show --verbose sphinx .. group-tab:: Unix/macOS
Name: Sphinx
Version: 1.4.5 .. code-block:: console
Summary: Python documentation generator
Home-page: http://sphinx-doc.org/ $ python -m pip show --verbose sphinx
Author: Georg Brandl Name: Sphinx
Author-email: georg@python.org Version: 1.4.5
License: BSD Summary: Python documentation generator
Location: /my/env/lib/python2.7/site-packages Home-page: http://sphinx-doc.org/
Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six Author: Georg Brandl
Metadata-Version: 2.0 Author-email: georg@python.org
Installer: License: BSD
Classifiers: Location: /my/env/lib/python2.7/site-packages
Development Status :: 5 - Production/Stable Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six
Environment :: Console Metadata-Version: 2.0
Environment :: Web Environment Installer:
Intended Audience :: Developers Classifiers:
Intended Audience :: Education Development Status :: 5 - Production/Stable
License :: OSI Approved :: BSD License Environment :: Console
Operating System :: OS Independent Environment :: Web Environment
Programming Language :: Python Intended Audience :: Developers
Programming Language :: Python :: 2 Intended Audience :: Education
Programming Language :: Python :: 3 License :: OSI Approved :: BSD License
Framework :: Sphinx Operating System :: OS Independent
Framework :: Sphinx :: Extension Programming Language :: Python
Framework :: Sphinx :: Theme Programming Language :: Python :: 2
Topic :: Documentation Programming Language :: Python :: 3
Topic :: Documentation :: Sphinx Framework :: Sphinx
Topic :: Text Processing Framework :: Sphinx :: Extension
Topic :: Utilities Framework :: Sphinx :: Theme
Entry-points: Topic :: Documentation
[console_scripts] Topic :: Documentation :: Sphinx
sphinx-apidoc = sphinx.apidoc:main Topic :: Text Processing
sphinx-autogen = sphinx.ext.autosummary.generate:main Topic :: Utilities
sphinx-build = sphinx:main Entry-points:
sphinx-quickstart = sphinx.quickstart:main [console_scripts]
[distutils.commands] sphinx-apidoc = sphinx.apidoc:main
build_sphinx = sphinx.setup_command:BuildDoc sphinx-autogen = sphinx.ext.autosummary.generate:main
sphinx-build = sphinx:main
sphinx-quickstart = sphinx.quickstart:main
[distutils.commands]
build_sphinx = sphinx.setup_command:BuildDoc
.. group-tab:: Windows
.. 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

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

@ -10,7 +10,15 @@ pip uninstall
Usage Usage
===== =====
.. pip-command-usage:: uninstall .. tabs::
.. group-tab:: Unix/macOS
.. pip-command-usage:: uninstall "python -m pip"
.. group-tab:: Windows
.. pip-command-usage:: uninstall "py -m pip"
Description Description
@ -30,11 +38,26 @@ Examples
#. Uninstall a package. #. Uninstall a package.
:: .. tabs::
$ pip uninstall simplejson .. group-tab:: Unix/macOS
Uninstalling simplejson:
/home/me/env/lib/python2.7/site-packages/simplejson .. code-block:: console
/home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info
Proceed (y/n)? y $ python -m pip uninstall simplejson
Successfully uninstalled 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
.. group-tab:: Windows
.. 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

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

@ -11,7 +11,15 @@ pip wheel
Usage Usage
===== =====
.. pip-command-usage:: wheel .. tabs::
.. group-tab:: Unix/macOS
.. pip-command-usage:: wheel "python -m pip"
.. group-tab:: Windows
.. pip-command-usage:: wheel "py -m pip"
Description Description
@ -24,9 +32,22 @@ Build System Interface
---------------------- ----------------------
In order for pip to build a wheel, ``setup.py`` must implement the In order for pip to build a wheel, ``setup.py`` must implement the
``bdist_wheel`` command with the following syntax:: ``bdist_wheel`` command with the following syntax:
.. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python setup.py bdist_wheel -d TARGET
.. group-tab:: Windows
.. code-block:: shell
py setup.py bdist_wheel -d TARGET
python setup.py bdist_wheel -d TARGET
This command must create a wheel compatible with the invoking Python This command must create a wheel compatible with the invoking Python
interpreter, and save that wheel in the directory TARGET. interpreter, and save that wheel in the directory TARGET.
@ -39,9 +60,22 @@ Customising the build
It is possible using ``--global-option`` to include additional build commands It is possible using ``--global-option`` to include additional build commands
with their arguments in the ``setup.py`` command. This is currently the only 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 way to influence the building of C extensions from the command line. For
example:: example:
.. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip wheel --global-option bdist_ext --global-option -DFOO wheel
.. group-tab:: Windows
.. code-block:: shell
py -m pip wheel --global-option bdist_ext --global-option -DFOO wheel
pip wheel --global-option bdist_ext --global-option -DFOO wheel
will result in a build command of will result in a build command of
@ -69,13 +103,34 @@ Examples
#. Build wheels for a requirement (and all its dependencies), and then install #. Build wheels for a requirement (and all its dependencies), and then install
:: .. tabs::
$ pip wheel --wheel-dir=/tmp/wheelhouse SomePackage .. group-tab:: Unix/macOS
$ pip install --no-index --find-links=/tmp/wheelhouse SomePackage
.. 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
.. code-block:: shell
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 #. Build a wheel for a package from source
:: .. tabs::
$ pip wheel --no-binary SomePackage SomePackage .. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip wheel --no-binary SomePackage SomePackage
.. group-tab:: Windows
.. code-block:: shell
py -m pip wheel --no-binary SomePackage SomePackage

639
docs/html/user_guide.rst
View File

@ -9,23 +9,28 @@ Running pip
=========== ===========
pip is a command line program. When you install pip, a ``pip`` command is added 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:: to your system, which can be run from the command prompt as follows:
$ pip <pip arguments> .. tabs::
If you cannot run the ``pip`` command directly (possibly because the location .. group-tab:: Unix/macOS
where it was installed isn't on your operating system's ``PATH``) then you can
run pip via the Python interpreter::
$ python -m pip <pip arguments> .. code-block:: shell
On Windows, the ``py`` launcher can be used:: python -m pip <pip arguments>
$ py -m pip <pip arguments> ``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.
Even though pip is available from your Python installation as an importable .. group-tab:: Windows
module, via ``import pip``, it is *not supported* to use pip in this way. For
more details, see :ref:`Using pip from your program`. .. code-block:: shell
py -m pip <pip arguments>
``py -m pip`` executes pip using the latest Python interpreter you
have installed. For more details, read the `Python Windows launcher`_ docs.
Installing Packages Installing Packages
@ -36,12 +41,25 @@ directly from distribution files.
The most common scenario is to install from `PyPI`_ using :ref:`Requirement The most common scenario is to install from `PyPI`_ using :ref:`Requirement
Specifiers` :: Specifiers`
$ pip install SomePackage # latest version .. tabs::
$ pip install SomePackage==1.0.4 # specific version
$ pip install 'SomePackage>=1.0.4' # minimum version
.. group-tab:: Unix/macOS
.. 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
.. group-tab:: Windows
.. 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
For more information and examples, see the :ref:`pip install` reference. For more information and examples, see the :ref:`pip install` reference.
@ -77,6 +95,47 @@ as the "username" and do not provide a password, for example -
``https://0123456789abcdef@pypi.company.com`` ``https://0123456789abcdef@pypi.company.com``
netrc Support
-------------
If no credentials are part of the URL, pip will attempt to get authentication credentials
for the URL’s hostname from the user’s .netrc file. This behaviour comes from the underlying
use of `requests`_ which in turn delegates it to the `Python standard library`_.
The .netrc file contains login and initialization information used by the auto-login process.
It resides in the user's home directory. The .netrc file format is simple. You specify lines
with a machine name and follow that with lines for the login and password that are
associated with that machine. Machine name is the hostname in your URL.
An example .netrc for the host example.com with a user named 'daniel', using the password
'qwerty' would look like:
.. code-block:: shell
machine example.com
login daniel
password qwerty
As mentioned in the `standard library docs <https://docs.python.org/3/library/netrc.html>`_,
only ASCII characters are allowed. Whitespace and non-printable characters are not allowed in passwords.
Keyring Support
---------------
pip also supports credentials stored in your keyring using the `keyring`_
library. Note that ``keyring`` will need to be installed separately, as pip
does not come with it included.
.. code-block:: shell
pip install keyring
echo your-password | keyring set pypi.company.com your-username
pip install your-package --extra-index-url https://pypi.company.com/
.. _keyring: https://pypi.org/project/keyring/
Using a Proxy Server Using a Proxy Server
==================== ====================
@ -101,10 +160,21 @@ Requirements Files
================== ==================
"Requirements files" are files containing a list of items to be "Requirements files" are files containing a list of items to be
installed using :ref:`pip install` like so:: installed using :ref:`pip install` like so:
pip install -r requirements.txt .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install -r requirements.txt
.. group-tab:: Windows
.. code-block:: shell
py -m pip install -r requirements.txt
Details on the format of the files are here: :ref:`Requirements File Format`. Details on the format of the files are here: :ref:`Requirements File Format`.
@ -119,10 +189,21 @@ In practice, there are 4 common uses of Requirements files:
this case, your requirement file contains a pinned version of everything that this case, your requirement file contains a pinned version of everything that
was installed when ``pip freeze`` was run. was installed when ``pip freeze`` was run.
:: .. tabs::
pip freeze > requirements.txt .. group-tab:: Unix/macOS
pip install -r requirements.txt
.. code-block:: shell
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt
.. group-tab:: Windows
.. code-block:: shell
py -m pip freeze > requirements.txt
py -m pip install -r requirements.txt
2. Requirements files are used to force pip to properly resolve dependencies. 2. Requirements files are used to force pip to properly resolve dependencies.
As it is now, pip `doesn't have true dependency resolution As it is now, pip `doesn't have true dependency resolution
@ -187,9 +268,21 @@ contents is nearly identical to :ref:`Requirements Files`. There is one key
difference: Including a package in a constraints file does not trigger difference: Including a package in a constraints file does not trigger
installation of the package. installation of the package.
Use a constraints file like so:: Use a constraints file like so:
pip install -c constraints.txt .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install -c constraints.txt
.. group-tab:: Windows
.. code-block:: shell
py -m pip install -c constraints.txt
Constraints files are used for exactly the same reason as requirements files 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 when you don't know exactly what things you want to install. For instance, say
@ -227,9 +320,19 @@ archives.
To install directly from a wheel archive: To install directly from a wheel archive:
:: .. tabs::
pip install SomePackage-1.0-py2.py3-none-any.whl .. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install SomePackage-1.0-py2.py3-none-any.whl
.. group-tab:: Windows
.. code-block:: shell
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 For the cases where wheels are not available, pip offers :ref:`pip wheel` as a
@ -242,17 +345,38 @@ convenience, to build wheels for all your requirements and dependencies.
To build wheels for your requirements and all their dependencies to a local To build wheels for your requirements and all their dependencies to a local
directory: directory:
:: .. tabs::
pip install wheel .. group-tab:: Unix/macOS
pip wheel --wheel-dir=/local/wheels -r requirements.txt
.. code-block:: shell
python -m pip install wheel
python -m pip wheel --wheel-dir=/local/wheels -r requirements.txt
.. group-tab:: Windows
.. code-block:: shell
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 And *then* to install those requirements just using your local directory of
wheels (and not from PyPI): wheels (and not from PyPI):
:: .. tabs::
pip install --no-index --find-links=/local/wheels -r requirements.txt .. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install --no-index --find-links=/local/wheels -r requirements.txt
.. group-tab:: Windows
.. code-block:: shell
py -m pip install --no-index --find-links=/local/wheels -r requirements.txt
Uninstalling Packages Uninstalling Packages
@ -260,9 +384,20 @@ Uninstalling Packages
pip is able to uninstall most packages like so: pip is able to uninstall most packages like so:
:: .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip uninstall SomePackage
.. group-tab:: Windows
.. code-block:: shell
py -m pip uninstall SomePackage
$ pip uninstall SomePackage
pip also performs an automatic uninstall of an old version of a package pip also performs an automatic uninstall of an old version of a package
before upgrading to a newer version. before upgrading to a newer version.
@ -275,33 +410,74 @@ Listing Packages
To list installed packages: To list installed packages:
:: .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: console
$ python -m pip list
docutils (0.9.1)
Jinja2 (2.6)
Pygments (1.5)
Sphinx (1.1.2)
.. group-tab:: Windows
.. code-block:: console
C:\> py -m pip list
docutils (0.9.1)
Jinja2 (2.6)
Pygments (1.5)
Sphinx (1.1.2)
$ 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: To list outdated packages, and show the latest version available:
:: .. tabs::
$ pip list --outdated .. group-tab:: Unix/macOS
docutils (Current: 0.9.1 Latest: 0.10)
Sphinx (Current: 1.1.2 Latest: 1.1.3)
.. 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)
.. group-tab:: Windows
.. 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)
To show details about an installed package: To show details about an installed package:
:: .. tabs::
$ pip show sphinx .. group-tab:: Unix/macOS
---
Name: Sphinx .. code-block:: console
Version: 1.1.3
Location: /my/env/lib/pythonx.x/site-packages $ python -m pip show sphinx
Requires: Pygments, Jinja2, docutils ---
Name: Sphinx
Version: 1.1.3
Location: /my/env/lib/pythonx.x/site-packages
Requires: Pygments, Jinja2, docutils
.. 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
For more information and examples, see the :ref:`pip list` and :ref:`pip show` For more information and examples, see the :ref:`pip list` and :ref:`pip show`
@ -312,9 +488,21 @@ Searching for Packages
====================== ======================
pip can search `PyPI`_ for packages using the ``pip search`` pip can search `PyPI`_ for packages using the ``pip search``
command:: command:
$ pip search "query" .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip search "query"
.. group-tab:: Windows
.. code-block:: shell
py -m pip search "query"
The query will be used to search the names and summaries of all The query will be used to search the names and summaries of all
packages. packages.
@ -436,6 +624,15 @@ and ``--no-cache-dir``, falsy values have to be used:
no-compile = no no-compile = no
no-warn-script-location = false no-warn-script-location = false
For options which can be repeated like ``--verbose`` and ``--quiet``,
a non-negative integer can be used to represent the level to be specified:
.. code-block:: ini
[global]
quiet = 0
verbose = 2
It is possible to append values to a section within a configuration file such as the pip.ini file. It is possible to append values to a section within a configuration file such as the pip.ini file.
This is applicable to appending options like ``--find-links`` or ``--trusted-host``, This is applicable to appending options like ``--find-links`` or ``--trusted-host``,
which can be written on multiple lines: which can be written on multiple lines:
@ -465,22 +662,81 @@ pip's command line options can be set with environment variables using the
format ``PIP_<UPPER_LONG_NAME>`` . Dashes (``-``) have to be replaced with format ``PIP_<UPPER_LONG_NAME>`` . Dashes (``-``) have to be replaced with
underscores (``_``). underscores (``_``).
For example, to set the default timeout:: For example, to set the default timeout:
export PIP_DEFAULT_TIMEOUT=60 .. tabs::
This is the same as passing the option to pip directly:: .. group-tab:: Unix/macOS
pip --default-timeout=60 [...] .. code-block:: shell
export PIP_DEFAULT_TIMEOUT=60
.. group-tab:: Windows
.. code-block:: shell
set PIP_DEFAULT_TIMEOUT=60
This is the same as passing the option to pip directly:
.. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip --default-timeout=60 [...]
.. group-tab:: Windows
.. code-block:: shell
py -m pip --default-timeout=60 [...]
For command line options which can be repeated, use a space to separate For command line options which can be repeated, use a space to separate
multiple values. For example:: multiple values. For example:
export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com" .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
.. group-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
.. code-block:: shell
python -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
.. group-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::
export PIP_VERBOSE=3
is the same as calling:: is the same as calling::
pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com pip install -vvv
.. note:: .. note::
@ -514,15 +770,15 @@ pip comes with support for command line completion in bash, zsh and fish.
To setup for bash:: To setup for bash::
$ pip completion --bash >> ~/.profile python -m pip completion --bash >> ~/.profile
To setup for zsh:: To setup for zsh::
$ pip completion --zsh >> ~/.zprofile python -m pip completion --zsh >> ~/.zprofile
To setup for fish:: To setup for fish::
$ pip completion --fish > ~/.config/fish/completions/pip.fish python -m pip completion --fish > ~/.config/fish/completions/pip.fish
Alternatively, you can use the result of the ``completion`` command directly Alternatively, you can use the result of the ``completion`` command directly
with the eval function of your shell, e.g. by adding the following to your with the eval function of your shell, e.g. by adding the following to your
@ -541,24 +797,59 @@ Installing from local packages
In some cases, you may want to install from local packages only, with no traffic In some cases, you may want to install from local packages only, with no traffic
to PyPI. to PyPI.
First, download the archives that fulfill your requirements:: First, download the archives that fulfill your requirements:
$ pip download --destination-directory DIR -r requirements.txt .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip download --destination-directory DIR -r requirements.txt
.. group-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 Note that ``pip download`` will look in your wheel cache first, before
trying to download from PyPI. If you've never installed your requirements 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 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 your requirements don't come as wheels from PyPI, and you want wheels, then run
this instead:: this instead:
$ pip wheel --wheel-dir DIR -r requirements.txt .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip wheel --wheel-dir DIR -r requirements.txt
.. group-tab:: Windows
.. code-block:: shell
py -m pip wheel --wheel-dir DIR -r requirements.txt
Then, to install from local only, you'll be using :ref:`--find-links 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:: <install_--find-links>` and :ref:`--no-index <install_--no-index>` like so:
$ pip install --no-index --find-links=DIR -r requirements.txt .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install --no-index --find-links=DIR -r requirements.txt
.. group-tab:: Windows
.. code-block:: shell
py -m pip install --no-index --find-links=DIR -r requirements.txt
"Only if needed" Recursive Upgrade "Only if needed" Recursive Upgrade
@ -577,10 +868,24 @@ The default strategy is ``only-if-needed``. This was changed in pip 10.0 due to
the breaking nature of ``eager`` when upgrading conflicting dependencies. the breaking nature of ``eager`` when upgrading conflicting dependencies.
As an historic note, an earlier "fix" for getting the ``only-if-needed`` As an historic note, an earlier "fix" for getting the ``only-if-needed``
behaviour was:: behaviour was:
.. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install --upgrade --no-deps SomePackage
python -m pip install SomePackage
.. group-tab:: Windows
.. code-block:: shell
py -m pip install --upgrade --no-deps SomePackage
py -m pip install SomePackage
pip install --upgrade --no-deps SomePackage
pip install SomePackage
A proposal for an ``upgrade-all`` command is being considered as a safer A proposal for an ``upgrade-all`` command is being considered as a safer
alternative to the behaviour of eager upgrading. alternative to the behaviour of eager upgrading.
@ -603,11 +908,23 @@ Moreover, the "user scheme" can be customized by setting the
``site.USER_BASE``. ``site.USER_BASE``.
To install "SomePackage" into an environment with site.USER_BASE customized to To install "SomePackage" into an environment with site.USER_BASE customized to
'/myappenv', do the following:: '/myappenv', do the following:
export PYTHONUSERBASE=/myappenv .. tabs::
pip install --user SomePackage
.. group-tab:: Unix/macOS
.. code-block:: shell
export PYTHONUSERBASE=/myappenv
python -m pip install --user SomePackage
.. group-tab:: Windows
.. code-block:: shell
set PYTHONUSERBASE=c:/myappenv
py -m pip install --user SomePackage
``pip install --user`` follows four rules: ``pip install --user`` follows four rules:
@ -630,54 +947,125 @@ To install "SomePackage" into an environment with site.USER_BASE customized to
To make the rules clearer, here are some examples: To make the rules clearer, here are some examples:
From within a ``--no-site-packages`` virtualenv (i.e. the default kind):: From within a ``--no-site-packages`` virtualenv (i.e. the default kind):
$ pip install --user SomePackage .. tabs::
Can not perform a '--user' install. User site-packages are not visible in this virtualenv.
.. group-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
.. 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.
From within a ``--system-site-packages`` virtualenv where ``SomePackage==0.3`` From within a ``--system-site-packages`` virtualenv where ``SomePackage==0.3``
is already installed in the virtualenv:: is already installed in the virtualenv:
$ pip install --user SomePackage==0.4 .. tabs::
Will not install to the user site because it will lack sys.path precedence
.. group-tab:: Unix/macOS
From within a real python, where ``SomePackage`` is *not* installed globally:: .. code-block:: console
$ pip install --user SomePackage $ python -m pip install --user SomePackage==0.4
[...] Will not install to the user site because it will lack sys.path precedence
Successfully installed SomePackage
.. group-tab:: Windows
.. 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
From within a real python, where ``SomePackage`` is *not* installed globally:
.. tabs::
.. group-tab:: Unix/macOS
.. code-block:: console
$ python -m pip install --user SomePackage
[...]
Successfully installed SomePackage
.. group-tab:: Windows
.. code-block:: console
C:\> py -m pip install --user SomePackage
[...]
Successfully installed SomePackage
From within a real python, where ``SomePackage`` *is* installed globally, but From within a real python, where ``SomePackage`` *is* installed globally, but
is *not* the latest version:: is *not* the latest version:
$ pip install --user SomePackage .. tabs::
[...]
Requirement already satisfied (use --upgrade to upgrade)
$ pip install --user --upgrade SomePackage .. group-tab:: Unix/macOS
[...]
Successfully installed SomePackage
.. 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
.. group-tab:: Windows
.. 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
From within a real python, where ``SomePackage`` *is* installed globally, and From within a real python, where ``SomePackage`` *is* installed globally, and
is the latest version:: is the latest version:
$ pip install --user SomePackage .. tabs::
[...]
Requirement already satisfied (use --upgrade to upgrade)
$ pip install --user --upgrade SomePackage .. group-tab:: Unix/macOS
[...]
Requirement already up-to-date: SomePackage
# force the install .. code-block:: console
$ 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
.. group-tab:: Windows
.. 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
.. _`Repeatability`: .. _`Repeatability`:
@ -742,7 +1130,7 @@ index servers are unavailable and avoids time-consuming recompilation. Create
an archive like this:: an archive like this::
$ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX) $ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX)
$ pip wheel -r requirements.txt --wheel-dir=$tempdir $ python -m pip wheel -r requirements.txt --wheel-dir=$tempdir
$ cwd=`pwd` $ cwd=`pwd`
$ (cd "$tempdir"; tar -cjvf "$cwd/bundled.tar.bz2" *) $ (cd "$tempdir"; tar -cjvf "$cwd/bundled.tar.bz2" *)
@ -750,10 +1138,10 @@ You can then install from the archive like this::
$ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX) $ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX)
$ (cd $tempdir; tar -xvf /path/to/bundled.tar.bz2) $ (cd $tempdir; tar -xvf /path/to/bundled.tar.bz2)
$ pip install --force-reinstall --ignore-installed --upgrade --no-index --no-deps $tempdir/* $ python -m pip install --force-reinstall --ignore-installed --upgrade --no-index --no-deps $tempdir/*
Note that compiled packages are typically OS- and architecture-specific, so Note that compiled packages are typically OS- and architecture-specific, so
these archives are not necessarily portable across machines. these archives are not necessarily portable across macOShines.
Hash-checking mode can be used along with this method to ensure that future Hash-checking mode can be used along with this method to ensure that future
archives are built with identical packages. archives are built with identical packages.
@ -766,8 +1154,6 @@ archives are built with identical packages.
to use such a package, see :ref:`Controlling to use such a package, see :ref:`Controlling
setup_requires<controlling-setup-requires>`. setup_requires<controlling-setup-requires>`.
.. _`Using pip from your program`:
Fixing conflicting dependencies Fixing conflicting dependencies
=============================== ===============================
@ -785,10 +1171,22 @@ Understanding your error message
When you get a ``ResolutionImpossible`` error, you might see something When you get a ``ResolutionImpossible`` error, you might see something
like this: like this:
.. code-block:: console .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install package_coffee==0.44.1 package_tea==4.3.0
.. group-tab:: Windows
.. code-block:: shell
py -m pip install package_coffee==0.44.1 package_tea==4.3.0
::
$ pip install package_coffee==0.44.1 package_tea==4.3.0
...
Due to conflicting dependencies pip cannot install Due to conflicting dependencies pip cannot install
package_coffee and package_tea: package_coffee and package_tea:
- package_coffee depends on package_water<3.0.0,>=2.4.2 - package_coffee depends on package_water<3.0.0,>=2.4.2
@ -879,7 +1277,7 @@ the same version of ``package_water``, you might consider:
(e.g. ``pip install "package_coffee>0.44.*" "package_tea>4.0.0"``) (e.g. ``pip install "package_coffee>0.44.*" "package_tea>4.0.0"``)
- Asking pip to install *any* version of ``package_coffee`` and ``package_tea`` - Asking pip to install *any* version of ``package_coffee`` and ``package_tea``
by removing the version specifiers altogether (e.g. by removing the version specifiers altogether (e.g.
``pip install package_coffee package_tea``) ``python -m pip install package_coffee package_tea``)
In the second case, pip will automatically find a version of both In the second case, pip will automatically find a version of both
``package_coffee`` and ``package_tea`` that depend on the same version of ``package_coffee`` and ``package_tea`` that depend on the same version of
@ -889,9 +1287,21 @@ In the second case, pip will automatically find a version of both
- ``package_tea 4.3.0`` which *also* depends on ``package_water 2.6.1`` - ``package_tea 4.3.0`` which *also* depends on ``package_water 2.6.1``
If you want to prioritize one package over another, you can add version If you want to prioritize one package over another, you can add version
specifiers to *only* the more important package:: specifiers to *only* the more important package:
pip install package_coffee==0.44.1b0 package_tea .. tabs::
.. group-tab:: Unix/macOS
.. code-block:: shell
python -m pip install package_coffee==0.44.1b0 package_tea
.. group-tab:: Windows
.. code-block:: shell
py -m pip install package_coffee==0.44.1b0 package_tea
This will result in: This will result in:
@ -957,6 +1367,8 @@ issue tracker`_ if you believe that your problem has exposed a bug in pip.
.. _"How do I ask a good question?": https://stackoverflow.com/help/how-to-ask .. _"How do I ask a good question?": https://stackoverflow.com/help/how-to-ask
.. _pip issue tracker: https://github.com/pypa/pip/issues .. _pip issue tracker: https://github.com/pypa/pip/issues
.. _`Using pip from your program`:
Using pip from your program Using pip from your program
=========================== ===========================
@ -1046,7 +1458,7 @@ The big change in this release is to the pip dependency resolver
within pip. within pip.
Computers need to know the right order to install pieces of software Computers need to know the right order to install pieces of software
("to install `x`, you need to install `y` first"). So, when Python ("to install ``x``, you need to install ``y`` first"). So, when Python
programmers share software as packages, they have to precisely describe programmers share software as packages, they have to precisely describe
those installation prerequisites, and pip needs to navigate tricky those installation prerequisites, and pip needs to navigate tricky
situations where it's getting conflicting instructions. This new situations where it's getting conflicting instructions. This new
@ -1271,3 +1683,6 @@ announcements on the `low-traffic packaging announcements list`_ and
.. _low-traffic packaging announcements list: https://mail.python.org/mailman3/lists/pypi-announce.python.org/ .. _low-traffic packaging announcements list: https://mail.python.org/mailman3/lists/pypi-announce.python.org/
.. _our survey on upgrades that create conflicts: https://docs.google.com/forms/d/e/1FAIpQLSeBkbhuIlSofXqCyhi3kGkLmtrpPOEBwr6iJA6SzHdxWKfqdA/viewform .. _our survey on upgrades that create conflicts: https://docs.google.com/forms/d/e/1FAIpQLSeBkbhuIlSofXqCyhi3kGkLmtrpPOEBwr6iJA6SzHdxWKfqdA/viewform
.. _the official Python blog: https://blog.python.org/ .. _the official Python blog: https://blog.python.org/
.. _requests: https://requests.readthedocs.io/en/master/user/authentication/#netrc-authentication
.. _Python standard library: https://docs.python.org/3/library/netrc.html
.. _Python Windows launcher: https://docs.python.org/3/using/windows.html#launcher

8
docs/pip_sphinxext.py
View File

@ -15,11 +15,17 @@ from pip._internal.req.req_file import SUPPORTED_OPTIONS
class PipCommandUsage(rst.Directive): class PipCommandUsage(rst.Directive):
required_arguments = 1 required_arguments = 1
optional_arguments = 3
def run(self): def run(self):
cmd = create_command(self.arguments[0]) cmd = create_command(self.arguments[0])
cmd_prefix = 'python -m pip'
if len(self.arguments) > 1:
cmd_prefix = " ".join(self.arguments[1:])
cmd_prefix = cmd_prefix.strip('"')
cmd_prefix = cmd_prefix.strip("'")
usage = dedent( usage = dedent(
cmd.usage.replace('%prog', 'pip {}'.format(cmd.name)) cmd.usage.replace('%prog', '{} {}'.format(cmd_prefix, cmd.name))
).strip() ).strip()
node = nodes.literal_block(usage, usage) node = nodes.literal_block(usage, usage)
return [node] return [node]

0
news/093f7456-cc25-4df9-9518-4732b1e07fe5.trivial.rst Normal file
View File

0
news/0e494986-202e-4275-b7ec-d6f046c0aa05.trivial.rst Normal file
View File

0
news/24715eb2-c118-473b-9d99-4f6ce8bbfa83.trivial.rst Normal file
View File

0
news/2a1e2773-eae6-43a4-b075-55f49e713fb1.trivial.rst Normal file
View File

0
news/4c82ffb4-cde3-4dd5-8f37-6f4ef53e028b.trivial.rst Normal file
View File

0
news/50cf024d-0a74-44c8-b3e9-483dd826fff2.trivial.rst Normal file
View File

0
news/559bb022-21ae-498c-a2ce-2c354d880f5e.trivial.rst Normal file
View File

0
news/5e8c60c2-d540-4a25-af03-100d848acbc0.trivial.rst Normal file
View File

0
news/629892ca-55da-4ca9-9cff-c15373e97ad1.trivial.rst Normal file
View File

0
news/6f8eff8d-9886-4e00-b431-5c809500e6bf.trivial.rst Normal file
View File

1
news/7231.doc.rst Normal file
View File

@ -0,0 +1 @@
Add documentation for '.netrc' support.

1
news/7311.doc.rst Normal file
View File

@ -0,0 +1 @@
Add OS tabs for OS-specific commands.

2
news/8023.feature.rst Normal file
View File

@ -0,0 +1,2 @@
New resolver: Avoid accessing indexes when the installed candidate is preferred
and considered good enough.

2
news/8103.bugfix.rst Normal file
View File

@ -0,0 +1,2 @@
Propagate ``--extra-index-url`` from requirements file properly to session auth,
so that keyring auth will work as expected.

1
news/8181.removal.rst Normal file
View File

@ -0,0 +1 @@
Deprecate support for Python 3.5

1
news/8355.feature.rst Normal file
View File

@ -0,0 +1 @@
Add option ``--format`` to subcommand ``list`` of ``pip cache``, with ``abspath`` choice to output the full path of a wheel file.

1
news/8417.removal.rst Normal file
View File

@ -0,0 +1 @@
Document that certain removals can be fast tracked.

4
news/8578.bugfix.rst Normal file
View File

@ -0,0 +1,4 @@
Allow specifying verbosity and quiet level via configuration files
and environment variables. Previously these options were treated as
boolean values when read from there while through CLI the level can be
specified.

1
news/8636.doc.rst Normal file
View File

@ -0,0 +1 @@
Add note and example on keyring support for index basic-auth

2
news/8676.feature.rst Normal file
View File

@ -0,0 +1,2 @@
Improve error message friendliness when an environment has packages with
corrupted metadata.

3
news/8696.bugfix.rst Normal file
View File

@ -0,0 +1,3 @@
List downloaded distributions before exiting ``pip download``
when using the new resolver to make the behavior the same as
that on the legacy resolver.

3
news/8752.feature.rst Normal file
View File

@ -0,0 +1,3 @@
Make the ``setup.py install`` deprecation warning less noisy. We warn only
when ``setup.py install`` succeeded and ``setup.py bdist_wheel`` failed, as
situations where both fails are most probably irrelevant to this deprecation.

2
news/8758.bugfix.rst Normal file
View File

@ -0,0 +1,2 @@
New resolver: Correctly respect ``Requires-Python`` metadata to reject
incompatible packages in ``--no-deps`` mode.

1
news/8781.trivial.rst Normal file
View File

@ -0,0 +1 @@
Fix a broken slug anchor in user guide.

1
news/8783.doc.rst Normal file
View File

@ -0,0 +1 @@
Added initial UX feedback widgets to docs.

2
news/8792.bugfix.rst Normal file
View File

@ -0,0 +1,2 @@
New resolver: Pick up hash declarations in constraints files and use them to
filter available distributions.

3
news/8804.feature.rst Normal file
View File

@ -0,0 +1,3 @@
Check the download directory for existing wheels to possibly avoid
fetching metadata when the ``fast-deps`` feature is used with
``pip wheel`` and ``pip download``.

1
news/8807.doc.rst Normal file
View File

@ -0,0 +1 @@
Add ux documentation

2
news/8815.feature.rst Normal file
View File

@ -0,0 +1,2 @@
When installing a git URL that refers to a commit that is not available locally
after git clone, attempt to fetch it from the remote.

2
news/8827.bugfix.rst Normal file
View File

@ -0,0 +1,2 @@
Avoid polluting the destination directory by resolution artifacts
when the new resolver is used for ``pip download`` or ``pip wheel``.

3
news/8839.bugfix.rst Normal file
View File

@ -0,0 +1,3 @@
New resolver: If a package appears multiple times in user specification with
different ``--hash`` options, only hashes that present in all specifications
should be allowed.

1
news/8848.doc.rst Normal file
View File

@ -0,0 +1 @@
Added initial UX feedback widgets to docs.

1
news/8861.bugfix.rst Normal file
View File

@ -0,0 +1 @@
Tweak the output during dependency resolution in the new resolver.

1
news/8892.feature.rst Normal file
View File

@ -0,0 +1 @@
Include http subdirectory in ``pip cache info`` and ``pip cache purge`` commands.

3
news/8905.feature.rst Normal file
View File

@ -0,0 +1,3 @@
Cache package listings on index packages so they are guarenteed to stay stable
during a pip command session. This also improves performance when a index page
is accessed multiple times during the command session.

2
news/8924.feature.rst Normal file
View File

@ -0,0 +1,2 @@
New resolver: Tweak resolution logic to improve user experience when
user-supplied requirements conflict.

1
news/8927.removal.rst Normal file
View File

@ -0,0 +1 @@
Document that Python versions are generally supported until PyPI usage falls below 5%.

2
news/8963.bugfix.rst Normal file
View File

@ -0,0 +1,2 @@
Correctly search for installed distributions in new resolver logic in order
to not miss packages (virtualenv packages from system-wide-packages for example)

0
news/946beace-6164-4d1a-a05d-e9bebf43ccd0.trivial.rst Normal file
View File

0
news/9f8da1d9-dd18-47e9-b334-5eb862054409.trivial.rst Normal file
View File

0
news/a2fa2e68-01bf-11eb-a0b1-4fe8cb1f9dcf.trivial.rst Normal file
View File

0
news/a3a2b1b7-744e-4533-b3ff-6e7a1843d573.trivial.rst Normal file
View File

0
news/bc7f9ea0-030d-11eb-92cb-6b2b625d02fc.trivial.rst Normal file
View File

0
news/c6182139-edb4-4bf6-bc3f-2d37cb5759ad.trivial.rst Normal file
View File

0
news/d53425e4-767e-4d73-bce5-88644b781855.trivial.rst Normal file
View File

0
news/d90a40c1-15b7-46b9-9162-335bb346b53f.trivial.rst Normal file
View File

14
setup.cfg
View File

@ -1,4 +1,5 @@
[isort] [isort]
profile = black
skip = skip =
./build, ./build,
.nox, .nox,
@ -6,16 +7,11 @@ skip =
.scratch, .scratch,
_vendor, _vendor,
data data
multi_line_output = 3
known_third_party = known_third_party =
pip._vendor pip._vendor
known_first_party =
pip
tests
default_section = THIRDPARTY
include_trailing_comma = true
[flake8] [flake8]
max-line-length = 88
exclude = exclude =
./build, ./build,
.nox, .nox,
@ -24,10 +20,10 @@ exclude =
_vendor, _vendor,
data data
enable-extensions = G enable-extensions = G
ignore = extend-ignore =
G200, G202, G200, G202,
# pycodestyle checks ignored in the default configuration # black adds spaces around ':'
E121, E123, E126, E133, E226, E241, E242, E704, W503, W504, W505, E203,
per-file-ignores = per-file-ignores =
# G: The plugin logging-format treats every .log and .error as logging. # G: The plugin logging-format treats every .log and .error as logging.
noxfile.py: G noxfile.py: G

2
src/pip/_internal/__init__.py
View File

@ -2,7 +2,7 @@ import pip._internal.utils.inject_securetransport # noqa
from pip._internal.utils.typing import MYPY_CHECK_RUNNING from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from typing import Optional, List from typing import List, Optional
def main(args=None): def main(args=None):

3
src/pip/_internal/build_env.py
View File

@ -19,7 +19,8 @@ from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from types import TracebackType from types import TracebackType
from typing import Tuple, Set, Iterable, Optional, List, Type from typing import Iterable, List, Optional, Set, Tuple, Type
from pip._internal.index.package_finder import PackageFinder from pip._internal.index.package_finder import PackageFinder
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)

2
src/pip/_internal/cache.py
View File

@ -17,7 +17,7 @@ from pip._internal.utils.typing import MYPY_CHECK_RUNNING
from pip._internal.utils.urls import path_to_url from pip._internal.utils.urls import path_to_url
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from typing import Optional, Set, List, Any, Dict from typing import Any, Dict, List, Optional, Set
from pip._vendor.packaging.tags import Tag from pip._vendor.packaging.tags import Tag

14
src/pip/_internal/cli/base_command.py
View File

@ -12,10 +12,7 @@ import traceback
from pip._internal.cli import cmdoptions from pip._internal.cli import cmdoptions
from pip._internal.cli.command_context import CommandContextMixIn from pip._internal.cli.command_context import CommandContextMixIn
from pip._internal.cli.parser import ( from pip._internal.cli.parser import ConfigOptionParser, UpdatingDefaultsHelpFormatter
ConfigOptionParser,
UpdatingDefaultsHelpFormatter,
)
from pip._internal.cli.status_codes import ( from pip._internal.cli.status_codes import (
ERROR, ERROR,
PREVIOUS_BUILD_DIR_ERROR, PREVIOUS_BUILD_DIR_ERROR,
@ -35,19 +32,16 @@ from pip._internal.utils.deprecation import deprecated
from pip._internal.utils.filesystem import check_path_owner from pip._internal.utils.filesystem import check_path_owner
from pip._internal.utils.logging import BrokenStdoutLoggingError, setup_logging from pip._internal.utils.logging import BrokenStdoutLoggingError, setup_logging
from pip._internal.utils.misc import get_prog, normalize_path from pip._internal.utils.misc import get_prog, normalize_path
from pip._internal.utils.temp_dir import ( from pip._internal.utils.temp_dir import global_tempdir_manager, tempdir_registry
global_tempdir_manager,
tempdir_registry,
)
from pip._internal.utils.typing import MYPY_CHECK_RUNNING from pip._internal.utils.typing import MYPY_CHECK_RUNNING
from pip._internal.utils.virtualenv import running_under_virtualenv from pip._internal.utils.virtualenv import running_under_virtualenv
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from typing import List, Optional, Tuple, Any
from optparse import Values from optparse import Values
from typing import Any, List, Optional, Tuple
from pip._internal.utils.temp_dir import ( from pip._internal.utils.temp_dir import (
TempDirectoryTypeRegistry as TempDirRegistry TempDirectoryTypeRegistry as TempDirRegistry,
) )
__all__ = ['Command'] __all__ = ['Command']

5
src/pip/_internal/cli/cmdoptions.py
View File

@ -30,8 +30,9 @@ from pip._internal.utils.hashes import STRONG_HASHES
from pip._internal.utils.typing import MYPY_CHECK_RUNNING from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from typing import Any, Callable, Dict, Optional, Tuple
from optparse import OptionParser, Values from optparse import OptionParser, Values
from typing import Any, Callable, Dict, Optional, Tuple
from pip._internal.cli.parser import ConfigOptionParser from pip._internal.cli.parser import ConfigOptionParser
@ -187,7 +188,7 @@ no_color = partial(
dest='no_color', dest='no_color',
action='store_true', action='store_true',
default=False, default=False,
help="Suppress colored output", help="Suppress colored output.",
) # type: Callable[..., Option] ) # type: Callable[..., Option]
version = partial( version = partial(

2
src/pip/_internal/cli/command_context.py
View File

@ -5,7 +5,7 @@ from pip._vendor.contextlib2 import ExitStack
from pip._internal.utils.typing import MYPY_CHECK_RUNNING from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from typing import Iterator, ContextManager, TypeVar from typing import ContextManager, Iterator, TypeVar
_T = TypeVar('_T', covariant=True) _T = TypeVar('_T', covariant=True)

7
src/pip/_internal/cli/main_parser.py
View File

@ -5,17 +5,14 @@ import os
import sys import sys
from pip._internal.cli import cmdoptions from pip._internal.cli import cmdoptions
from pip._internal.cli.parser import ( from pip._internal.cli.parser import ConfigOptionParser, UpdatingDefaultsHelpFormatter
ConfigOptionParser,
UpdatingDefaultsHelpFormatter,
)
from pip._internal.commands import commands_dict, get_similar_commands from pip._internal.commands import commands_dict, get_similar_commands
from pip._internal.exceptions import CommandError from pip._internal.exceptions import CommandError
from pip._internal.utils.misc import get_pip_version, get_prog from pip._internal.utils.misc import get_pip_version, get_prog
from pip._internal.utils.typing import MYPY_CHECK_RUNNING from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from typing import Tuple, List from typing import List, Tuple
__all__ = ["create_main_parser", "parse_command"] __all__ = ["create_main_parser", "parse_command"]

36
src/pip/_internal/cli/parser.py
View File

@ -11,6 +11,7 @@ import sys
import textwrap import textwrap
from distutils.util import strtobool from distutils.util import strtobool
from pip._vendor.contextlib2 import suppress
from pip._vendor.six import string_types from pip._vendor.six import string_types
from pip._internal.cli.status_codes import UNKNOWN_ERROR from pip._internal.cli.status_codes import UNKNOWN_ERROR
@ -197,15 +198,27 @@ class ConfigOptionParser(CustomOptionParser):
if option is None: if option is None:
continue continue
if option.action in ('store_true', 'store_false', 'count'): if option.action in ('store_true', 'store_false'):
try: try:
val = strtobool(val) val = strtobool(val)
except ValueError: except ValueError:
error_msg = invalid_config_error_message( self.error(
option.action, key, val '{} is not a valid value for {} option, ' # noqa
'please specify a boolean value like yes/no, '
'true/false or 1/0 instead.'.format(val, key)
)
elif option.action == 'count':
with suppress(ValueError):
val = strtobool(val)
with suppress(ValueError):
val = int(val)
if not isinstance(val, int) or val < 0:
self.error(
'{} is not a valid value for {} option, ' # noqa
'please instead specify either a non-negative integer '
'or a boolean value like yes/no or false/true '
'which is equivalent to 1/0.'.format(val, key)
) )
self.error(error_msg)
elif option.action == 'append': elif option.action == 'append':
val = val.split() val = val.split()
val = [self.check_default(option, key, v) for v in val] val = [self.check_default(option, key, v) for v in val]
@ -251,16 +264,3 @@ class ConfigOptionParser(CustomOptionParser):
def error(self, msg): def error(self, msg):
self.print_usage(sys.stderr) self.print_usage(sys.stderr)
self.exit(UNKNOWN_ERROR, "{}\n".format(msg)) self.exit(UNKNOWN_ERROR, "{}\n".format(msg))
def invalid_config_error_message(action, key, val):
"""Returns a better error message when invalid configuration option
is provided."""
if action in ('store_true', 'store_false'):
return ("{0} is not a valid value for {1} option, "
"please specify a boolean value like yes/no, "
"true/false or 1/0 instead.").format(val, key)
return ("{0} is not a valid value for {1} option, "
"please specify a numerical value like 1/0 "
"instead.").format(val, key)

29
src/pip/_internal/cli/req_command.py
View File

@ -16,7 +16,6 @@ from pip._internal.exceptions import CommandError, PreviousBuildDirError
from pip._internal.index.collector import LinkCollector from pip._internal.index.collector import LinkCollector
from pip._internal.index.package_finder import PackageFinder from pip._internal.index.package_finder import PackageFinder
from pip._internal.models.selection_prefs import SelectionPreferences from pip._internal.models.selection_prefs import SelectionPreferences
from pip._internal.network.download import Downloader
from pip._internal.network.session import PipSession from pip._internal.network.session import PipSession
from pip._internal.operations.prepare import RequirementPreparer from pip._internal.operations.prepare import RequirementPreparer
from pip._internal.req.constructors import ( from pip._internal.req.constructors import (
@ -39,10 +38,7 @@ if MYPY_CHECK_RUNNING:
from pip._internal.req.req_install import InstallRequirement from pip._internal.req.req_install import InstallRequirement
from pip._internal.req.req_tracker import RequirementTracker from pip._internal.req.req_tracker import RequirementTracker
from pip._internal.resolution.base import BaseResolver from pip._internal.resolution.base import BaseResolver
from pip._internal.utils.temp_dir import ( from pip._internal.utils.temp_dir import TempDirectory, TempDirectoryTypeRegistry
TempDirectory,
TempDirectoryTypeRegistry,
)
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
@ -207,28 +203,39 @@ class RequirementCommand(IndexGroupCommand):
finder, # type: PackageFinder finder, # type: PackageFinder
use_user_site, # type: bool use_user_site, # type: bool
download_dir=None, # type: str download_dir=None, # type: str
wheel_download_dir=None, # type: str
): ):
# type: (...) -> RequirementPreparer # type: (...) -> RequirementPreparer
""" """
Create a RequirementPreparer instance for the given parameters. Create a RequirementPreparer instance for the given parameters.
""" """
downloader = Downloader(session, progress_bar=options.progress_bar)
temp_build_dir_path = temp_build_dir.path temp_build_dir_path = temp_build_dir.path
assert temp_build_dir_path is not None assert temp_build_dir_path is not None
if '2020-resolver' in options.features_enabled:
lazy_wheel = 'fast-deps' in options.features_enabled
if lazy_wheel:
logger.warning(
'pip is using lazily downloaded wheels using HTTP '
'range requests to obtain dependency information. '
'This experimental feature is enabled through '
'--use-feature=fast-deps and it is not ready for '
'production.'
)
else:
lazy_wheel = False
return RequirementPreparer( return RequirementPreparer(
build_dir=temp_build_dir_path, build_dir=temp_build_dir_path,
src_dir=options.src_dir, src_dir=options.src_dir,
download_dir=download_dir, download_dir=download_dir,
wheel_download_dir=wheel_download_dir,
build_isolation=options.build_isolation, build_isolation=options.build_isolation,
req_tracker=req_tracker, req_tracker=req_tracker,
downloader=downloader, session=session,
progress_bar=options.progress_bar,
finder=finder, finder=finder,
require_hashes=options.require_hashes, require_hashes=options.require_hashes,
use_user_site=use_user_site, use_user_site=use_user_site,
lazy_wheel=lazy_wheel,
) )
@staticmethod @staticmethod
@ -259,6 +266,7 @@ class RequirementCommand(IndexGroupCommand):
# "Resolver" class being redefined. # "Resolver" class being redefined.
if '2020-resolver' in options.features_enabled: if '2020-resolver' in options.features_enabled:
import pip._internal.resolution.resolvelib.resolver import pip._internal.resolution.resolvelib.resolver
return pip._internal.resolution.resolvelib.resolver.Resolver( return pip._internal.resolution.resolvelib.resolver.Resolver(
preparer=preparer, preparer=preparer,
finder=finder, finder=finder,
@ -271,7 +279,6 @@ class RequirementCommand(IndexGroupCommand):
force_reinstall=force_reinstall, force_reinstall=force_reinstall,
upgrade_strategy=upgrade_strategy, upgrade_strategy=upgrade_strategy,
py_version_info=py_version_info, py_version_info=py_version_info,
lazy_wheel='fast-deps' in options.features_enabled,
) )
import pip._internal.resolution.legacy.resolver import pip._internal.resolution.legacy.resolver
return pip._internal.resolution.legacy.resolver.Resolver( return pip._internal.resolution.legacy.resolver.Resolver(

2
src/pip/_internal/cli/spinners.py
View File

@ -13,7 +13,7 @@ from pip._internal.utils.logging import get_indentation
from pip._internal.utils.typing import MYPY_CHECK_RUNNING from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from typing import Iterator, IO from typing import IO, Iterator
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)

1
src/pip/_internal/commands/__init__.py
View File

@ -18,6 +18,7 @@ from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from typing import Any from typing import Any
from pip._internal.cli.base_command import Command from pip._internal.cli.base_command import Command

74
src/pip/_internal/commands/cache.py
View File

@ -37,11 +37,25 @@ class CacheCommand(Command):
usage = """ usage = """
%prog dir %prog dir
%prog info %prog info
%prog list [<pattern>] %prog list [<pattern>] [--format=[human, abspath]]
%prog remove <pattern> %prog remove <pattern>
%prog purge %prog purge
""" """
def add_options(self):
# type: () -> None
self.cmd_opts.add_option(
'--format',
action='store',
dest='list_format',
default="human",
choices=('human', 'abspath'),
help="Select the output format among: human (default) or abspath"
)
self.parser.insert_option_group(0, self.cmd_opts)
def run(self, options, args): def run(self, options, args):
# type: (Values, List[Any]) -> int # type: (Values, List[Any]) -> int
handlers = { handlers = {
@ -88,19 +102,30 @@ class CacheCommand(Command):
if args: if args:
raise CommandError('Too many arguments') raise CommandError('Too many arguments')
num_http_files = len(self._find_http_files(options))
num_packages = len(self._find_wheels(options, '*')) num_packages = len(self._find_wheels(options, '*'))
cache_location = self._wheels_cache_dir(options) http_cache_location = self._cache_dir(options, 'http')
cache_size = filesystem.format_directory_size(cache_location) wheels_cache_location = self._cache_dir(options, 'wheels')
http_cache_size = filesystem.format_directory_size(http_cache_location)
wheels_cache_size = filesystem.format_directory_size(
wheels_cache_location
)
message = textwrap.dedent(""" message = textwrap.dedent("""
Location: {location} Package index page cache location: {http_cache_location}
Size: {size} Package index page cache size: {http_cache_size}
Number of HTTP files: {num_http_files}
Wheels location: {wheels_cache_location}
Wheels size: {wheels_cache_size}
Number of wheels: {package_count} Number of wheels: {package_count}
""").format( """).format(
location=cache_location, http_cache_location=http_cache_location,
http_cache_size=http_cache_size,
num_http_files=num_http_files,
wheels_cache_location=wheels_cache_location,
package_count=num_packages, package_count=num_packages,
size=cache_size, wheels_cache_size=wheels_cache_size,
).strip() ).strip()
logger.info(message) logger.info(message)
@ -116,7 +141,13 @@ class CacheCommand(Command):
pattern = '*' pattern = '*'
files = self._find_wheels(options, pattern) files = self._find_wheels(options, pattern)
if options.list_format == 'human':
self.format_for_human(files)
else:
self.format_for_abspath(files)
def format_for_human(self, files):
# type: (List[str]) -> None
if not files: if not files:
logger.info('Nothing cached.') logger.info('Nothing cached.')
return return
@ -129,6 +160,17 @@ class CacheCommand(Command):
logger.info('Cache contents:\n') logger.info('Cache contents:\n')
logger.info('\n'.join(sorted(results))) logger.info('\n'.join(sorted(results)))
def format_for_abspath(self, files):
# type: (List[str]) -> None
if not files:
return
results = []
for filename in files:
results.append(filename)
logger.info('\n'.join(sorted(results)))
def remove_cache_items(self, options, args): def remove_cache_items(self, options, args):
# type: (Values, List[Any]) -> None # type: (Values, List[Any]) -> None
if len(args) > 1: if len(args) > 1:
@ -138,6 +180,11 @@ class CacheCommand(Command):
raise CommandError('Please provide a pattern') raise CommandError('Please provide a pattern')
files = self._find_wheels(options, args[0]) files = self._find_wheels(options, args[0])
# Only fetch http files if no specific pattern given
if args[0] == '*':
files += self._find_http_files(options)
if not files: if not files:
raise CommandError('No matching packages') raise CommandError('No matching packages')
@ -153,13 +200,18 @@ class CacheCommand(Command):
return self.remove_cache_items(options, ['*']) return self.remove_cache_items(options, ['*'])
def _wheels_cache_dir(self, options): def _cache_dir(self, options, subdir):
# type: (Values) -> str # type: (Values, str) -> str
return os.path.join(options.cache_dir, 'wheels') return os.path.join(options.cache_dir, subdir)
def _find_http_files(self, options):
# type: (Values) -> List[str]
http_dir = self._cache_dir(options, 'http')
return filesystem.find_files(http_dir, '*')
def _find_wheels(self, options, pattern): def _find_wheels(self, options, pattern):
# type: (Values, str) -> List[str] # type: (Values, str) -> List[str]
wheel_dir = self._wheels_cache_dir(options) wheel_dir = self._cache_dir(options, 'wheels')
# The wheel filename format, as specified in PEP 427, is: # The wheel filename format, as specified in PEP 427, is:
# {distribution}-{version}(-{build})?-{python}-{abi}-{platform}.whl # {distribution}-{version}(-{build})?-{python}-{abi}-{platform}.whl

2
src/pip/_internal/commands/check.py
View File

@ -12,8 +12,8 @@ from pip._internal.utils.typing import MYPY_CHECK_RUNNING
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from typing import List, Any
from optparse import Values from optparse import Values
from typing import Any, List
class CheckCommand(Command): class CheckCommand(Command):

2
src/pip/_internal/commands/completion.py
View File

@ -9,8 +9,8 @@ from pip._internal.utils.misc import get_prog
from pip._internal.utils.typing import MYPY_CHECK_RUNNING from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from typing import List
from optparse import Values from optparse import Values
from typing import List
BASE_COMPLETION = """ BASE_COMPLETION = """
# pip {shell} completion start{script}# pip {shell} completion end # pip {shell} completion start{script}# pip {shell} completion end

8
src/pip/_internal/commands/configuration.py
View File

@ -4,19 +4,15 @@ import subprocess
from pip._internal.cli.base_command import Command from pip._internal.cli.base_command import Command
from pip._internal.cli.status_codes import ERROR, SUCCESS from pip._internal.cli.status_codes import ERROR, SUCCESS
from pip._internal.configuration import ( from pip._internal.configuration import Configuration, get_configuration_files, kinds
Configuration,
get_configuration_files,
kinds,
)
from pip._internal.exceptions import PipError from pip._internal.exceptions import PipError
from pip._internal.utils.logging import indent_log from pip._internal.utils.logging import indent_log
from pip._internal.utils.misc import get_prog, write_output from pip._internal.utils.misc import get_prog, write_output
from pip._internal.utils.typing import MYPY_CHECK_RUNNING from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from typing import List, Any, Optional
from optparse import Values from optparse import Values
from typing import Any, List, Optional
from pip._internal.configuration import Kind from pip._internal.configuration import Kind

5
src/pip/_internal/commands/debug.py
View File

@ -19,9 +19,10 @@ from pip._internal.utils.misc import get_pip_version
from pip._internal.utils.typing import MYPY_CHECK_RUNNING from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from types import ModuleType
from typing import List, Optional, Dict
from optparse import Values from optparse import Values
from types import ModuleType
from typing import Dict, List, Optional
from pip._internal.configuration import Configuration from pip._internal.configuration import Configuration
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)

12
src/pip/_internal/commands/download.py
View File

@ -87,7 +87,6 @@ class DownloadCommand(RequirementCommand):
cmdoptions.check_dist_restriction(options) cmdoptions.check_dist_restriction(options)
options.download_dir = normalize_path(options.download_dir) options.download_dir = normalize_path(options.download_dir)
ensure_dir(options.download_dir) ensure_dir(options.download_dir)
session = self.get_default_session(options) session = self.get_default_session(options)
@ -134,10 +133,13 @@ class DownloadCommand(RequirementCommand):
reqs, check_supported_wheels=True reqs, check_supported_wheels=True
) )
downloaded = ' '.join([req.name # type: ignore downloaded = [] # type: List[str]
for req in requirement_set.requirements.values() for req in requirement_set.requirements.values():
if req.successfully_downloaded]) if not req.editable and req.satisfied_by is None:
assert req.name is not None
preparer.save_linked_requirement(req)
downloaded.append(req.name)
if downloaded: if downloaded:
write_output('Successfully downloaded %s', downloaded) write_output('Successfully downloaded %s', ' '.join(downloaded))
return SUCCESS return SUCCESS

6
src/pip/_internal/commands/help.py
View File

@ -6,8 +6,8 @@ from pip._internal.exceptions import CommandError
from pip._internal.utils.typing import MYPY_CHECK_RUNNING from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from typing import List
from optparse import Values from optparse import Values
from typing import List
class HelpCommand(Command): class HelpCommand(Command):
@ -20,7 +20,9 @@ class HelpCommand(Command):
def run(self, options, args): def run(self, options, args):
# type: (Values, List[str]) -> int # type: (Values, List[str]) -> int
from pip._internal.commands import ( from pip._internal.commands import (
commands_dict, create_command, get_similar_commands, commands_dict,
create_command,
get_similar_commands,
) )
try: try:

14
src/pip/_internal/commands/install.py
View File

@ -21,7 +21,6 @@ from pip._internal.locations import distutils_scheme
from pip._internal.operations.check import check_install_conflicts from pip._internal.operations.check import check_install_conflicts
from pip._internal.req import install_given_reqs from pip._internal.req import install_given_reqs
from pip._internal.req.req_tracker import get_requirement_tracker from pip._internal.req.req_tracker import get_requirement_tracker
from pip._internal.utils.datetime import today_is_later_than
from pip._internal.utils.distutils_args import parse_distutils_args from pip._internal.utils.distutils_args import parse_distutils_args
from pip._internal.utils.filesystem import test_writable_dir from pip._internal.utils.filesystem import test_writable_dir
from pip._internal.utils.misc import ( from pip._internal.utils.misc import (
@ -543,19 +542,6 @@ class InstallCommand(RequirementCommand):
"your packages with the new resolver before it becomes the " "your packages with the new resolver before it becomes the "
"default.\n" "default.\n"
) )
elif not today_is_later_than(year=2020, month=7, day=31):
# NOTE: trailing newlines here are intentional
parts.append(
"Pip will install or upgrade your package(s) and its "
"dependencies without taking into account other packages you "
"already have installed. This may cause an uncaught "
"dependency conflict.\n"
)
form_link = "https://forms.gle/cWKMoDs8sUVE29hz9"
parts.append(
"If you would like pip to take your other packages into "
"account, please tell us here: {}\n".format(form_link)
)
# NOTE: There is some duplication here, with commands/check.py # NOTE: There is some duplication here, with commands/check.py
for project_name in missing: for project_name in missing:

6
src/pip/_internal/commands/list.py
View File

@ -24,10 +24,11 @@ from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from optparse import Values from optparse import Values
from typing import List, Set, Tuple, Iterator from typing import Iterator, List, Set, Tuple
from pip._vendor.pkg_resources import Distribution
from pip._internal.network.session import PipSession from pip._internal.network.session import PipSession
from pip._vendor.pkg_resources import Distribution
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
@ -201,7 +202,6 @@ class ListCommand(IndexGroupCommand):
def latest_info(dist): def latest_info(dist):
# type: (Distribution) -> Distribution # type: (Distribution) -> Distribution
typ = 'unknown'
all_candidates = finder.find_all_candidates(dist.key) all_candidates = finder.find_all_candidates(dist.key)
if not options.pre: if not options.pre:
# Remove prereleases # Remove prereleases

4
src/pip/_internal/commands/search.py
View File

@ -7,6 +7,7 @@ from collections import OrderedDict
from pip._vendor import pkg_resources from pip._vendor import pkg_resources
from pip._vendor.packaging.version import parse as parse_version from pip._vendor.packaging.version import parse as parse_version
# NOTE: XMLRPC Client is not annotated in typeshed as on 2017-07-17, which is # NOTE: XMLRPC Client is not annotated in typeshed as on 2017-07-17, which is
# why we ignore the type on this import # why we ignore the type on this import
from pip._vendor.six.moves import xmlrpc_client # type: ignore from pip._vendor.six.moves import xmlrpc_client # type: ignore
@ -24,7 +25,8 @@ from pip._internal.utils.typing import MYPY_CHECK_RUNNING
if MYPY_CHECK_RUNNING: if MYPY_CHECK_RUNNING:
from optparse import Values from optparse import Values
from typing import List, Dict, Optional from typing import Dict, List, Optional
from typing_extensions import TypedDict from typing_extensions import TypedDict
TransformedHit = TypedDict( TransformedHit = TypedDict(
'TransformedHit', 'TransformedHit',

Some files were not shown because too many files have changed in this diff Show More