Merge remote-tracking branch 'origin/main' into fix-direct-preference

Author: notatallshaw

.github/workflows/update-rtd-redirects.yml

@@ -3,6 +3,9 @@ name: Update documentation redirects
 on:
   push:
     branches: [main]
+    paths:
+      - ".readthedocs-custom-redirects.yml"
+      - ".readthedocs.yml"
   schedule:
     - cron: 0 0 * * MON # Run every Monday at 00:00 UTC
 
@@ -22,7 +25,6 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
-      - run: pip install httpx pyyaml rich
-      - run: python tools/update-rtd-redirects.py
+      - run: pipx run tools/update-rtd-redirects.py
         env:
           RTD_API_TOKEN: ${{ secrets.RTD_API_TOKEN }}

build-requirements.txt

@@ -18,7 +18,7 @@ pyproject-hooks==1.2.0 \
     # via build
 
 # The following packages are considered to be unsafe in a requirements file:
-setuptools==75.8.0 \
-    --hash=sha256:c5afc8f407c626b8313a86e10311dd3f661c6cd9c09d4bf8c15c0e11f9f2b0e6 \
-    --hash=sha256:e3982f444617239225d675215d51f6ba05f845d4eec313da4418fdbb56fb27e3
+setuptools==76.0.0 \
+    --hash=sha256:199466a166ff664970d0ee145839f5582cb9bca7a0a3a2e795b6a9cb2308e9c6 \
+    --hash=sha256:43b4ee60e10b0d0ee98ad11918e114c70701bc6051662a9a675a0496c1a158f4
     # via -r build-requirements.in

docs/html/topics/more-dependency-resolution.md

@@ -160,16 +160,22 @@ Pip's current implementation of the provider implements
 
 * If Requires-Python is present only consider that
 * If there are causes of resolution conflict (backtrack causes) then
-  only consider them until there are no longer any resolution conflicts
-
-Pip's current implementation of the provider implements `get_preference` as
-follows:
-
-* Prefer if any of the known requirements is "direct", e.g. points to an
-    explicit URL.
-* If equal, prefer if any requirement is "pinned", i.e. contains
-    operator ``===`` or ``==``.
-* Order user-specified requirements by the order they are specified.
-* If equal, prefers "non-free" requirements, i.e. contains at least one
-    operator, such as ``>=`` or ``<``.
-* If equal, order alphabetically for consistency (helps debuggability).
+    only consider them until there are no longer any resolution conflicts
+
+Pip's current implementation of the provider implements `get_preference`
+for known requirements with the following preferences in the following order:
+
+* Any requirement that is "direct", e.g., points to an explicit URL.
+* Any requirement that is "pinned", i.e., contains the operator ``===``
+    or ``==`` without a wildcard.
+* Any requirement that imposes an upper version limit, i.e., contains the
+    operator ``<``, ``<=``, ``~=``, or ``==`` with a wildcard. Because
+    pip prioritizes the latest version, preferring explicit upper bounds
+    can rule out infeasible candidates sooner. This does not imply that
+    upper bounds are good practice; they can make dependency management
+    and resolution harder.
+* Order user-specified requirements as they are specified, placing
+    other requirements afterward.
+* Any "non-free" requirement, i.e., one that contains at least one
+    operator, such as ``>=`` or ``!=``.
+* Alphabetical order for consistency (aids debuggability).

news/13270.bugfix.rst

@@ -0,0 +1,3 @@
+Fix a regression that causes dependencies to be checked *before* ``Requires-Python``
+project metadata is checked, leading to wasted cycles when the Python version is
+unsupported.

news/13273.feature.rst

@@ -0,0 +1 @@
+Improved heuristics for determining the order of dependency resolution.

news/CacheControl.vendor.rst

@@ -0,0 +1 @@
+Upgrade CacheControl to 0.14.2

news/certifi.vendor.rst

@@ -0,0 +1 @@
+Upgrade certifi to 2025.1.31

news/pygments.vendor.rst

@@ -0,0 +1 @@
+Upgrade pygments to 2.19.1

src/pip/_internal/resolution/resolvelib/candidates.py

@@ -249,10 +249,12 @@ def _prepare(self) -> BaseDistribution:
         return dist
 
     def iter_dependencies(self, with_requires: bool) -> Iterable[Optional[Requirement]]:
+        # Emit the Requires-Python requirement first to fail fast on
+        # unsupported candidates and avoid pointless downloads/preparation.
+        yield self._factory.make_requires_python_requirement(self.dist.requires_python)
         requires = self.dist.iter_dependencies() if with_requires else ()
         for r in requires:
             yield from self._factory.make_requirements_from_spec(str(r), self._ireq)
-        yield self._factory.make_requires_python_requirement(self.dist.requires_python)
 
     def get_install_requirement(self) -> Optional[InstallRequirement]:
         return self._ireq

src/pip/_internal/resolution/resolvelib/provider.py

@@ -166,14 +166,20 @@ def get_preference(
 
         Currently pip considers the following in order:
 
-        * Prefer if any of the known requirements is "direct", e.g. points to an
-          explicit URL.
-        * If equal, prefer if any requirement is "pinned", i.e. contains
-          operator ``===`` or ``==``.
-        * Order user-specified requirements by the order they are specified.
-        * If equal, prefers "non-free" requirements, i.e. contains at least one
-          operator, such as ``>=`` or ``<``.
-        * If equal, order alphabetically for consistency (helps debuggability).
+        * Any requirement that is "direct", e.g., points to an explicit URL.
+        * Any requirement that is "pinned", i.e., contains the operator ``===``
+          or ``==`` without a wildcard.
+        * Any requirement that imposes an upper version limit, i.e., contains the
+          operator ``<``, ``<=``, ``~=``, or ``==`` with a wildcard. Because
+          pip prioritizes the latest version, preferring explicit upper bounds
+          can rule out infeasible candidates sooner. This does not imply that
+          upper bounds are good practice; they can make dependency management
+          and resolution harder.
+        * Order user-specified requirements as they are specified, placing
+          other requirements afterward.
+        * Any "non-free" requirement, i.e., one that contains at least one
+          operator, such as ``>=`` or ``!=``.
+        * Alphabetical order for consistency (aids debuggability).
         """
         try:
             next(iter(information[identifier]))
@@ -206,12 +212,17 @@ def get_preference(
         ]
 
         pinned = any(((op[:2] == "==") and ("*" not in ver)) for op, ver in operators)
+        upper_bounded = any(
+            ((op in ("<", "<=", "~=")) or (op == "==" and "*" in ver))
+            for op, ver in operators
+        )
         unfree = bool(operators)
         requested_order = self._user_requested.get(identifier, math.inf)
 
         return (
             not direct,
             not pinned,
+            not upper_bounded,
             requested_order,
             not unfree,
             identifier,
@@ -263,6 +274,7 @@ def _eligible_for_upgrade(identifier: str) -> bool:
     def is_satisfied_by(self, requirement: Requirement, candidate: Candidate) -> bool:
         return requirement.is_satisfied_by(candidate)
 
-    def get_dependencies(self, candidate: Candidate) -> Sequence[Requirement]:
+    def get_dependencies(self, candidate: Candidate) -> Iterable[Requirement]:
         with_requires = not self._ignore_dependencies
-        return [r for r in candidate.iter_dependencies(with_requires) if r is not None]
+        # iter_dependencies() can perform nontrivial work so delay until needed.
+        return (r for r in candidate.iter_dependencies(with_requires) if r is not None)