diff --git a/docs/html/cli/pip_install.rst b/docs/html/cli/pip_install.rst index 1362b490ba3..6b4d3b1a2ba 100644 --- a/docs/html/cli/pip_install.rst +++ b/docs/html/cli/pip_install.rst @@ -149,120 +149,10 @@ profile: ``setup_requires``. -.. _`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:: - - [[--option]...] - [; markers] [[--option]...] - - [-e] - [-e] - -For details on requirement specifiers, see :ref:`Requirement Specifiers`. - -See the :ref:`pip install Examples` for examples of all these forms. - -A line that begins with ``#`` is treated as a comment and ignored. Whitespace -followed by a ``#`` causes the ``#`` and the remainder of the line to be -treated as a comment. - -A line ending in an unescaped ``\`` is treated as a line continuation -and the newline following it is effectively ignored. - -Comments are stripped *after* line continuations are processed. - -To interpret the requirements file in UTF-8 format add a comment -``# -*- coding: utf-8 -*-`` to the first or second line of the file. - -The following options are supported: - -.. pip-requirements-file-options-ref-list:: - -Please note that the above options are global options, and should be specified on their individual lines. -The options which can be applied to individual requirements are -:ref:`--install-option `, :ref:`--global-option ` and ``--hash``. - -For example, to specify :ref:`--pre `, :ref:`--no-index ` and two -:ref:`--find-links ` locations: - -:: - ---pre ---no-index ---find-links /my/local/archives ---find-links http://some.archives.com/archives - - -If you wish, you can refer to other requirements files, like this:: - - -r more_requirements.txt - -You can also refer to :ref:`constraints files `, like this:: - - -c some_constraints.txt - -.. _`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 -environment variables and only specify the variable name for your requirements, -letting pip lookup the value at runtime. This approach aligns with the commonly -used `12-factor configuration pattern `_. - -You have to use the POSIX format for variable names including brackets around -the uppercase name as shown in this example: ``${API_TOKEN}``. pip will attempt -to find the corresponding environment variable defined on the host system at -runtime. - -.. note:: - - There is no support for other variable expansion syntaxes such as - ``$VARIABLE`` and ``%VARIABLE%``. - - -.. _`Example Requirements File`: - -Example Requirements File -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Use ``pip install -r example-requirements.txt`` to install:: - - # - ####### example-requirements.txt ####### - # - ###### Requirements without Version Specifiers ###### - nose - nose-cov - beautifulsoup4 - # - ###### Requirements with Version Specifiers ###### - # See https://www.python.org/dev/peps/pep-0440/#version-specifiers - docopt == 0.6.1 # Version Matching. Must be version 0.6.1 - keyring >= 4.1.1 # Minimum version 4.1.1 - coverage != 3.5 # Version Exclusion. Anything except version 3.5 - Mopidy-Dirble ~= 1.1 # Compatible release. Same as >= 1.1, == 1.* - # - ###### Refer to other requirements files ###### - -r other-requirements.txt - # - # - ###### A particular file ###### - ./downloads/numpy-1.9.2-cp34-none-win32.whl - http://wxpython.org/Phoenix/snapshot-builds/wxPython_Phoenix-3.0.3.dev1820+49a8884-cp34-none-win_amd64.whl - # - ###### Additional Requirements without Version Specifiers ###### - # Same as 1st section, just here to show that you can put things in any order. - rejected - green - # +This section has been moved to :doc:`../reference/requirements-file-format`. .. _`Requirement Specifiers`: diff --git a/docs/html/index.md b/docs/html/index.md index 4b565b9a38c..34a01744996 100644 --- a/docs/html/index.md +++ b/docs/html/index.md @@ -14,6 +14,7 @@ getting-started installation user_guide topics/index +reference/index cli/index ``` diff --git a/docs/html/reference/index.md b/docs/html/reference/index.md new file mode 100644 index 00000000000..13e57b2a478 --- /dev/null +++ b/docs/html/reference/index.md @@ -0,0 +1,10 @@ +# Reference + +Reference provides information about various file formats, interfaces and +interoperability standards that pip utilises/implements. + +```{toctree} +:titlesonly: + +requirements-file-format +``` diff --git a/docs/html/reference/index.rst b/docs/html/reference/index.rst deleted file mode 100644 index 5e81105c9ad..00000000000 --- a/docs/html/reference/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -:orphan: - -.. meta:: - - :http-equiv=refresh: 3; url=../cli/ - -This page has moved -=================== - -You should be redirected automatically in 3 seconds. If that didn't -work, here's a link: :doc:`../cli/index` diff --git a/docs/html/reference/requirements-file-format.md b/docs/html/reference/requirements-file-format.md new file mode 100644 index 00000000000..3ee708e1abb --- /dev/null +++ b/docs/html/reference/requirements-file-format.md @@ -0,0 +1,145 @@ +# Requirements File Format + +Requirements files serve as a list of items to be installed by pip, when +using {ref}`pip install`. Files that use this format are often called +"pip requirements.txt files", since `requirements.txt` is usually what +these files are named (although, that is not a requirement). + +```{note} +The requirements file format is closely tied to a number of internal details of +pip (e.g., pip's command line options). The basic format is relatively stable +and portable but the full syntax, as described here, is only intended for +consumption by pip, and other tools should take that into account before using +it for their own purposes. +``` + +## Structure + +Each line of the requirements file indicates something to be installed, +or arguments to {ref}`pip install`. The following forms are supported: + +- `[[--option]...]` +- ` [; markers] [[--option]...]` +- `` +- `[-e] ` +- `[-e] ` + +For details on requirement specifiers, see {ref}`Requirement Specifiers`. For +examples of all these forms, see {ref}`pip install Examples`. + +### Encoding + +Requirements files are `utf-8` encoding by default and also support +{pep}`263` style comments to change the encoding (i.e. +`# -*- coding: -*-`). + +### Line continuations + +A line ending in an unescaped `\` is treated as a line continuation +and the newline following it is effectively ignored. + +### Comments + +A line that begins with `#` is treated as a comment and ignored. Whitespace +followed by a `#` causes the `#` and the remainder of the line to be +treated as a comment. + +Comments are stripped _after_ line continuations are processed. + +## Supported options + +Requirements files only supports certain pip install options, which are listed +below. + +### Global options + +The following options have an effect on the _entire_ `pip install` run, and +must be specified on their individual lines. + +```{eval-rst} +.. pip-requirements-file-options-ref-list:: +``` + +````{admonition} Example +To specify {ref}`--pre `, {ref}`--no-index ` +and two {ref}`--find-links ` locations: + +``` +--pre +--no-index +--find-links /my/local/archives +--find-links http://some.archives.com/archives +``` +```` + +### Per-requirement options + +The options which can be applied to individual requirements are: + +- {ref}`--install-option ` +- {ref}`--global-option ` +- `--hash` (for {ref}`Hash-Checking mode`) + +If you wish, you can refer to other requirements files, like this: + +``` +-r more_requirements.txt +``` + +You can also refer to {ref}`constraints files `, like this: + +``` +-c some_constraints.txt +``` + +## Using environment variables + +```{versionadded} 10.0 + +``` + +pip supports the use of environment variables inside the +requirements file. + +You have to use the POSIX format for variable names including brackets around +the uppercase name as shown in this example: `${API_TOKEN}`. pip will attempt +to find the corresponding environment variable defined on the host system at +runtime. + +```{note} +There is no support for other variable expansion syntaxes such as `$VARIABLE` +and `%VARIABLE%`. +``` + +You can now store sensitive data (tokens, keys, etc.) in environment variables +and only specify the variable name for your requirements, letting pip lookup +the value at runtime. This approach aligns with the commonly used +[12-factor configuration pattern](https://12factor.net/config). + +## Example + +``` +###### Requirements without Version Specifiers ###### +pytest +pytest-cov +beautifulsoup4 + +###### Requirements with Version Specifiers ###### +# See https://www.python.org/dev/peps/pep-0440/#version-specifiers +docopt == 0.6.1 # Version Matching. Must be version 0.6.1 +keyring >= 4.1.1 # Minimum version 4.1.1 +coverage != 3.5 # Version Exclusion. Anything except version 3.5 +Mopidy-Dirble ~= 1.1 # Compatible release. Same as >= 1.1, == 1.* + +###### Refer to other requirements files ###### +-r other-requirements.txt + +###### A particular file ###### +./downloads/numpy-1.9.2-cp34-none-win32.whl +http://wxpython.org/Phoenix/snapshot-builds/wxPython_Phoenix-3.0.3.dev1820+49a8884-cp34-none-win_amd64.whl + +###### Additional Requirements without Version Specifiers ###### +# Same as 1st section, just here to show that you can put things in any order. +rejected +green +```