pypa · pradyunsg · Sep 28, 2019 · Sep 24, 2019
diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst
@@ -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.
-
-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.
+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.
 
 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'])