Update docs and news items to make clear index needs to provide upload-time field

Author: notatallshaw

news/13520.feature.rst

@@ -1 +1,2 @@
-Add ``--exclude-newer-than`` option to exclude packages uploaded after a given date.
+Add ``--exclude-newer-than`` option to exclude packages uploaded after a given date,
+only effective with indexes that provide upload-time metadata.

src/pip/_internal/cli/cmdoptions.py

@@ -846,6 +846,10 @@ def _handle_exclude_newer_than(
 
     Parses an ISO 8601 datetime string. If no timezone is specified in the string,
     local timezone is used.
+
+    Note: This option only works with indexes that provide upload-time metadata
+    as specified in the simple repository API:
+    https://packaging.python.org/en/latest/specifications/simple-repository-api/
     """
     if value is None:
         return None
@@ -874,10 +878,9 @@ def _handle_exclude_newer_than(
     callback=_handle_exclude_newer_than,
     type="str",
     help=(
-        "Exclude packages newer than given time. This should be an ISO 8601 string. "
-        "If no timezone is specified, local time is used. "
-        "For consistency across environments, specify the timezone explicitly "
-        "e.g., '2023-01-01T00:00:00Z' for UTC or '2023-01-01T00:00:00-05:00' for UTC-5."
+        "Exclude packages newer than given time. Accepts ISO 8601 strings "
+        "(e.g., '2023-01-01T00:00:00Z'). Uses local timezone if none specified. "
+        "Only effective when installing from indexes that provide upload-time metadata."
     ),
 )
 

tests/functional/test_exclude_newer.py

@@ -1,4 +1,7 @@
-"""Tests for pip install --exclude-newer-than."""
+"""Tests for pip install --exclude-newer-than.
+
+Only effective with indexes that provide upload-time metadata.
+"""
 
 from __future__ import annotations
 
@@ -8,7 +11,10 @@
 
 
 class TestExcludeNewer:
-    """Test --exclude-newer-than functionality."""
+    """Test --exclude-newer-than functionality.
+
+    Only effective with indexes that provide upload-time metadata.
+    """
 
     def test_exclude_newer_than_invalid_date(
         self, script: PipTestEnvironment, data: TestData

tests/unit/test_finder.py

@@ -579,7 +579,10 @@ def test_find_all_candidates_find_links_and_index(data: TestData) -> None:
 
 
 class TestPackageFinderExcludeNewerThan:
-    """Test PackageFinder integration with exclude_newer_than functionality."""
+    """Test PackageFinder integration with exclude_newer_than functionality.
+
+    Only effective with indexes that provide upload-time metadata.
+    """
 
     def test_package_finder_create_with_exclude_newer_than(self) -> None:
         """Test that PackageFinder.create() accepts exclude_newer_than parameter."""

tests/unit/test_index.py

@@ -367,7 +367,10 @@ def test_filter_unallowed_hashes__log_message_with_no_match(
 
 
 class TestLinkEvaluatorExcludeNewerThan:
-    """Test the exclude_newer_than functionality in LinkEvaluator."""
+    """Test the exclude_newer_than functionality in LinkEvaluator.
+
+    Only effective with indexes that provide upload-time metadata.
+    """
 
     def make_test_link_evaluator(
         self, exclude_newer_than: datetime.datetime | None = None