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

Merge pull request #7079 from pradyunsg/rewrap-user-guide 

Rewrap user guide
This commit is contained in:
Pradyun Gedam 2019-09-28 08:16:01 +05:30 committed by GitHub
parent efd1843af2 5713057db2
commit 8bff9dca6f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 77 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

143
docs/html/user_guide.rst
View File

@ -100,15 +100,13 @@ In practice, there are 4 common uses of Requirements files:
2. Requirements files are used to force pip to properly resolve dependencies.
As it is now, pip `doesn't have true dependency resolution
<https://github.com/pypa/pip/issues/988>`_, but instead simply uses the first
specification it finds for a project. E.g. if ``pkg1`` requires ``pkg3>=1.0`` and
``pkg2`` requires ``pkg3>=1.0,<=2.0``, and if ``pkg1`` is resolved first, pip will
only use ``pkg3>=1.0``, and could easily end up installing a version of ``pkg3``
that conflicts with the needs of ``pkg2``. To solve this problem, you can
place ``pkg3>=1.0,<=2.0`` (i.e. the correct specification) into your
requirements file directly along with the other top level requirements. Like
so:
::
specification it finds for a project. E.g. if ``pkg1`` requires
``pkg3>=1.0`` and ``pkg2`` requires ``pkg3>=1.0,<=2.0``, and if ``pkg1`` is
resolved first, pip will only use ``pkg3>=1.0``, and could easily end up
installing a version of ``pkg3`` that conflicts with the needs of ``pkg2``.
To solve this problem, you can place ``pkg3>=1.0,<=2.0`` (i.e. the correct
specification) into your requirements file directly along with the other top
level requirements. Like so::
pkg1
pkg2
@ -117,20 +115,18 @@ In practice, there are 4 common uses of Requirements files:
3. Requirements files are used to force pip to install an alternate version of a
sub-dependency. For example, suppose ``ProjectA`` in your requirements file
requires ``ProjectB``, but the latest version (v1.3) has a bug, you can force
pip to accept earlier versions like so:
::
pip to accept earlier versions like so::
ProjectA
ProjectB<1.3
4. Requirements files are used to override a dependency with a local patch that
lives in version control. For example, suppose a dependency,
``SomeDependency`` from PyPI has a bug, and you can't wait for an upstream fix.
lives in version control. For example, suppose a dependency
``SomeDependency`` from PyPI has a bug, and you can't wait for an upstream
fix.
You could clone/copy the src, make the fix, and place it in VCS with the tag
``sometag``. You'd reference it in your requirements file with a line like so:
::
``sometag``. You'd reference it in your requirements file with a line like
so::
git+https://myvcs.com/some_dependency@sometag#egg=SomeDependency
@ -198,7 +194,8 @@ to building and installing from source archives. For more information, see the
Pip prefers Wheels where they are available. To disable this, use the
:ref:`--no-binary <install_--no-binary>` flag for :ref:`pip install`.
If no satisfactory wheels are found, pip will default to finding source archives.
If no satisfactory wheels are found, pip will default to finding source
archives.
To install directly from a wheel archive:
@ -215,15 +212,16 @@ convenience, to build wheels for all your requirements and dependencies.
<https://pypi.org/project/wheel/>`_ to be installed, which provides the
"bdist_wheel" setuptools extension that it uses.
To build wheels for your requirements and all their dependencies to a local directory:
To build wheels for your requirements and all their dependencies to a local
directory:
::
pip install wheel
pip wheel --wheel-dir=/local/wheels -r requirements.txt
And *then* to install those requirements just using your local directory of wheels (and not from PyPI):
And *then* to install those requirements just using your local directory of
wheels (and not from PyPI):
::
@ -447,16 +445,18 @@ is the same as calling::
.. note::
Environment variables set to be empty string will not be treated as false. Please use ``no``,
``false`` or ``0`` instead.
Environment variables set to be empty string will not be treated as false.
Please use ``no``, ``false`` or ``0`` instead.
Config Precedence
-----------------
Command line options have precedence over environment variables, which have precedence over the config file.
Command line options have precedence over environment variables, which have
precedence over the config file.
Within the config file, command specific sections have precedence over the global section.
Within the config file, command specific sections have precedence over the
global section.
Examples:
@ -483,8 +483,9 @@ To setup for fish::
$ pip completion --fish > ~/.config/fish/completions/pip.fish
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 startup file::
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
startup file::
eval "`pip completion --bash`"
@ -551,14 +552,16 @@ With Python 2.6 came the `"user scheme" for installation
which means that all Python distributions support an alternative install
location that is specific to a user. The default location for each OS is
explained in the python documentation for the `site.USER_BASE
<https://docs.python.org/3/library/site.html#site.USER_BASE>`_ variable. This mode
of installation can be turned on by specifying the :ref:`--user
<https://docs.python.org/3/library/site.html#site.USER_BASE>`_ variable.
This mode of installation can be turned on by specifying the :ref:`--user
<install_--user>` option to ``pip install``.
Moreover, the "user scheme" can be customized by setting the
``PYTHONUSERBASE`` environment variable, which updates the value of ``site.USER_BASE``.
``PYTHONUSERBASE`` environment variable, which updates the value of
``site.USER_BASE``.
To install "SomePackage" into an environment with site.USER_BASE customized to '/myappenv', do the following::
To install "SomePackage" into an environment with site.USER_BASE customized to
'/myappenv', do the following::
export PYTHONUSERBASE=/myappenv
pip install --user SomePackage
@ -591,7 +594,8 @@ From within a ``--no-site-packages`` virtualenv (i.e. the default kind)::
Can not perform a '--user' install. User site-packages are not visible in this virtualenv.
From within a ``--system-site-packages`` virtualenv where ``SomePackage==0.3`` is already installed in the virtualenv::
From within a ``--system-site-packages`` virtualenv where ``SomePackage==0.3``
is already installed in the virtualenv::
$ pip install --user SomePackage==0.4
Will not install to the user site because it will lack sys.path precedence
@ -604,7 +608,8 @@ From within a real python, where ``SomePackage`` is *not* installed globally::
Successfully installed SomePackage
From within a real python, where ``SomePackage`` *is* installed globally, but is *not* the latest version::
From within a real python, where ``SomePackage`` *is* installed globally, but
is *not* the latest version::
$ pip install --user SomePackage
[...]
@ -615,7 +620,8 @@ From within a real python, where ``SomePackage`` *is* installed globally, but is
Successfully installed SomePackage
From within a real python, where ``SomePackage`` *is* installed globally, and is the latest version::
From within a real python, where ``SomePackage`` *is* installed globally, and
is the latest version::
$ pip install --user SomePackage
[...]
@ -679,7 +685,8 @@ requirements file for free). It can also substitute for a vendor library,
providing easier upgrades and less VCS noise. It does not, of course,
provide the availability benefits of a private index or a vendor library.
For more, see :ref:`pip install\'s discussion of hash-checking mode <hash-checking mode>`.
For more, see
:ref:`pip install\'s discussion of hash-checking mode <hash-checking mode>`.
.. _`Installation Bundle`:
@ -720,50 +727,54 @@ archives are built with identical packages.
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 not use pip's
internal APIs in this way. There are a number of reasons for this:
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
not use pip's internal APIs in this way. There are a number of reasons for this:
#. The pip code assumes that is in sole control of the global state of the program.
Pip manages things like the logging system configuration, or the values of the
standard IO streams, without considering the possibility that user code might be
affected.
#. The pip code assumes that is in sole control of the global state of the
program.
pip manages things like the logging system configuration, or the values of
the standard IO streams, without considering the possibility that user code
might be affected.
#. Pip's code is *not* thread safe. If you were to run pip in a thread, there is no
guarantee that either your code or pip's would work as you expect.
#. pip's code is *not* thread safe. If you were to run pip in a thread, there
is no guarantee that either your code or pip's would work as you expect.
#. Pip assumes that once it has finished its work, the process will terminate. It
doesn't need to handle the possibility that other code will continue to run
after that point, so (for example) calling pip twice in the same process is
likely to have issues.
#. pip assumes that once it has finished its work, the process will terminate.
It doesn't need to handle the possibility that other code will continue to
run after that point, so (for example) calling pip twice in the same process
is likely to have issues.
This does not mean that the pip developers are opposed in principle to the idea that
pip could be used as a library - it's just that this isn't how it was written, and it
would be a lot of work to redesign the internals for use as a library, handling all
of the above issues, and designing a usable, robust and stable API that we could
guarantee would remain available across multiple releases of pip. And we simply don't
currently have the resources to even consider such a task.
This does not mean that the pip developers are opposed in principle to the idea
that pip could be used as a library - it's just that this isn't how it was
written, and it would be a lot of work to redesign the internals for use as a
library, handling all of the above issues, and designing a usable, robust and
stable API that we could guarantee would remain available across multiple
releases of pip. And we simply don't currently have the resources to even
consider such a task.
What this means in practice is that everything inside of pip is considered an
implementation detail. Even the fact that the import name is ``pip`` is subject to
change without notice. While we do try not to break things as much as possible, all
the internal APIs can change at any time, for any reason. It also means that we
generally *won't* fix issues that are a result of using pip in an unsupported way.
implementation detail. Even the fact that the import name is ``pip`` is subject
to change without notice. While we do try not to break things as much as
possible, all the internal APIs can change at any time, for any reason. It also
means that we generally *won't* fix issues that are a result of using pip in an
unsupported way.
It should also be noted that installing packages into ``sys.path`` in a running Python
process is something that should only be done with care. The import system caches
certain data, and installing new packages while a program is running may not always
behave as expected. In practice, there is rarely an issue, but it is something to be
aware of.
It should also be noted that installing packages into ``sys.path`` in a running
Python process is something that should only be done with care. The import
system caches certain data, and installing new packages while a program is
running may not always behave as expected. In practice, there is rarely an
issue, but it is something to be aware of.
Having said all of the above, it is worth covering the options available if you
decide that you do want to run pip from within your program. The most reliable
approach, and the one that is fully supported, is to run pip in a subprocess. This
is easily done using the standard ``subprocess`` module::
approach, and the one that is fully supported, is to run pip in a subprocess.
This is easily done using the standard ``subprocess`` module::
subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'my_package'])
If you want to process the output further, use one of the other APIs in the module::
If you want to process the output further, use one of the other APIs in the
module::
reqs = subprocess.check_output([sys.executable, '-m', 'pip', 'freeze'])