Implement `--uploaded-prior-to`

[notatallshaw]

Closes https://github.com/pypa/pip/issues/6257 Supplants https://github.com/pypa/pip/pull/12717 & https://github.com/pypa/pip/pull/13520 (because I accidentally broke that PR)

Design Choices:

Option Name & Semantics - "uploaded-prior-to" was chosen to match semantically with an exclusive upper bound in both the "date" and "datetime" format, e.g. --uploaded-prior-to 2025-01-01 includes only packages uploaded prior to 2025-01-01 00:00:00 (i.e., 2024 and earlier): https://github.com/pypa/pip/pull/13520#discussion_r2289656168

Timezone - Accepts ISO 8601 datetime strings, defaults to local timezone if unspecified. Documentation recommends explicit UTC (Z suffix) or UTC offset for reproducibility: https://github.com/pypa/pip/pull/13520#discussion_r2257136457

Error Handling - Fails immediately if a package index doesn't provide upload-time metadata. File system packages (local directories, wheels, etc.) are unaffected - this only applies to remote indexes: https://github.com/pypa/pip/pull/13520#discussion_r2442503433, so you can specify local packages that depend on remote packages and filter those remote packages by upload time.

[notatallshaw]

Okay, this is again ready for review or approval, though I appreciate if no one will have time before 25.3, I will move to 26.0 if it remains unmerged before release.

[potiuk]

~Small comment here @notatallshaw . What's the difference of this one compared to --exclude-newer ?~

      --exclude-newer <EXCLUDE_NEWER>                  Limit candidate packages to those that were uploaded prior to the given date [env: UV_EXCLUDE_NEWER=]
      --exclude-newer-package <EXCLUDE_NEWER_PACKAGE>  Limit candidate packages for specific packages to those that were uploaded prior to the given date

~It seems suspiciously the same~

UPDATE: Of course I looked at uv pip help not the pip help 🤦 . But the below question still holds:

Also following my #13674 - any chances relative specification can be used in either of those (if it turns out that they are in fact different?) The cooldown feature has been largely discussed in teh security community due to the recent npm Shai Hulud attacks, and it would be great if pip supported that option.

[ichard26]

For the sake of review, I'd much prefer if relative times were added as a follow-up. This PR is already unwieldy to review as-is, adding one more feature will make that worse.

[notatallshaw]

Yes, we will keep discussions about a relative option strictly in https://github.com/pypa/pip/issues/13674, there are many UX questions that need to be answered and it would potentially be a very large PR, it would be much better to land this first and then it can be considered whether to build on top of it for a relative option, as the two intended use cases are quite different.

@potiuk the difference between --uploaded-prior-to and --exclude-newer is that the former is an exclusive upper bound of inclusion and the latter is an exclusive lower bound of exclusion. While for fully specified date times the effect of this is basically nothing, for dates it makes a big difference. --uploaded-prior-to 2025-11-29 is the same as --uploaded-prior-to 2025-11-29 00:00:00 whereas --exclude-newer 2025-11-29 is the same as --exclude-newer 2025-11-29 23:59:59.999999. You can read further discussion on that in this comment thread: https://github.com/pypa/pip/pull/13520#discussion_r2289656168

[potiuk]

Make perfect sense to be follow up. Thanks for explanation @notatallshaw - yeah the exclusive vs. inclusive is something not obvious from the first glance.