Rename to --uploaded-prior-to, require remote index to have upload-time, pass to SubprocessBuildEnvironmentInstaller

Author: notatallshaw

docs/html/user_guide.rst

@@ -297,6 +297,66 @@ Example build constraints file (``build-constraints.txt``):
    cython==0.29.24
 
 
+.. _`Filtering by Upload Time`:
+
+Filtering by Upload Time
+=========================
+
+The ``--uploaded-prior-to`` option allows you to filter packages by their upload time
+to an index, only considering packages that were uploaded before a specified datetime.
+This can be useful for creating reproducible builds by ensuring you only install
+packages that were available at a known point in time.
+
+.. tab:: Unix/macOS
+
+   .. code-block:: shell
+
+      python -m pip install --uploaded-prior-to=2025-03-16T00:00:00Z SomePackage
+
+.. tab:: Windows
+
+   .. code-block:: shell
+
+      py -m pip install --uploaded-prior-to=2025-03-16T00:00:00Z SomePackage
+
+The option accepts ISO 8601 datetime strings in several formats:
+
+* ``2025-03-16`` - Date in local timezone
+* ``2025-03-16 12:30:00`` - Datetime in local timezone
+* ``2025-03-16T12:30:00Z`` - Datetime in UTC
+* ``2025-03-16T12:30:00+05:00`` - Datetime in UTC offset
+
+For consistency across machines, use either UTC format (with 'Z' suffix) or UTC offset
+format (with timezone offset like '+05:00'). Local timezone formats may produce different
+results on different machines.
+
+.. note::
+
+    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:
+
+.. tab:: Unix/macOS
+
+   .. code-block:: shell
+
+      python -m pip install -c constraints.txt --uploaded-prior-to=2025-03-16 SomePackage
+
+.. tab:: Windows
+
+   .. code-block:: shell
+
+      py -m pip install -c constraints.txt --uploaded-prior-to=2025-03-16 SomePackage
+
+
 .. _`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/build_env.py

@@ -230,6 +230,8 @@ def install(
             # in the isolated build environment
             extra_environ = {"extra_environ": {"_PIP_IN_BUILD_IGNORE_CONSTRAINTS": "1"}}
 
+        if finder.uploaded_prior_to:
+            args.extend(["--uploaded-prior-to", finder.uploaded_prior_to.isoformat()])
         args.append("--")
         args.extend(requirements)
 

src/pip/_internal/cli/cmdoptions.py

@@ -28,6 +28,7 @@
 from pip._internal.models.format_control import FormatControl
 from pip._internal.models.index import PyPI
 from pip._internal.models.target_python import TargetPython
+from pip._internal.utils.datetime import parse_iso_datetime
 from pip._internal.utils.hashes import STRONG_HASHES
 from pip._internal.utils.misc import strtobool
 
@@ -833,31 +834,51 @@ def _handle_dependency_group(
 )
 
 
-def _handle_upload_before(
+def _handle_uploaded_prior_to(
     option: Option, opt: str, value: str, parser: OptionParser
 ) -> None:
     """
-    Process a value provided for the --upload-before option.
+    This is an optparse.Option callback for the --uploaded-prior-to option.
 
-    This is an optparse.Option callback for the --upload-before option.
+    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
-    upload_before = datetime.datetime.fromisoformat(value)
-    # Assume local timezone if no offset is given in the ISO string.
-    if upload_before.tzinfo is None:
-        upload_before = upload_before.astimezone()
-    parser.values.upload_before = upload_before
+
+    try:
+        uploaded_prior_to = parse_iso_datetime(value)
+        # Use local timezone if no offset is given in the ISO string.
+        if uploaded_prior_to.tzinfo is None:
+            uploaded_prior_to = uploaded_prior_to.astimezone()
+        parser.values.uploaded_prior_to = uploaded_prior_to
+    except ValueError as exc:
+        msg = (
+            f"invalid --uploaded-prior-to value: {value!r}: {exc}. "
+            f"Expected an ISO 8601 datetime string, "
+            f"e.g '2023-01-01' or '2023-01-01T00:00:00Z'"
+        )
+        raise_option_error(parser, option=option, msg=msg)
 
 
-upload_before: Callable[..., Option] = partial(
+uploaded_prior_to: Callable[..., Option] = partial(
     Option,
-    "--upload-before",
-    dest="upload_before",
+    "--uploaded-prior-to",
+    dest="uploaded_prior_to",
     metavar="datetime",
     action="callback",
-    callback=_handle_upload_before,
-    help="Skip uploads after given time. This should be an ISO 8601 string.",
+    callback=_handle_uploaded_prior_to,
+    type="str",
+    help=(
+        "Only consider packages uploaded prior to the given date 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."
+    ),
 )
 
 no_build_isolation: Callable[..., Option] = partial(

src/pip/_internal/cli/req_command.py

@@ -5,6 +5,8 @@
 PackageFinder machinery and all its vendored dependencies, etc.
 """
 
+from __future__ import annotations
+
 import logging
 import os
 from functools import partial
@@ -346,7 +348,6 @@ def _build_package_finder(
         session: PipSession,
         target_python: TargetPython | None = None,
         ignore_requires_python: bool | None = None,
-        upload_before: datetime.datetime | None = None,
     ) -> PackageFinder:
         """
         Create a package finder appropriate to this requirement command.
@@ -367,5 +368,5 @@ def _build_package_finder(
             link_collector=link_collector,
             selection_prefs=selection_prefs,
             target_python=target_python,
-            upload_before=upload_before,
+            uploaded_prior_to=options.uploaded_prior_to,
         )

src/pip/_internal/commands/download.py

@@ -49,7 +49,7 @@ def add_options(self) -> None:
         self.cmd_opts.add_option(cmdoptions.use_pep517())
         self.cmd_opts.add_option(cmdoptions.check_build_deps())
         self.cmd_opts.add_option(cmdoptions.ignore_requires_python())
-        self.cmd_opts.add_option(cmdoptions.upload_before())
+        self.cmd_opts.add_option(cmdoptions.uploaded_prior_to())
 
         self.cmd_opts.add_option(
             "-d",
@@ -93,7 +93,6 @@ def run(self, options: Values, args: list[str]) -> int:
             session=session,
             target_python=target_python,
             ignore_requires_python=options.ignore_requires_python,
-            upload_before=options.upload_before,
         )
 
         build_tracker = self.enter_context(get_build_tracker())

src/pip/_internal/commands/index.py

@@ -1,4 +1,6 @@
-import datetime
+from __future__ import annotations
+
+import json
 import logging
 from collections.abc import Iterable
 from optparse import Values
@@ -38,7 +40,7 @@ def add_options(self) -> None:
         cmdoptions.add_target_python_options(self.cmd_opts)
 
         self.cmd_opts.add_option(cmdoptions.ignore_requires_python())
-        self.cmd_opts.add_option(cmdoptions.upload_before())
+        self.cmd_opts.add_option(cmdoptions.uploaded_prior_to())
         self.cmd_opts.add_option(cmdoptions.pre())
         self.cmd_opts.add_option(cmdoptions.json())
         self.cmd_opts.add_option(cmdoptions.no_binary())
@@ -85,7 +87,6 @@ def _build_package_finder(
         session: PipSession,
         target_python: TargetPython | None = None,
         ignore_requires_python: bool | None = None,
-        upload_before: datetime.datetime | None = None,
     ) -> PackageFinder:
         """
         Create a package finder appropriate to the index command.
@@ -103,7 +104,7 @@ def _build_package_finder(
             link_collector=link_collector,
             selection_prefs=selection_prefs,
             target_python=target_python,
-            upload_before=upload_before,
+            uploaded_prior_to=options.uploaded_prior_to,
         )
 
     def get_available_package_versions(self, options: Values, args: list[Any]) -> None:
@@ -119,7 +120,6 @@ def get_available_package_versions(self, options: Values, args: list[Any]) -> No
                 session=session,
                 target_python=target_python,
                 ignore_requires_python=options.ignore_requires_python,
-                upload_before=options.upload_before,
             )
 
             versions: Iterable[Version] = (

src/pip/_internal/commands/install.py

@@ -207,7 +207,7 @@ def add_options(self) -> None:
             ),
         )
 
-        self.cmd_opts.add_option(cmdoptions.upload_before())
+        self.cmd_opts.add_option(cmdoptions.uploaded_prior_to())
         self.cmd_opts.add_option(cmdoptions.ignore_requires_python())
         self.cmd_opts.add_option(cmdoptions.no_build_isolation())
         self.cmd_opts.add_option(cmdoptions.use_pep517())
@@ -342,7 +342,6 @@ def run(self, options: Values, args: list[str]) -> int:
             session=session,
             target_python=target_python,
             ignore_requires_python=options.ignore_requires_python,
-            upload_before=options.upload_before,
         )
         build_tracker = self.enter_context(get_build_tracker())
 

src/pip/_internal/commands/list.py

@@ -143,10 +143,8 @@ def handle_pip_version_check(self, options: Values) -> None:
             super().handle_pip_version_check(options)
 
     def _build_package_finder(
-        self,
-        options: Values,
-        session: "PipSession",
-    ) -> "PackageFinder":
+        self, options: Values, session: PipSession
+    ) -> PackageFinder:
         """
         Create a package finder appropriate to this list command.
         """

src/pip/_internal/commands/lock.py

@@ -65,6 +65,7 @@ def add_options(self) -> None:
         self.cmd_opts.add_option(cmdoptions.src())
 
         self.cmd_opts.add_option(cmdoptions.ignore_requires_python())
+        self.cmd_opts.add_option(cmdoptions.uploaded_prior_to())
         self.cmd_opts.add_option(cmdoptions.no_build_isolation())
         self.cmd_opts.add_option(cmdoptions.use_pep517())
         self.cmd_opts.add_option(cmdoptions.check_build_deps())