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

Make heading style consistent

This commit is contained in:
Pradyun Gedam 2020-02-11 18:30:03 +05:30
parent 9944ad114f
commit 49b978dd8a
No known key found for this signature in database
GPG Key ID: DA17C4B29CB32E4B
18 changed files with 115 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -9,7 +9,7 @@ reference to the development setup. If you face any issues during this
process, please `open an issue`_ about it on the issue tracker.
Get the source code
-------------------
===================
To work on pip, you first need to get the source code of pip. The source code is
available on `GitHub`_.
@ -21,7 +21,7 @@ available on `GitHub`_.
Development Environment
-----------------------
=======================
pip is a command line application written in Python. For developing pip,
you should `install Python`_ on your computer.
@ -30,7 +30,7 @@ For developing pip, you need to install :pypi:`tox`. Often, you can run
``python -m pip install tox`` to install and use it.
Running pip From Source Tree
----------------------------
============================
To run the pip executable from your source tree during development, run pip
from the ``src`` directory:
@ -40,7 +40,7 @@ from the ``src`` directory:
$ python src/pip --version
Running Tests
-------------
=============
pip's tests are written using the :pypi:`pytest` test framework, :pypi:`mock`
and :pypi:`pretend`. :pypi:`tox` is used to automate the setup and execution of
@ -85,7 +85,7 @@ tools, you can tell pip to skip those tests:
$ tox -e py36 -- -k "not (svn or git)"
Running Linters
---------------
===============
pip uses :pypi:`pre-commit` for managing linting of the codebase.
``pre-commit`` performs various checks on all files in pip and uses tools that
@ -105,7 +105,7 @@ To use linters locally, run:
readability problems.
Building Documentation
----------------------
======================
pip's documentation is built using :pypi:`Sphinx`. The documentation is written
in reStructuredText.

6
docs/html/development/issue-triage.rst
View File

@ -13,7 +13,7 @@ how to help triage reported issues.
Issue Tracker
*************
=============
The `pip issue tracker <https://github.com/pypa/pip/issues>`__ is hosted on
GitHub alongside the project.
@ -101,7 +101,7 @@ links on the closed issue.
Triage Issues
*************
=============
Users can make issues for a number of reasons:
@ -297,7 +297,7 @@ An issue may be considered resolved and closed when:
Common issues
*************
=============
#. network-related issues - any issue involving retries, address lookup, or
anything like that are typically network issues.

2
docs/html/index.rst
View File

@ -29,7 +29,7 @@ If you want to get involved head over to GitHub to get the source code and feel
* `Dev IRC`_
Code of Conduct
---------------
===============
Everyone interacting in the pip project's codebases, issue trackers, chat
rooms, and mailing lists is expected to follow the `PyPA Code of Conduct`_.

12
docs/html/installing.rst
View File

@ -5,7 +5,7 @@ Installation
============
Do I need to install pip?
-------------------------
=========================
pip is already installed if you are using Python 2 >=2.7.9 or Python 3 >=3.4
downloaded from `python.org <https://www.python.org>`_ or if you are working
@ -17,7 +17,7 @@ Just make sure to :ref:`upgrade pip <Upgrading pip>`.
.. _`get-pip`:
Installing with get-pip.py
--------------------------
==========================
To install pip, securely [1]_ download ``get-pip.py`` by following
this link: `get-pip.py
@ -52,7 +52,7 @@ speed), although neither are required to install pre-built :term:`wheels
get-pip.py options
~~~~~~~~~~~~~~~~~~~
------------------
.. option:: --no-setuptools
@ -86,7 +86,7 @@ Install behind a proxy::
Using Linux Package Managers
----------------------------
============================
See :ref:`pypug:Installing pip/setuptools/wheel with Linux Package Managers` in
the `Python Packaging User Guide
@ -95,7 +95,7 @@ the `Python Packaging User Guide
.. _`Upgrading pip`:
Upgrading pip
-------------
=============
On Linux or macOS::
@ -110,7 +110,7 @@ On Windows [4]_::
.. _compatibility-requirements:
Python and OS Compatibility
---------------------------
===========================
pip works with CPython versions 2.7, 3.5, 3.6, 3.7, 3.8 and also PyPy.

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

