Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Describe --upgrade-strategy and direct requirements explicitly #8739

Closed
wants to merge 2 commits into from
Closed

docs: Describe --upgrade-strategy and direct requirements explicitly #8739

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3b1aea0
docs: Describe --upgrade-strategy and direct requirements explicitly
EricCousineau-TRI Aug 9, 2020
b6218a0
TO BE SQUAHSED? add news/ entry
EricCousineau-TRI Aug 9, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/html/development/architecture/upgrade-options.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@ candidate.
``--upgrade-strategy``

This option affects which packages are allowed to be installed. It is only
relevant if ``--upgrade`` is specified. The base behaviour is to allow
relevant if ``--upgrade`` is specified (except for the ``to-satisfy-only``
option mentioned below). The base behaviour is to allow
packages specified on pip's command line to be upgraded. This option controls
what *other* packages can be upgraded:

Expand All @@ -40,7 +41,8 @@ what *other* packages can be upgraded:
currently installed.
* ``to-satisfy-only`` (**undocumented**) - packages are not upgraded (not
even direct requirements) unless the currently installed version fails to
satisfy a requirement (either explicitly specified or a dependency).
satisfy a requirement (either explicitly specified or a dependency). This
is actually the "default" strategy when ``--upgrade`` is not set.

``--force-reinstall``

Expand Down
5 changes: 5 additions & 0 deletions docs/html/reference/pip_install.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -871,6 +871,11 @@ Examples

$ pip install --upgrade SomePackage

.. note::

This will only update ``SomePackage`` as it is a direct requirement. Any
of its dependencies (indirect requirements) will be affected by the
``--upgrade-strategy`` command.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indirect requirements can still be upgraded here if a later version of SomePackage needs them upgraded. Say

  • SomePackage==1.0 needs DepPackage==1.0
  • SomePackage==2.0 needs DepPackage==2.0

With SomePackage==1.0 and DepPackage==1.0 initially installed, pip install --upgrade SomePackage will still upgrade DepPackage.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IOW, only SomePackage is guarenteed to be upgraded. Its dependencies are upgraded only if needed.


#. Install a local project in "editable" mode. See the section on :ref:`Editable Installs <editable-installs>`.

Expand Down
15 changes: 15 additions & 0 deletions docs/html/user_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -598,6 +598,21 @@ strategies supported:
The default strategy is ``only-if-needed``. This was changed in pip 10.0 due to
the breaking nature of ``eager`` when upgrading conflicting dependencies.

It is important to note that ``--upgrade`` affects *direct requirements* (e.g.
those specified on the command-line or via a requirements file) while
``--upgrade-strategy`` affects *indirect requirements* (dependencies of direct
requirements).

As an example, say ``SomePackage`` has a dependency, ``SomeDependency``, and
both of them are already installed but are not the latest avaialable versions:

- ``pip install SomePackage``: will not upgrade the existing ``SomePackage`` or
``SomeDependency``.
- ``pip install --upgrade SomePackage``: will upgrade ``SomePackage``, but not
``SomeDependency`` (unless a minimum requirement is not met).
- ``pip install --upgrade SomePackage --upgrade-strategy=eager``: upgrades both
``SomePackage`` and ``SomeDependency``.

As an historic note, an earlier "fix" for getting the ``only-if-needed``
behaviour was::

Expand Down
3 changes: 3 additions & 0 deletions news/8739.doc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
Describe --upgrade-strategy and direct requirements explicitly

Add a brief example