Skip to content

Commit

Permalink
Merge pull request #9056 from brainwane/docs-migration-guide-details
Browse files Browse the repository at this point in the history
Improve migration guide re: new resolver
  • Loading branch information
pradyunsg authored Oct 29, 2020
2 parents 1bcebab + 3f4e15a commit 8daece5
Show file tree
Hide file tree
Showing 4 changed files with 51 additions and 21 deletions.
10 changes: 7 additions & 3 deletions docs/html/development/architecture/upgrade-options.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@
Options that control the installation process
=============================================

When installing packages, pip chooses a distribution file, and installs it in
the user's environment. There are many choices involved in deciding which file
to install, and these are controlled by a variety of options.
When installing packages, pip chooses a distribution file, and
installs it in the user's environment. There are many choices (which
are `still evolving`_) involved in deciding which file to install, and
these are controlled by a variety of options.

.. note::

Expand Down Expand Up @@ -122,3 +123,6 @@ necessarily resolution or what gets installed.
``--constraint``

``--editable <LOCATION>``


.. _still evolving: https://github.com/pypa/pip/issues/8115
3 changes: 3 additions & 0 deletions docs/html/reference/pip_install.rst
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@ pip install has several stages:
3. Build wheels. All the dependencies that can be are built into wheels.
4. Install the packages (and uninstall anything being upgraded/replaced).

Note that ``pip install`` prefers to leave the installed version as-is
unless ``--upgrade`` is specified.

Argument Handling
-----------------

Expand Down
58 changes: 40 additions & 18 deletions docs/html/user_guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -197,18 +197,16 @@ In practice, there are 4 common uses of Requirements files:
py -m pip freeze > requirements.txt
py -m pip install -r requirements.txt
2. Requirements files are used to force pip to properly resolve
dependencies. In versions of pip prior to 20.3, 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 for
pip 20.2 and previous, 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::
2. Requirements files are used to force pip to properly resolve dependencies.
pip 20.2 and earlier `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::

pkg1
pkg2
Expand Down Expand Up @@ -291,7 +289,11 @@ organisation and use that everywhere. If the thing being installed requires
"helloworld" to be installed, your fixed version specified in your constraints
file will be used.

Constraints file support was added in pip 7.1.
Constraints file support was added in pip 7.1. In :ref:`Resolver
changes 2020` we did a fairly comprehensive overhaul, removing several
undocumented and unsupported quirks from the previous implementation,
and stripped constraints files down to being purely a way to specify
global (version) limits for packages.

.. _`Installing from Wheels`:

Expand Down Expand Up @@ -1437,17 +1439,37 @@ time to fix the underlying problem in the packages, because pip will
be stricter from here on out.

This also means that, when you run a ``pip install`` command, pip only
considers the packages you are installing in that command, and may
break already-installed packages. It will not guarantee that your
considers the packages you are installing in that command, and **may
break already-installed packages**. It will not guarantee that your
environment will be consistent all the time. If you ``pip install x``
and then ``pip install y``, it's possible that the version of ``y``
you get will be different than it would be if you had run ``pip
install x y`` in a single command. We would like your thoughts on what
install x y`` in a single command. We are considering changing this
behavior (per :issue:`7744`) and would like your thoughts on what
pip's behavior should be; please answer `our survey on upgrades that
create conflicts`_.

We are also changing our support for :ref:`Constraints Files`:

We are also changing our support for :ref:`Constraints Files`,
editable installs, and related functionality. We did a fairly
comprehensive overhaul and stripped constraints files down to being
purely a way to specify global (version) limits for packages, and so
some combinations that used to be allowed will now cause
errors. Specifically:

* Constraints don't override the existing requirements; they simply
constrain what versions are visible as input to the resolver (see
:issue:`9020`)
* Providing an editable requirement (``-e .``) does not cause pip to
ignore version specifiers or constraints (see :issue:`8076`), and if
you have a conflict between a pinned requirement and a local
directory then pip will indicate that it cannot find a version
satisfying both (see :issue:`8307`)
* Hash-checking mode requires that all requirements are specified as a
``==`` match on a version and may not work well in combination with
constraints (see :issue:`9020` and :issue:`8792`)
* If necessary to satisfy constraints, pip will happily reinstall
packages, upgrading or downgrading, without needing any additional
command-line options (see :issue:`8115` and :doc:`development/architecture/upgrade-options`)
* Unnamed requirements are not allowed as constraints (see :issue:`6628` and :issue:`8210`)
* Links are not allowed as constraints (see :issue:`8253`)
* Constraints cannot have extras (see :issue:`6628`)
Expand Down
1 change: 1 addition & 0 deletions news/9056.doc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Improve migration guide to reflect changes in new resolver behavior.

0 comments on commit 8daece5

Please sign in to comment.