mirror of
https://github.com/pypa/pip
synced 2023-12-13 21:30:23 +01:00
expand a bit on the purpose and use of requirement files
This commit is contained in:
parent
2e8d129590
commit
2770524365
|
@ -109,7 +109,8 @@ and you get a dozen packages. Each of these packages has its own version.
|
||||||
Maybe you ran that installation and it works. Great! Will it keep working?
|
Maybe you ran that installation and it works. Great! Will it keep working?
|
||||||
Did you have to provide special options to get it to find everything? Did you
|
Did you have to provide special options to get it to find everything? Did you
|
||||||
have to install a bunch of other optional pieces? Most of all, will you be able
|
have to install a bunch of other optional pieces? Most of all, will you be able
|
||||||
to do it again?
|
to do it again? Requirements files give you a way to create an *environment*:
|
||||||
|
a *set* of packages that work together.
|
||||||
|
|
||||||
If you've ever tried to setup an application on a new system, or with slightly
|
If you've ever tried to setup an application on a new system, or with slightly
|
||||||
updated pieces, and had it fail, pip requirements are for you. If you
|
updated pieces, and had it fail, pip requirements are for you. If you
|
||||||
|
@ -124,11 +125,15 @@ whatever libraries come along, you can create a requirements file something like
|
||||||
Framework==0.9.4
|
Framework==0.9.4
|
||||||
Library>=0.2
|
Library>=0.2
|
||||||
|
|
||||||
Then, regardless of what MyApp lists in ``setup.py``, you'll get a specific
|
Then, regardless of what MyApp lists in ``setup.py``, you'll get a
|
||||||
version of Framework and at least the 0.2 version of Library. (You might think
|
specific version of Framework (0.9.4) and at least the 0.2 version of
|
||||||
you could list these specific versions in ``setup.py`` -- try it and you'll
|
Library. (You might think you could list these specific versions in
|
||||||
quickly see why that doesn't work.) You can add optional libraries and support
|
MyApp's ``setup.py`` -- but if you do that you'll have to edit MyApp
|
||||||
tools that MyApp doesn't strictly require.
|
if you want to try a new version of Framework, or release a new
|
||||||
|
version of MyApp if you determine that Library 0.3 doesn't work with
|
||||||
|
your application.) You can also add optional libraries and support
|
||||||
|
tools that MyApp doesn't strictly require, giving people a set of
|
||||||
|
recommended libraries.
|
||||||
|
|
||||||
You can also include "editable" packages -- packages that are checked out from
|
You can also include "editable" packages -- packages that are checked out from
|
||||||
Subversion, Git, Mercurial and Bazaar. These are just like using the ``-e``
|
Subversion, Git, Mercurial and Bazaar. These are just like using the ``-e``
|
||||||
|
@ -141,6 +146,19 @@ you have to include ``#egg=Package`` so pip knows what to expect at that URL.
|
||||||
You can also include ``@rev`` in the URL, e.g., ``@275`` to check out
|
You can also include ``@rev`` in the URL, e.g., ``@275`` to check out
|
||||||
revision 275.
|
revision 275.
|
||||||
|
|
||||||
|
Requirement files are mostly *flat*. Maybe ``MyApp`` requires
|
||||||
|
``Framework``, and ``Framework`` requires ``Library``. I encourage
|
||||||
|
you to still list all these in a single requirement file; it is the
|
||||||
|
nature of Python programs that there are implicit bindings *directly*
|
||||||
|
between MyApp and Library. For instance, Framework might expose one
|
||||||
|
of Library's objects, and so if Library is updated it might directly
|
||||||
|
break MyApp. If that happens you can update the requirements file to
|
||||||
|
force an earlier version of Library, and you can do that without
|
||||||
|
having to re-release MyApp at all.
|
||||||
|
|
||||||
|
Read the `requirements file format <requirement-format.html>`_ to
|
||||||
|
learn about other features.
|
||||||
|
|
||||||
Freezing Requirements
|
Freezing Requirements
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
|
@ -271,4 +289,4 @@ directly with the eval function of you shell, e.g. by adding::
|
||||||
|
|
||||||
eval `pip completion --bash`
|
eval `pip completion --bash`
|
||||||
|
|
||||||
to your startup file.
|
to your startup file.
|
||||||
|
|
|
@ -1,8 +1,10 @@
|
||||||
The requirements file format
|
The requirements file format
|
||||||
============================
|
============================
|
||||||
|
|
||||||
The requirements file is what pip uses to install packages.
|
The requirements file is a way to get pip to install specific packages
|
||||||
This document describes that format.
|
to make up an *environment*. This document describes that format. To
|
||||||
|
read about *when* you should use requirement files, see `Requirements
|
||||||
|
Files <./#requirements-files>`_.
|
||||||
|
|
||||||
Each line of the requirements file indicates something to be
|
Each line of the requirements file indicates something to be
|
||||||
installed. For example::
|
installed. For example::
|
||||||
|
@ -99,3 +101,38 @@ Tags or revisions can be installed like this::
|
||||||
|
|
||||||
-e bzr+https://bzr.myproject.org/MyProject/trunk/@2019#egg=MyProject
|
-e bzr+https://bzr.myproject.org/MyProject/trunk/@2019#egg=MyProject
|
||||||
-e bzr+http://bzr.myproject.org/MyProject/trunk/@v1.0#egg=MyProject
|
-e bzr+http://bzr.myproject.org/MyProject/trunk/@v1.0#egg=MyProject
|
||||||
|
|
||||||
|
Recursive Requirements
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
If you wish, you can also refer to other requirements files, like::
|
||||||
|
|
||||||
|
-r Pylons-requirements.txt
|
||||||
|
|
||||||
|
This gives you a way of abstracting out sets of requirements. This
|
||||||
|
isn't, however, very friendly with `frozen requirements
|
||||||
|
<./#freezing-requirements>`_, as everything in
|
||||||
|
``Pylons-requirements.txt`` will show up in your frozen file.
|
||||||
|
|
||||||
|
Indexes, find-links
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
You can also provide values for the ``--index`` and ``--find-links``
|
||||||
|
options in your requirement files, like::
|
||||||
|
|
||||||
|
--index http://example.com/private-pypi/
|
||||||
|
|
||||||
|
Note that using ``--index`` removes the use of `PyPI
|
||||||
|
<http://pypi.python.org>`_, while using ``--extra-index`` will add
|
||||||
|
additional indexes.
|
||||||
|
|
||||||
|
``--find-links`` is more ad-hoc; instead of a complete "index", you
|
||||||
|
only need an HTML page of links to available packages. Simply by
|
||||||
|
putting all your private packages in a directory and using the Apache
|
||||||
|
auto-index, you can publish your packages so pip can find them.
|
||||||
|
``--find-links`` is always additive; pip looks at everything it can
|
||||||
|
find. Use it like::
|
||||||
|
|
||||||
|
--find-link http://example.com/private-packages/
|
||||||
|
|
||||||
|
Note that all these options must be on a line of their own.
|
||||||
|
|
Loading…
Reference in a new issue