Replace deprecated utcnow() and fix UTC-based timedelta date headers

[digitalresistor]

Combines the three outstanding utcnow() / UTC-correctness pull requests into a single branch, with the conflicts resolved and the gaps closed. All three original authors are credited via their own commits.

Issues

• Fixes Python 3.13 deprecation of utcnow() #473 — datetime.datetime.utcnow() is deprecated as of Python 3.12
• Fixes Setting response.expires via timedelta produces an incorrect header value #430 — setting Response.expires via a timedelta produces a header off by the local UTC offset

Supersedes

These are all mutually exclusive — they rewrite the same lines — so none can be merged alongside the others. Their content is included here:

• Supersedes Replace to-be-deprecated utcnow() datetime calls with aware now() calls #475 (@jenstroeger) — aware-datetime handling in serialize_cookie_date
• Supersedes Replace deprecated datetime.datetime.utcnow #480 (@kajinamit) — centralized utcnow() helper
• Supersedes Fix timedelta date headers (e.g. Response.expires) to be UTC-based (fixes #430) #491 (@apoorvdarshan) — UTC-based timedelta date headers

Closing keywords don't apply to PRs, so those three need closing by hand once this lands.

What's here

The deprecation (#473). Takes #480's approach, which @mmerickel favoured in review: a webob.datetime_utils.utcnow() helper built on datetime.now(timezone.utc) that returns a naive UTC datetime. Nothing on the public API surface changes type, which keeps this separate from the tz-aware migration discussed in #473.

Aware datetimes in cookies. Takes #475's fix so that a timezone-aware datetime passed to serialize_cookie_date() is converted to UTC rather than having its local wall-clock time written out as GMT.

One change was needed to make that safe. #475 called v.astimezone(timezone.utc) unconditionally, which treats a naive datetime as local time and shifts it by the machine's UTC offset — WebOb has always treated naive datetimes as UTC. Under TZ=America/New_York:

main                 Tue, 04-Jan-2011 13:43:50 GMT
#475 as submitted    Tue, 04-Jan-2011 18:43:50 GMT

CI runs in UTC, so this is invisible there. The conversion is now gated on v.tzinfo is not None, and test_serialize_cookie_date_naive_datetime_is_utc pins it.

UTC-based timedelta headers (#430). datetime_utils._now was datetime.now, i.e. naive local. The result is fed to calendar.timegm (which reads its argument as UTC) and serialized with usegmt=True, so the value came out off by the local UTC offset.

#491 fixed this by adding a _utcnow = datetime.utcnow hook — but that would reintroduce the deprecated call this branch removes, in the same module. Instead _now is repointed at the utcnow() helper. That also fixes a second occurrence of the same bug that #491 doesn't reach: parse_date_delta() resolved delta seconds against local time, so reading back Response.retry_after returned an instant off by the UTC offset. Keeping the single _now hook means the existing _NowRestorer tests continue to apply to both call sites.

Verified end-to-end against a real Response under TZ=Europe/Berlin:

                  before              after
real UTC now      06:55:14            06:57:32
r.expires         08:55:14  (+2h)     06:57:32  (0s skew)
r.retry_after     08:55:14  (local)   06:57:32  (UTC)
r.cache_expires   correct             correct

Testing

tox across lint, py310–py314, pypy39, pypy310, coverage and docs: all green, 2398 passed / 1 xfailed per interpreter, coverage --fail-under=100 at exactly 100%.

No datetime.utcnow() calls remain in src/ or tests/. The only DeprecationWarning the suite still raises is WebOb's own pre-existing acceptparse.__contains__ one.

New tests: naive/aware/date handling in serialize_cookie_date, the utcnow() helper itself, and tz-sensitive regression tests for both serialize_date and parse_date_delta (skipped where time.tzset() is unavailable).

Not addressed

Response.retry_after still returns a naive datetime on the delta-seconds path while parse_date returns an aware UTC one, so comparing the two raises TypeError. Reconciling that is the tz-aware migration @mmerickel called "much more controversial" in #473, and is deliberately left alone here.

[jenstroeger]

Thank you @digitalresistor for moving this forward!

[digitalresistor]

@jenstroeger do you have any comments on this MR? Just looking for a 👍 to make sure I didn't miss something obvious!

[jenstroeger]

@jenstroeger do you have any comments on this MR? Just looking for a 👍 to make sure I didn't miss something obvious!

The changes look ok to me, though I’m not versed with webob details. One note on the tests: maybe consider using the pytest.setenv() monkeypatch context manager?