@ -7,19 +7,19 @@ pip check
.. contents::
Usage
*****
=====
.. pip-command-usage:: check
Description
***********
===========
.. pip-command-description:: check
Examples
********
========
#. If all dependencies are compatible:

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

@ -8,16 +8,16 @@ pip config
.. contents::
Usage
*****
=====
.. pip-command-usage:: config
Description
***********
===========
.. pip-command-description:: config
Options
*******
=======
.. pip-command-options:: config

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

@ -7,7 +7,7 @@ pip debug
.. contents::
Usage
*****
=====
.. pip-command-usage:: debug
@ -18,12 +18,12 @@ Usage
Description
***********
===========
.. pip-command-description:: debug
Options
*******
=======
.. pip-command-options:: debug

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

@ -8,19 +8,19 @@ pip download
.. contents::
Usage
*****
=====
.. pip-command-usage:: download
Description
***********
===========
.. pip-command-description:: download
Overview
++++++++
--------
``pip download`` does the same resolution and downloading as ``pip install``,
but instead of installing the dependencies, it collects the downloaded
@ -44,7 +44,7 @@ constrained download requirement.
Options
*******
=======
.. pip-command-options:: download
@ -52,7 +52,7 @@ Options
Examples
********
========
#. Download a package and all of its dependencies

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

@ -8,25 +8,25 @@ pip freeze
.. contents::
Usage
*****
=====
.. pip-command-usage:: freeze
Description
***********
===========
.. pip-command-description:: freeze
Options
*******
=======
.. pip-command-options:: freeze
Examples
********
========
#. Generate output suitable for a requirements file.

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

@ -7,19 +7,20 @@ pip hash
.. contents::
Usage
*****
=====
.. pip-command-usage:: hash
Description
***********
===========
.. pip-command-description:: hash
Overview
++++++++
--------
``pip hash`` is a convenient way to get a hash digest for use with
:ref:`hash-checking mode`, especially for packages with multiple archives. The
error message from ``pip install --require-hashes ...`` will give you one
@ -30,13 +31,13 @@ different set of options, like :ref:`--no-binary <install_--no-binary>`.
Options
*******
=======
.. pip-command-options:: hash
Example
********
=======
Compute the hash of a downloaded archive::

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

