Do not allow indexes which don't provide upload-time if --uploaded-prior-to is used

Author: notatallshaw

docs/html/user_guide.rst

@@ -333,9 +333,15 @@ results on different machines.
 
 .. note::
 
-    This option only works with package indexes that provide upload-time metadata
-    (such as PyPI). When upload-time information is not available, packages are not
-    filtered and installation continues normally.
+    This option only applies to packages from indexes, not local files. Local
+    package files are allowed regardless of the ``--uploaded-prior-to`` setting.
+    e.g., ``pip install /path/to/package.whl`` or packages from
+    ``--find-links`` directories.
+
+    This option requires package indexes that provide upload-time metadata
+    (such as PyPI). If the index does not provide upload-time metadata for a
+    package file, pip will fail immediately with an error message indicating
+    that upload-time metadata is required when using ``--uploaded-prior-to``.
 
 You can combine this option with other filtering mechanisms like constraints files:
 
@@ -350,7 +356,6 @@ You can combine this option with other filtering mechanisms like constraints fil
    .. code-block:: shell
 
       py -m pip install -c constraints.txt --uploaded-prior-to=2025-03-16 SomePackage
->>>>>>> e592e95e9 (Add `--uploaded-prior-to` to the user guide)
 
 
 .. _`Dependency Groups`:

pyproject.toml

@@ -268,7 +268,7 @@ max-complexity = 33  # default is 10
 [tool.ruff.lint.pylint]
 max-args = 15  # default is 5
 max-branches = 28  # default is 12
-max-returns = 14  # default is 6
+max-returns = 15  # default is 6
 max-statements = 134  # default is 50
 
 [tool.ruff.per-file-target-version]

src/pip/_internal/index/package_finder.py

@@ -25,10 +25,11 @@
 from pip._internal.exceptions import (
     BestVersionAlreadyInstalled,
     DistributionNotFound,
+    InstallationError,
     InvalidWheelFilename,
     UnsupportedWheel,
 )
-from pip._internal.index.collector import LinkCollector, parse_links
+from pip._internal.index.collector import IndexContent, LinkCollector, parse_links
 from pip._internal.models.candidate import InstallationCandidate
 from pip._internal.models.format_control import FormatControl
 from pip._internal.models.link import Link
@@ -113,6 +114,7 @@ class LinkType(enum.Enum):
     platform_mismatch = enum.auto()
     requires_python_mismatch = enum.auto()
     upload_too_late = enum.auto()
+    upload_time_missing = enum.auto()
 
 
 class LinkEvaluator:
@@ -182,14 +184,6 @@ def evaluate_link(self, link: Link) -> tuple[LinkType, str]:
             reason = link.yanked_reason or "<none given>"
             return (LinkType.yanked, f"yanked for reason: {reason}")
 
-        if link.upload_time is not None and self._uploaded_prior_to is not None:
-            if link.upload_time >= self._uploaded_prior_to:
-                reason = (
-                    f"Upload time {link.upload_time} not "
-                    f"prior to {self._uploaded_prior_to}"
-                )
-                return (LinkType.upload_too_late, reason)
-
         if link.egg_fragment:
             egg_info = link.egg_fragment
             ext = link.ext
@@ -232,6 +226,30 @@ def evaluate_link(self, link: Link) -> tuple[LinkType, str]:
 
                 version = wheel.version
 
