From 6017256f1acc5eaccc26a104fd999fb026993c2f Mon Sep 17 00:00:00 2001 From: Nicole Harris Date: Tue, 30 Jun 2020 16:41:06 +0100 Subject: [PATCH] Fix copy, formatting --- docs/html/user_guide.rst | 105 +++++++++++++++++++++------------------ 1 file changed, 56 insertions(+), 49 deletions(-) diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index eb6c25b2a52..3c929926c3c 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -791,19 +791,21 @@ like this: :: - pip install packageA==0.44.1 packageB==4.3.0 - Due to conflicting dependencies pip cannot install packageA and packageB: - - packageA depends on packageC<3.0.0,>=2.4.2 - - packageB depends on packageC==2.3.1 + pip install package_coffee==0.44.1 package_tea==4.3.0 + Due to conflicting dependencies pip cannot install package_coffee and + package_tea: + - package_coffee depends on package_water<3.0.0,>=2.4.2 + - package_tea depends on package_water==2.3.1 In this example, pip cannot install the packages you have requested, because they each depend on different versions of the same package -(``packageC``): +(``package_water``): -- ``packageA`` version ``0.44.1`` depends on a version of ``packageC`` - that is less than ``3.0.0`` but greater than or equal to ``2.4.2`` -- ``packageB`` version ``4.3.0`` depends on version ``2.3.1`` of - ``packageC`` +- ``package_coffee`` version ``0.44.1`` depends on a version of +``package_water`` that is less than ``3.0.0`` but greater than or equal to +``2.4.2`` +- ``package_tea`` version ``4.3.0`` depends on version ``2.3.1`` of + ``package_water`` Sometimes these messages are straightforward to read, because they use commonly understood comparison operators to specify the required version @@ -842,58 +844,59 @@ The solution to your error will depend on your individual use case. Here are some things to try: 1. Audit your top level requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As a first step it is useful to audit your project and remove any -unneccessary or out of date requirements. Removing these can -significantly reduce the complexity of your dependency tree, thereby -reducing opportunities for conflicts to occur. +unnecessary or out of date requirements (e.g. from your ``setup.py`` or +``requirements.txt`` files). Removing these can significantly reduce the +complexity of your dependency tree, thereby reducing opportunities for +conflicts to occur. 2. Loosen your top level requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sometimes the packages that you have asked pip to install are incompatible because you have been too strict when you specified the package version. -In our first example both ``packageA`` and ``packageB`` have been +In our first example both ``package_coffee`` and ``package_tea`` have been *pinned* to use specific versions -(``packageA==0.44.1b0 packageB==4.3.0``). +(``package_coffee==0.44.1b0 package_tea==4.3.0``). -To find a version of both ``packageA`` and ``packageB`` that depend on -the same version of ``packageC``, you might consider: +To find a version of both ``package_coffee`` and ``package_tea`` that depend on +the same version of ``package_water``, you might consider: - Loosening the range of packages that you are prepared to install - (e.g. ``pip install "packageA>0.44.*" "packageB>4.0.0"``) -- Asking pip to install *any* version of ``packageA`` and ``packageB`` + (e.g. ``pip install "package_coffee>0.44.*" "package_tea>4.0.0"``) +- Asking pip to install *any* version of ``package_coffee`` and ``package_tea`` by removing the version specifiers altogether (e.g. - ``pip install packageA packageB``) + ``pip install package_coffee package_tea``) In the second case, pip will automatically find a version of both -``packageA`` and ``packageB`` that depend on the same version of -``packageC``, installing: +``package_coffee`` and ``package_tea`` that depend on the same version of +``package_water``, installing: -- ``packageA 0.46.0b0``, which depends on ``packageC 2.6.1`` -- ``packageB 4.3.0`` which *also* depends on ``packageC 2.6.1`` +- ``package_coffee 0.46.0b0``, which depends on ``package_water 2.6.1`` +- ``package_tea 4.3.0`` which *also* depends on ``package_water 2.6.1`` -If you want to prioritise one package over another, you can add version +If you want to prioritize one package over another, you can add version specifiers to *only* the more important package:: - pip install packageA==0.44.1b0 packageB + pip install package_coffee==0.44.1b0 package_tea -This will result in: - ``packageA 0.44.1b0``, which depends on -``packageC 2.6.1`` - ``packageB 4.1.3`` which also depends on -``packageC 2.6.1`` +This will result in: - ``package_coffee 0.44.1b0``, which depends on +``package_water 2.6.1`` - ``package_tea 4.1.3`` which also depends on +``package_water 2.6.1`` Now that you have resolved the issue, you can repin the compatible package versions as required. -3. Loosen the requirements of your downstream dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +3. Loosen the requirements of your dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Assuming that you cannot resolve the conflict by loosening the version of the package you require (as above), you can try to fix the issue on -your *downstream dependency* by: +your *dependency* by: - Requesting that the package maintainers loosen *their* dependencies - Forking the package and loosening the dependencies yourself @@ -904,17 +907,15 @@ your *downstream dependency* by: any support provided by the package maintainers. Proceed at your own risk! 4. All requirements are loose, but a solution does not exist -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sometimes it's simply impossible to find a combination of package -versions that do not conflict. Welcome to `dependency -hell `__. +versions that do not conflict. Welcome to `dependency hell`_. In this situation, you could consider: - Using an alternative package, if that is acceptable for your project. - See `Awesome Python `__ for similar - packages. + See `Awesome Python`_ for similar packages. - Refactoring your project to reduce the number of dependencies (for example, by breaking up a monolithic code base into smaller pieces) @@ -924,21 +925,27 @@ Getting help If none of the suggestions above work for you, we recommend that you ask for help on: -- `Python user Discourse `__ -- `Python user forums `__ -- `Python developers Slack channel `__ -- `Python IRC `__ -- `Stack - Overflow `__ +- `Python user Discourse`_ +- `Python user forums`_ +- `Python developers Slack channel`_ +- `Python IRC`_ +- `Stack Overflow`_ -See `"How do I ask a good -question?" `__ for tips on -asking for help. +See `"How do I ask a good question?"`_ for tips on asking for help. Unfortunately, **the pip team cannot provide support for individual dependency conflict errors**. Please *only* open a ticket on the `pip -issue tracker `__ if you believe -that your problem has exposed a bug in pip. +issue tracker`_ if you believe that your problem has exposed a bug in pip. + +.. _dependency hell: https://en.wikipedia.org/wiki/Dependency_hell> +.. _Awesome Python: https://python.libhunt.com/ +.. _Python user Discourse: https://discuss.python.org/c/users/7 +.. _Python user forums: https://www.python.org/community/forums/ +.. _Python developers Slack channel: https://pythondev.slack.com/ +.. _Python IRC: https://www.python.org/community/irc/ +.. _Stack Overflow: https://stackoverflow.com/questions/tagged/python +.. _"How do I ask a good question?": https://stackoverflow.com/help/how-to-ask +.. _pip issue tracker: https://github.com/pypa/pip/issues Using pip from your program ===========================