@ -7,18 +7,18 @@ pip install
.. contents::
Usage
*****
=====
.. pip-command-usage:: install
Description
***********
===========
.. pip-command-description:: install
Overview
++++++++
--------
Pip install has several stages:
@ -29,7 +29,7 @@ Pip install has several stages:
4. Install the packages (and uninstall anything being upgraded/replaced).
Argument Handling
+++++++++++++++++
-----------------
When looking at the items to be installed, pip checks what type of item
each is, in the following order:
@ -45,7 +45,7 @@ Each item identified is added to the set of requirements to be satisfied by
the install.
Working Out the Name and Version
++++++++++++++++++++++++++++++++
--------------------------------
For each candidate item, pip needs to know the project name and version. For
wheels (identified by the ``.whl`` file extension) this can be obtained from
@ -60,7 +60,7 @@ Any URL may use the ``#egg=name`` syntax (see :ref:`VCS Support`) to
explicitly state the project name.
Satisfying Requirements
+++++++++++++++++++++++
-----------------------
Once pip has the set of requirements to satisfy, it chooses which version of
each requirement to install using the simple rule that the latest version that
@ -70,7 +70,7 @@ the chosen version is available, it is assumed that any source is acceptable
(as otherwise the versions would differ).
Installation Order
++++++++++++++++++
------------------
.. note::
This section is only about installation order of runtime dependencies, and
@ -125,7 +125,7 @@ profile:
.. _`Requirements File Format`:
Requirements File Format
++++++++++++++++++++++++
------------------------
Each line of the requirements file indicates something to be installed,
and like arguments to :ref:`pip install`, the following forms are supported::
@ -188,7 +188,7 @@ You can also refer to :ref:`constraints files <Constraints Files>`, like this::
.. _`Using Environment Variables`:
Using Environment Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Since version 10, pip supports the use of environment variables inside the
requirements file. You can now store sensitive data (tokens, keys, etc.) in
@ -210,7 +210,7 @@ runtime.
.. _`Example Requirements File`:
Example Requirements File
~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^
Use ``pip install -r example-requirements.txt`` to install::
@ -246,7 +246,7 @@ Use ``pip install -r example-requirements.txt`` to install::
.. _`Requirement Specifiers`:
Requirement Specifiers
++++++++++++++++++++++
----------------------
pip supports installing from a package index using a :term:`requirement
specifier <pypug:Requirement Specifier>`. Generally speaking, a requirement
@ -291,7 +291,7 @@ Environment markers are supported in the command line and in requirements files.
.. _`Per-requirement Overrides`:
Per-requirement Overrides
+++++++++++++++++++++++++
-------------------------
Since version 7.0 pip supports controlling the command line options given to
``setup.py`` via requirements files. This disables the use of wheels (cached or
@ -329,7 +329,7 @@ installation error.
.. _`Pre Release Versions`:
Pre-release Versions
++++++++++++++++++++
--------------------
Starting with v1.4, pip will only install stable versions as specified by
`pre-releases`_ by default. If a version cannot be parsed as a compliant :pep:`440`
@ -349,7 +349,7 @@ that enables installation of pre-releases and development releases.
.. _`VCS Support`:
VCS Support
+++++++++++
-----------
pip supports installing from Git, Mercurial, Subversion and Bazaar, and detects
the type of VCS using URL prefixes: ``git+``, ``hg+``, ``svn+``, and ``bzr+``.
@ -397,7 +397,7 @@ You'll need to use ``pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirecto
Git
~~~
^^^
pip currently supports cloning over ``git``, ``git+http``, ``git+https``,
``git+ssh``, ``git+git`` and ``git+file``:
@ -423,7 +423,7 @@ hash because a full hash allows pip to operate more efficiently (e.g. by
making fewer network calls).
Mercurial
~~~~~~~~~
^^^^^^^^^
The supported schemes are: ``hg+file``, ``hg+http``, ``hg+https``,
``hg+static-http``, and ``hg+ssh``.
@ -444,7 +444,7 @@ branch name like so::
[-e] hg+http://hg.example.com/MyProject@special_feature#egg=MyProject
Subversion
~~~~~~~~~~
^^^^^^^^^^
pip supports the URL schemes ``svn``, ``svn+svn``, ``svn+http``, ``svn+https``, ``svn+ssh``.
@ -464,7 +464,7 @@ out the revision from 2008-01-01. You can only check out specific
revisions using ``-e svn+...``.
Bazaar
~~~~~~
^^^^^^
pip supports Bazaar using the ``bzr+http``, ``bzr+https``, ``bzr+ssh``,
``bzr+sftp``, ``bzr+ftp`` and ``bzr+lp`` schemes.
@ -483,7 +483,7 @@ Tags or revisions can be installed like so::
[-e] bzr+http://bzr.example.com/MyProject/trunk@v1.0#egg=MyProject
Using Environment Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Since version 10, pip also makes it possible to use environment variables which
makes it possible to reference private repositories without having to store
@ -499,7 +499,7 @@ allowing Basic Auth for authentication can be refenced like this::
``%VARIABLE%`` won't work.
Finding Packages
++++++++++++++++
----------------
pip searches for packages on `PyPI`_ using the
`HTTP simple interface <https://pypi.org/simple/>`_,
@ -522,7 +522,7 @@ See the :ref:`pip install Examples<pip install Examples>`.
.. _`SSL Certificate Verification`:
SSL Certificate Verification
++++++++++++++++++++++++++++
----------------------------
Starting with v1.3, pip provides SSL certificate verification over https, to
prevent man-in-the-middle attacks against PyPI downloads.
@ -531,7 +531,7 @@ prevent man-in-the-middle attacks against PyPI downloads.
.. _`Caching`:
Caching
+++++++
-------
Starting with v6.0, pip provides an on-by-default cache which functions
similarly to that of a web browser. While the cache is on by default and is
@ -570,7 +570,7 @@ Windows
.. _`Wheel cache`:
Wheel Cache
~~~~~~~~~~~
^^^^^^^^^^^
Pip will read from the subdirectory ``wheels`` within the pip cache directory
and use any packages found there. This is disabled via the same
@ -595,7 +595,7 @@ automatically and insert it into the wheel cache.
.. _`hash-checking mode`:
Hash-Checking Mode
++++++++++++++++++
------------------
Since version 8.0, pip can check downloaded package archives against local
hashes to protect against remote tampering. To verify a package against one or
@ -700,7 +700,7 @@ Hash-checking mode also works with :ref:`pip download` and :ref:`pip wheel`. A
Hashes from PyPI
~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^
PyPI provides an MD5 hash in the fragment portion of each package download URL,
like ``#md5=123...``, which pip checks as a protection against download
@ -712,7 +712,7 @@ local hash.
Local project installs
++++++++++++++++++++++
----------------------
pip supports installing local project in both regular mode and editable mode.
You can install local projects by specifying the project path to pip::
@ -725,7 +725,7 @@ The exception is that pip will exclude .tox and .nox directories present in the
.. _`editable-installs`:
"Editable" Installs
~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^
"Editable" installs are fundamentally `"setuptools develop mode"
<https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode>`_
@ -746,7 +746,7 @@ which creates the "egg-info" directly relative the current working directory.
.. _`controlling-setup-requires`:
Controlling setup_requires
++++++++++++++++++++++++++
--------------------------
Setuptools offers the ``setup_requires`` `setup() keyword
<https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords>`_
@ -779,7 +779,7 @@ To have the dependency located from a local directory and not crawl PyPI, add th
Build System Interface
++++++++++++++++++++++
----------------------
In order for pip to install a package from source, ``setup.py`` must implement
the following commands::
@ -825,7 +825,7 @@ Installing a package from a wheel does not invoke the build system at all.
.. _`pip install Options`:
Options
*******
=======
.. pip-command-options:: install
@ -835,7 +835,7 @@ Options
.. _`pip install Examples`:
Examples
********
========
#. Install ``SomePackage`` and its dependencies from `PyPI`_ using :ref:`Requirement Specifiers`

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

@ -7,17 +7,17 @@ pip list
.. contents::
Usage
*****
=====
.. pip-command-usage:: list
Description
***********
===========
.. pip-command-description:: list
Options
*******
=======
.. pip-command-options:: list
@ -25,7 +25,7 @@ Options
Examples
********
========
#. List installed packages.

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

@ -7,24 +7,24 @@ pip search
.. contents::
Usage
*****
=====
.. pip-command-usage:: search
Description
***********
===========
.. pip-command-description:: search
Options
*******
=======
.. pip-command-options:: search
Examples
********
========
#. Search for "peppercorn"

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

@ -8,25 +8,25 @@ pip show
Usage
*****
=====
.. pip-command-usage:: show
Description
***********
===========
.. pip-command-description:: show
Options
*******
=======
.. pip-command-options:: show
Examples
********
========
#. Show information about a package:

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

@ -7,23 +7,23 @@ pip uninstall
.. contents::
Usage
*****
=====
.. pip-command-usage:: uninstall
Description
***********
===========
.. pip-command-description:: uninstall
Options
*******
=======
.. pip-command-options:: uninstall
Examples
********
========
#. Uninstall a package.

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

@ -8,19 +8,19 @@ pip wheel
.. contents::
Usage
*****
=====
.. pip-command-usage:: wheel
Description
***********
===========
.. pip-command-description:: wheel
Build System Interface
++++++++++++++++++++++
----------------------
In order for pip to build a wheel, ``setup.py`` must implement the
``bdist_wheel`` command with the following syntax::
@ -33,7 +33,7 @@ interpreter, and save that wheel in the directory TARGET.
No other build system commands are invoked by the ``pip wheel`` command.
Customising the build
~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^
It is possible using ``--global-option`` to include additional build commands
with their arguments in the ``setup.py`` command. This is currently the only
@ -56,7 +56,7 @@ the current implementation than a supported interface.
Options
*******
=======
.. pip-command-options:: wheel
@ -64,7 +64,7 @@ Options
Examples
********
========
#. Build wheels for a requirement (and all its dependencies), and then install

36
docs/html/user_guide.rst
View File

@ -5,7 +5,7 @@ User Guide
.. contents::
Running pip
***********
===========
pip is a command line program. When you install pip, a ``pip`` command is added
to your system, which can be run from the command prompt as follows::
@ -28,7 +28,7 @@ more details, see :ref:`Using pip from your program`.
Installing Packages
*******************
===================
pip supports installing from `PyPI`_, version control, local projects, and
directly from distribution files.
@ -50,7 +50,7 @@ For more information and examples, see the :ref:`pip install` reference.
Basic Authentication Credentials
********************************
================================
pip supports basic authentication credentials. Basically, in the URL there is
a username and password separated by ``:``.
@ -79,7 +79,7 @@ as the "username" and do not provide a password, for example -
Using a Proxy Server
********************
====================
When installing packages from `PyPI`_, pip requires internet access, which
in many corporate environments requires an outbound HTTP proxy server.
@ -98,7 +98,7 @@ pip can be configured to connect through a proxy server in various ways:
.. _`Requirements Files`:
Requirements Files
******************
==================
"Requirements files" are files containing a list of items to be
installed using :ref:`pip install` like so:
@ -180,7 +180,7 @@ See also:
.. _`Constraints Files`:
Constraints Files
*****************
=================
Constraints files are requirements files that only control which version of a
requirement is installed, not whether it is installed or not. Their syntax and
@ -214,7 +214,7 @@ Constraints file support was added in pip 7.1.
.. _`Installing from Wheels`:
Installing from Wheels
**********************
======================
"Wheel" is a built, archive format that can greatly speed installation compared
to building and installing from source archives. For more information, see the
@ -258,7 +258,7 @@ wheels (and not from PyPI):
Uninstalling Packages
*********************
=====================
pip is able to uninstall most packages like so:
@ -273,7 +273,7 @@ For more information and examples, see the :ref:`pip uninstall` reference.
Listing Packages
****************
================
To list installed packages:
@ -311,7 +311,7 @@ reference pages.
Searching for Packages
**********************
======================
pip can search `PyPI`_ for packages using the ``pip search``
command::
@ -326,12 +326,12 @@ For more information and examples, see the :ref:`pip search` reference.
.. _`Configuration`:
Configuration
*************
=============
.. _config-file:
Config file
------------
-----------
pip allows you to set all command line option defaults in a standard ini
style config file.
@ -497,7 +497,7 @@ Examples:
Command Completion
******************
==================
pip comes with support for command line completion in bash, zsh and fish.
@ -524,7 +524,7 @@ startup file::
.. _`Installing from local packages`:
Installing from local packages
******************************
==============================
In some cases, you may want to install from local packages only, with no traffic
to PyPI.
@ -550,7 +550,7 @@ $ pip install --no-index --find-links=DIR -r requirements.txt
"Only if needed" Recursive Upgrade
**********************************
==================================
``pip install --upgrade`` now has a ``--upgrade-strategy`` option which
controls how pip handles upgrading of dependencies. There are 2 upgrade
@ -575,7 +575,7 @@ alternative to the behaviour of eager upgrading.
User Installs
*************
=============
With Python 2.6 came the `"user scheme" for installation
<https://docs.python.org/3/install/index.html#alternate-installation-the-user-scheme>`_,
@ -670,7 +670,7 @@ is the latest version::
.. _`Repeatability`:
Ensuring Repeatability
**********************
======================
pip can achieve various levels of repeatability:
@ -755,7 +755,7 @@ archives are built with identical packages.
.. _`Using pip from your program`:
Using pip from your program
***************************
===========================
As noted previously, pip is a command line program. While it is implemented in
Python, and so is available from your Python code via ``import pip``, you must

8
src/pip/_vendor/README.rst
View File

@ -25,7 +25,7 @@ Vendoring Policy
``pip/_vendor/__init__.py``.
Rationale
---------
=========
Historically pip has not had any dependencies except for ``setuptools`` itself,
choosing instead to implement any functionality it needed to prevent needing
@ -95,7 +95,7 @@ such as OS packages.
Modifications
-------------
=============
* ``setuptools`` is completely stripped to only keep ``pkg_resources``
* ``pkg_resources`` has been modified to import its dependencies from ``pip._vendor``
@ -108,7 +108,7 @@ Modifications
Automatic Vendoring
-------------------
===================
Vendoring is automated via the ``vendoring`` tool from the content of
``pip/_vendor/vendor.txt`` and the different patches in
@ -117,7 +117,7 @@ Launch it via ``vendoring sync . -v`` (requires ``vendoring>=0.2.2``).
Debundling
----------
==========
As mentioned in the rationale, we, the pip team, would prefer it if pip was not
debundled (other than optionally ``pip/_vendor/requests/cacert.pem``) and that