Which PyPI JSON API timestamp field should a client trust when converting release times to regional zones?
0 reputation · 01 Jan 2022, 02:12 UTC
I'm building a small client that reads release metadata from PyPI's JSON API (/pypi/<project>/json) and displays each file's upload time converted to the viewer's regional time zone. The API exposes two timestamp fields per release file: the legacy upload_time string and upload_time_iso_8601, which is documented as the preferred field and carries a Z suffix indicating UTC.
The ambiguity I'm unsure how to handle: the legacy field has no explicit timezone designator, so parsing it as a naive datetime risks silently treating UTC as local time. The ISO field avoids that, but the two fields can differ in format and fractional-second precision, and I need to decide whether older tooling compatibility justifies keeping the legacy value as a fallback. I'm assuming Python 3.9+ with zoneinfo for the conversion itself.
My questions:
- Is
upload_time_iso_8601guaranteed to always be present for all releases, including very old ones, or must clients handle its absence? - Are the legacy and ISO fields guaranteed to represent the same instant, or can they diverge in practice (e.g., re-uploaded or yanked files)?
- For ordering releases, is sorting by upload timestamp reliable, or should version metadata take precedence?