Change name to uploaded prior to

Author: notatallshaw

news/13520.feature.rst

@@ -1,2 +1,2 @@
-Add ``--exclude-newer-than`` option to exclude packages uploaded after a given date,
-only effective with indexes that provide upload-time metadata.
+Add ``--uploaded-prior-to`` option to only consider packages uploaded prior to
+a given datetime when the ``upload-time`` field is available from an index.

src/pip/_internal/build_env.py

@@ -167,8 +167,8 @@ def install(
             args.append("--pre")
         if finder.prefer_binary:
             args.append("--prefer-binary")
-        if finder.exclude_newer_than:
-            args.extend(["--exclude-newer-than", finder.exclude_newer_than.isoformat()])
+        if finder.uploaded_prior_to:
+            args.extend(["--uploaded-prior-to", finder.uploaded_prior_to.isoformat()])
         args.append("--")
         args.extend(requirements)
         with open_spinner(f"Installing {kind}") as spinner:

src/pip/_internal/cli/cmdoptions.py

@@ -798,13 +798,11 @@ def _handle_dependency_group(
 )
 
 
-def _handle_exclude_newer_than(
+def _handle_uploaded_prior_to(
     option: Option, opt: str, value: str, parser: OptionParser
 ) -> None:
     """
-    Process a value provided for the --exclude-newer-than option.
-
-    This is an optparse.Option callback for the --exclude-newer-than option.
+    This is an optparse.Option callback for the --uploaded-prior-to option.
 
     Parses an ISO 8601 datetime string. If no timezone is specified in the string,
     local timezone is used.
@@ -817,32 +815,33 @@ def _handle_exclude_newer_than(
         return None
 
     try:
-        exclude_newer_than = parse_iso_datetime(value)
+        uploaded_prior_to = parse_iso_datetime(value)
         # Use local timezone if no offset is given in the ISO string.
-        if exclude_newer_than.tzinfo is None:
-            exclude_newer_than = exclude_newer_than.astimezone()
-        parser.values.exclude_newer_than = exclude_newer_than
+        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 --exclude-newer-than value: {value!r}: {exc}. "
+            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)
 
 
-exclude_newer_than: Callable[..., Option] = partial(
+uploaded_prior_to: Callable[..., Option] = partial(
     Option,
-    "--exclude-newer-than",
-    dest="exclude_newer_than",
+    "--uploaded-prior-to",
+    dest="uploaded_prior_to",
     metavar="datetime",
     action="callback",
-    callback=_handle_exclude_newer_than,
+    callback=_handle_uploaded_prior_to,
     type="str",
     help=(
-        "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."
+        "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."
     ),
 )
 

src/pip/_internal/cli/req_command.py

@@ -348,5 +348,5 @@ def _build_package_finder(
             link_collector=link_collector,
             selection_prefs=selection_prefs,
             target_python=target_python,
-            exclude_newer_than=options.exclude_newer_than,
+            uploaded_prior_to=options.uploaded_prior_to,
         )

src/pip/_internal/commands/download.py

@@ -51,7 +51,7 @@ def add_options(self) -> None:
         self.cmd_opts.add_option(cmdoptions.no_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.exclude_newer_than())
+        self.cmd_opts.add_option(cmdoptions.uploaded_prior_to())
 
         self.cmd_opts.add_option(
             "-d",

src/pip/_internal/commands/index.py

@@ -40,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.exclude_newer_than())
+        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())
@@ -104,7 +104,7 @@ def _build_package_finder(
             link_collector=link_collector,
             selection_prefs=selection_prefs,
             target_python=target_python,
-            exclude_newer_than=options.exclude_newer_than,
+            uploaded_prior_to=options.uploaded_prior_to,
         )
 
     def get_available_package_versions(self, options: Values, args: list[Any]) -> None:

src/pip/_internal/commands/install.py

@@ -207,7 +207,7 @@ def add_options(self) -> None:
             ),
         )
 
-        self.cmd_opts.add_option(cmdoptions.exclude_newer_than())
+        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())

src/pip/_internal/commands/lock.py

@@ -67,7 +67,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.exclude_newer_than())
+        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.no_use_pep517())

src/pip/_internal/commands/wheel.py

@@ -64,7 +64,7 @@ def add_options(self) -> None:
         self.cmd_opts.add_option(cmdoptions.requirements())
         self.cmd_opts.add_option(cmdoptions.src())
         self.cmd_opts.add_option(cmdoptions.ignore_requires_python())
-        self.cmd_opts.add_option(cmdoptions.exclude_newer_than())
+        self.cmd_opts.add_option(cmdoptions.uploaded_prior_to())
         self.cmd_opts.add_option(cmdoptions.no_deps())
         self.cmd_opts.add_option(cmdoptions.progress_bar())
 

src/pip/_internal/index/package_finder.py

@@ -134,7 +134,7 @@ def __init__(
         target_python: TargetPython,
         allow_yanked: bool,
         ignore_requires_python: bool | None = None,
-        exclude_newer_than: datetime.datetime | None = None,
+        uploaded_prior_to: datetime.datetime | None = None,
     ) -> None:
         """
         :param project_name: The user supplied package name.
@@ -152,7 +152,8 @@ def __init__(
         :param ignore_requires_python: Whether to ignore incompatible
             PEP 503 "data-requires-python" values in HTML links. Defaults
             to False.
-        :param exclude_newer_than: If set, only allow links prior to the given date.
+        :param uploaded_prior_to: If set, only allow links uploaded prior to
+            the given datetime.
         """
         if ignore_requires_python is None:
             ignore_requires_python = False
@@ -162,7 +163,7 @@ def __init__(
         self._ignore_requires_python = ignore_requires_python
         self._formats = formats
         self._target_python = target_python
-        self._exclude_newer_than = exclude_newer_than
+        self._uploaded_prior_to = uploaded_prior_to
 
         self.project_name = project_name
 
@@ -181,10 +182,11 @@ 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._exclude_newer_than is not None:
-            if link.upload_time > self._exclude_newer_than:
+        if link.upload_time is not None and self._uploaded_prior_to is not None:
+            if self._uploaded_prior_to < link.upload_time:
                 reason = (
-                    f"Upload time {link.upload_time} after {self._exclude_newer_than}"
+                    f"Upload time {link.upload_time} not "
+                    f"prior to {self._uploaded_prior_to}"
                 )
                 return (LinkType.upload_too_late, reason)
 
@@ -605,7 +607,7 @@ def __init__(
         format_control: FormatControl | None = None,
         candidate_prefs: CandidatePreferences | None = None,
         ignore_requires_python: bool | None = None,
-        exclude_newer_than: datetime.datetime | None = None,
+        uploaded_prior_to: datetime.datetime | None = None,
     ) -> None:
         """
         This constructor is primarily meant to be used by the create() class
@@ -627,7 +629,7 @@ def __init__(
         self._ignore_requires_python = ignore_requires_python
         self._link_collector = link_collector
         self._target_python = target_python
-        self._exclude_newer_than = exclude_newer_than
+        self._uploaded_prior_to = uploaded_prior_to
 
         self.format_control = format_control
 
@@ -651,7 +653,7 @@ def create(
         link_collector: LinkCollector,
         selection_prefs: SelectionPreferences,
         target_python: TargetPython | None = None,
-        exclude_newer_than: datetime.datetime | None = None,
+        uploaded_prior_to: datetime.datetime | None = None,
     ) -> PackageFinder:
         """Create a PackageFinder.
 
@@ -660,7 +662,8 @@ def create(
         :param target_python: The target Python interpreter to use when
             checking compatibility. If None (the default), a TargetPython
             object will be constructed from the running Python.
-        :param exclude_newer_than: If set, only find links prior to the given date.
+        :param uploaded_prior_to: If set, only find links uploaded prior
+            to the given datetime.
         """
         if target_python is None:
             target_python = TargetPython()
@@ -677,7 +680,7 @@ def create(
             allow_yanked=selection_prefs.allow_yanked,
             format_control=selection_prefs.format_control,
             ignore_requires_python=selection_prefs.ignore_requires_python,
-            exclude_newer_than=exclude_newer_than,
+            uploaded_prior_to=uploaded_prior_to,
         )
 
     @property
@@ -738,8 +741,8 @@ def set_prefer_binary(self) -> None:
         self._candidate_prefs.prefer_binary = True
 
     @property
-    def exclude_newer_than(self) -> datetime.datetime | None:
-        return self._exclude_newer_than
+    def uploaded_prior_to(self) -> datetime.datetime | None:
+        return self._uploaded_prior_to
 
     def requires_python_skipped_reasons(self) -> list[str]:
         reasons = {
@@ -760,7 +763,7 @@ def make_link_evaluator(self, project_name: str) -> LinkEvaluator:
             target_python=self._target_python,
             allow_yanked=self._allow_yanked,
             ignore_requires_python=self._ignore_requires_python,
-            exclude_newer_than=self._exclude_newer_than,
+            uploaded_prior_to=self._uploaded_prior_to,
         )
 
     def _sort_links(self, links: Iterable[Link]) -> list[Link]: