Support pip 26.1+ duration format (P7D) for PIP_UPLOADED_PRIOR_TO

[mprpic]

Background

pip 26.1 (released April 26, 2026) added support for ISO 8601 duration format in addition to absolute timestamps for --uploaded-prior-to:

• Absolute timestamp (pip 26.0+): 2024-04-28T12:00:00Z
• Relative duration (pip 26.1+): P7D (7 days)

Both formats remain supported. See: https://pip.pypa.io/en/stable/news/#v26-1

Current State

cooldowns.sh only generates and validates absolute timestamps:

1. set_pip() generates timestamps via _date_days_ago() → "2024-04-28T12:00:00Z"
2. check_date_staleness() assumes dates and tries to parse with date_to_epoch()
3. If a user manually sets export PIP_UPLOADED_PRIOR_TO=P7D (valid for pip 26.1+), cooldowns.sh check fails silently

Problem

Related to #1 (comment):

• date_to_epoch() fails when given duration format
• Errors are masked by 2>/dev/null
• Users get cryptic "can't parse date" warnings

Proposed Changes

Support both formats in set_pip() and check_pip():

1. set_pip() changes:

   • For pip ≥ 26.1: offer duration format as an option (e.g., cooldowns.sh set pip 7d --duration)
   • Default: keep current behavior (absolute timestamps for compatibility)
   • Document both formats in comments and help text

2. check_pip() changes:

   • Detect if value is duration (P\d+D) vs timestamp (\d{4}-\d{2}-\d{2})
   • For durations: report as configured (no staleness check needed)
   • For timestamps: continue using check_date_staleness()

3. Error handling improvements:

   • Better validation in date_to_epoch() before calling date
   • More helpful error messages when parsing fails
   • Remove or improve 2>/dev/null suppression

4. Documentation updates:

   • Update script header comments to mention both formats
   • Update examples to show both options
   • Note pip version requirements

[mprpic]

Fixed via a0234cc