+        # Check upload-time filter after verifying the link is a package file.
+        # Skip this check for local files, as --uploaded-prior-to only applies
+        # to packages from indexes.
+        if self._uploaded_prior_to is not None and not link.is_file:
+            if link.upload_time is None:
+                if isinstance(link.comes_from, IndexContent):
+                    index_info = f"Index {link.comes_from.url}"
+                elif link.comes_from:
+                    index_info = f"Index {link.comes_from}"
+                else:
+                    index_info = "Index"
+
+                return (
+                    LinkType.upload_time_missing,
+                    f"{index_info} does not provide upload-time metadata. "
+                    "Cannot use --uploaded-prior-to with this index.",
+                )
+            elif link.upload_time >= self._uploaded_prior_to:
+                return (
+                    LinkType.upload_too_late,
+                    f"Upload time {link.upload_time} not "
+                    f"prior to {self._uploaded_prior_to}",
+                )
+
         # This should be up by the self.ok_binary check, but see issue 2700.
         if "source" not in self._formats and ext != WHEEL_EXTENSION:
             reason = f"No sources permitted for {self.project_name}"
@@ -798,6 +816,10 @@ def get_install_candidate(
         InstallationCandidate and return it. Otherwise, return None.
         """
         result, detail = link_evaluator.evaluate_link(link)
+        if result == LinkType.upload_time_missing:
+            # Fail immediately if the index doesn't provide upload-time
+            # when --uploaded-prior-to is specified
+            raise InstallationError(detail)
         if result != LinkType.candidate:
             self._log_skipped_link(link, result, detail)
             return None

tests/functional/test_uploaded_prior_to.py

@@ -5,32 +5,68 @@
 import pytest
 
 from tests.lib import PipTestEnvironment, TestData
+from tests.lib.server import (
+    file_response,
+    make_mock_server,
+    package_page,
+    server_running,
+)
 
 
 class TestUploadedPriorTo:
-    """Test --uploaded-prior-to functionality.
-
-    Only effective with indexes that provide upload-time metadata.
-    """
+    """Test --uploaded-prior-to functionality."""
 
     def test_uploaded_prior_to_invalid_date(
         self, script: PipTestEnvironment, data: TestData
     ) -> None:
-        """Test that --uploaded-prior-to fails with invalid date format."""
+        """Test that invalid date format is rejected."""
         result = script.pip_install_local(
             "--uploaded-prior-to=invalid-date", "simple", expect_error=True
         )
-
-        # Should fail with date parsing error
         assert "invalid" in result.stderr.lower() or "error" in result.stderr.lower()
 
+    def test_uploaded_prior_to_file_index_no_upload_time(
+        self, script: PipTestEnvironment, data: TestData
+    ) -> None:
+        """Test that file:// indexes are exempt from upload-time filtering."""
+        result = script.pip(
+            "install",
+            "--index-url",
+            data.index_url("simple"),
+            "--uploaded-prior-to=3030-01-01T00:00:00",
+            "simple",
+            expect_error=False,
+        )
+        assert "Successfully installed simple" in result.stdout
+
+    def test_uploaded_prior_to_http_index_no_upload_time(
+        self, script: PipTestEnvironment, data: TestData
+    ) -> None:
+        """Test that HTTP index without upload-time causes immediate error."""
+        server = make_mock_server()
+        simple_package = data.packages / "simple-1.0.tar.gz"
+        server.mock.side_effect = [
+            package_page({"simple-1.0.tar.gz": "/files/simple-1.0.tar.gz"}),
+            file_response(simple_package),
+        ]
+
+        with server_running(server):
+            result = script.pip(
+                "install",
+                "--index-url",
+                f"http://{server.host}:{server.port}",
+                "--uploaded-prior-to=3030-01-01T00:00:00",
+                "simple",
+                expect_error=True,
+            )
+
+        assert "does not provide upload-time metadata" in result.stderr
+        assert "--uploaded-prior-to" in result.stderr or "Cannot use" in result.stderr
+
     @pytest.mark.network
     def test_uploaded_prior_to_with_real_pypi(self, script: PipTestEnvironment) -> None:
-        """Test uploaded-prior-to functionality against real PyPI with upload times."""
-        # Use a small package with known old versions for testing
-        # requests 2.0.0 was released in 2013
-
-        # Test 1: With an old cutoff date, should find no matching versions
+        """Test filtering against real PyPI with upload-time metadata."""
+        # Test with old cutoff date - should find no matching versions
         result = script.pip(
             "install",
             "--dry-run",
@@ -39,10 +75,9 @@ def test_uploaded_prior_to_with_real_pypi(self, script: PipTestEnvironment) -> N
             "requests==2.0.0",
             expect_error=True,
         )
-        # Should fail because requests 2.0.0 was uploaded after 2010
-        assert "No matching distribution found" in result.stderr
+        assert "Could not find a version that satisfies" in result.stderr
 
-        # Test 2: With a date that should find the package
+        # Test with future cutoff date - should find the package
         result = script.pip(
             "install",
             "--dry-run",
@@ -55,8 +90,7 @@ def test_uploaded_prior_to_with_real_pypi(self, script: PipTestEnvironment) -> N
 
     @pytest.mark.network
     def test_uploaded_prior_to_date_formats(self, script: PipTestEnvironment) -> None:
-        """Test different date formats work with real PyPI."""
-        # Test various date formats with a well known small package
+        """Test various date format strings are accepted."""
         formats = [
             "2030-01-01",
             "2030-01-01T00:00:00",
@@ -73,5 +107,34 @@ def test_uploaded_prior_to_date_formats(self, script: PipTestEnvironment) -> Non
                 "requests==2.0.0",
                 expect_error=False,
             )
-            # All dates should allow the package
             assert "Would install requests-2.0.0" in result.stdout
+
+    def test_uploaded_prior_to_allows_local_files(
+        self, script: PipTestEnvironment, data: TestData
+    ) -> None:
+        """Test that local file installs bypass upload-time filtering."""
+        simple_wheel = data.packages / "simplewheel-1.0-py2.py3-none-any.whl"
+
+        result = script.pip(
+            "install",
+            "--no-index",
+            "--uploaded-prior-to=2000-01-01T00:00:00",
+            str(simple_wheel),
+            expect_error=False,
+        )
+        assert "Successfully installed simplewheel-1.0" in result.stdout
+
+    def test_uploaded_prior_to_allows_find_links(
+        self, script: PipTestEnvironment, data: TestData
+    ) -> None:
+        """Test that --find-links bypasses upload-time filtering."""
+        result = script.pip(
+            "install",
+            "--no-index",
+            "--find-links",
+            data.find_links,
+            "--uploaded-prior-to=2000-01-01T00:00:00",
+            "simple==1.0",
+            expect_error=False,
+        )
+        assert "Successfully installed simple-1.0" in result.stdout

tests/unit/test_index.py

@@ -440,13 +440,26 @@ def test_evaluate_link_uploaded_prior_to(
         assert actual == expected_result
 
     def test_evaluate_link_no_upload_time(self) -> None:
-        """Test that links with no upload time are not filtered."""
+        """Test that links with no upload time cause an error when filter is set."""
         uploaded_prior_to = datetime.datetime(
             2023, 6, 1, 0, 0, 0, tzinfo=datetime.timezone.utc
         )
         evaluator = self.make_test_link_evaluator(uploaded_prior_to)
 
-        # Link with no upload_time should not be filtered
+        # Link with no upload_time should be rejected when uploaded_prior_to is set
+        link = Link("https://example.com/myproject-1.0.tar.gz")
+        actual = evaluator.evaluate_link(link)
+
+        # Should be rejected because index doesn't provide upload-time
+        assert actual[0] == LinkType.upload_time_missing
+        assert "Index does not provide upload-time metadata" in actual[1]
+
+    def test_evaluate_link_no_upload_time_no_filter(self) -> None:
+        """Test that links with no upload time are accepted when no filter is set."""
+        # No uploaded_prior_to filter set
+        evaluator = self.make_test_link_evaluator(uploaded_prior_to=None)
+
+        # Link with no upload_time should be accepted when no filter is set
         link = Link("https://example.com/myproject-1.0.tar.gz")
         actual = evaluator.evaluate_link(link)