From b7c3503a342ba52b3e782a4a3373f8b31e855e4a Mon Sep 17 00:00:00 2001 From: Sumana Harihareswara Date: Mon, 26 Oct 2020 15:44:15 -0400 Subject: [PATCH 1/6] Add note about install/upgrade behavior to docs Towards #8115. --- docs/html/development/architecture/upgrade-options.rst | 10 +++++++--- docs/html/reference/pip_install.rst | 3 +++ 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/html/development/architecture/upgrade-options.rst b/docs/html/development/architecture/upgrade-options.rst index 36e34c71ee9..0527101f8c6 100644 --- a/docs/html/development/architecture/upgrade-options.rst +++ b/docs/html/development/architecture/upgrade-options.rst @@ -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:: @@ -122,3 +123,6 @@ necessarily resolution or what gets installed. ``--constraint`` ``--editable `` + + +.. _still evolving: https://github.com/pypa/pip/issues/8115 diff --git a/docs/html/reference/pip_install.rst b/docs/html/reference/pip_install.rst index 7d6b5471a2b..be974dacf61 100644 --- a/docs/html/reference/pip_install.rst +++ b/docs/html/reference/pip_install.rst @@ -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 ----------------- From 539303202590abcbe620951c27a44782e3a001b6 Mon Sep 17 00:00:00 2001 From: Sumana Harihareswara Date: Mon, 26 Oct 2020 20:36:36 -0400 Subject: [PATCH 2/6] Improve docs on resolver, constraints, and hash-checking Related to #9020. --- docs/html/user_guide.rst | 10 +++++++++- news/9056.doc.rst | 1 + 2 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 news/9056.doc.rst diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 2e8bfeb026c..391297bb927 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -1446,7 +1446,15 @@ install x y`` in a single command. We 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` and related functionality: + +* Constraints don't override the existing requirements; they simply + constrain what versions are visible as input to the resolver (see + :issue:`9020`) + +* 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`) * Unnamed requirements are not allowed as constraints (see :issue:`6628` and :issue:`8210`) * Links are not allowed as constraints (see :issue:`8253`) diff --git a/news/9056.doc.rst b/news/9056.doc.rst new file mode 100644 index 00000000000..7317dc9cd0d --- /dev/null +++ b/news/9056.doc.rst @@ -0,0 +1 @@ +Improve migration guide to reflect changes in new resolver behavior. From 27b100e8d1086442cd87c274542a465e0b718603 Mon Sep 17 00:00:00 2001 From: Sumana Harihareswara Date: Mon, 26 Oct 2020 21:01:18 -0400 Subject: [PATCH 3/6] Explain resolver changes affecting constraints files Related to #8792, #8076, #9020. --- docs/html/user_guide.rst | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 391297bb927..a1491923e95 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -291,7 +291,10 @@ 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 and stripped +constraints files down to being purely a way to specify global +(version) limits for packages. .. _`Installing from Wheels`: @@ -1446,15 +1449,21 @@ install x y`` in a single command. We 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` and related functionality: +We are also changing our support for :ref:`Constraints Files` 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. 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`) + * 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`) + `==` match on a version and may not work well in combination with + constraints (see :issue:`9020` and :issue:`8792`) * Unnamed requirements are not allowed as constraints (see :issue:`6628` and :issue:`8210`) * Links are not allowed as constraints (see :issue:`8253`) From 395e1ae8e83e49cd24d8e05b7567f907dbdee8f9 Mon Sep 17 00:00:00 2001 From: Sumana Harihareswara Date: Mon, 26 Oct 2020 21:14:16 -0400 Subject: [PATCH 4/6] Add detail to docs on constraints changes with new resolver Related to #8307, #8115. --- docs/html/user_guide.rst | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index a1491923e95..a8439d8c538 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -1449,22 +1449,27 @@ install x y`` in a single command. We 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` 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. Specifically: +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`) - + 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 + ``==`` 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`) From fbcdeca91ae5e781ce9c3b2cd31aac82cbe6825f Mon Sep 17 00:00:00 2001 From: Sumana Harihareswara Date: Tue, 27 Oct 2020 19:32:40 -0400 Subject: [PATCH 5/6] Clarify constraints overhaul in user guide Co-authored-by: Paul Moore --- docs/html/user_guide.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index a8439d8c538..d7107db70a3 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -292,9 +292,10 @@ organisation and use that everywhere. If the thing being installed requires file will be used. Constraints file support was added in pip 7.1. In :ref:`Resolver -changes 2020` we did a fairly comprehensive overhaul and stripped -constraints files down to being purely a way to specify global -(version) limits for packages. +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`: From 3f4e15aef0d406a93e7a9b66280ea054938f7837 Mon Sep 17 00:00:00 2001 From: Sumana Harihareswara Date: Wed, 28 Oct 2020 23:21:11 -0400 Subject: [PATCH 6/6] docs: Emphasize that pip may break existing packages Related to #7744 . --- docs/html/user_guide.rst | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index d7107db70a3..677a8a063e7 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -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 - `_, 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 + `_, 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 @@ -1441,12 +1439,13 @@ 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`_.