RFC 3339 Timestamp Library

2.1.0 · active · verified Sun Apr 05

pyRFC3339 parses and generates RFC 3339-compliant timestamps using Python datetime.datetime objects. It aims to simplify timestamp parsing and generation, leveraging improvements in native Python capabilities. The current stable version is 2.1.0, released on August 23, 2025. It appears to be actively maintained with recent releases and GitHub activity.

Warnings

breaking Version 2.0 and later of `pyrfc3339` require Python 3.9 or higher. Users on Python 3.8 or older must remain on a `pyrfc3339` 1.x release or upgrade their Python interpreter.
Fix: Upgrade Python to 3.9+ or pin `pyrfc3339<2.0.0`.
gotcha `generate()` by default requires timezone-aware `datetime` objects. Passing a 'naive' datetime (one without timezone information) will raise a `ValueError`.
Fix: Ensure `datetime` objects are timezone-aware (e.g., `datetime.now(timezone.utc)`), or explicitly pass `accept_naive=True` to treat naive datetimes as UTC.
gotcha When using `parse()`, if `produce_naive=True` is specified, the returned `datetime` object will not have `tzinfo` attached. This can lead to unexpected behavior if subsequent operations expect a timezone-aware `datetime`.
Fix: Carefully manage `produce_naive` based on whether downstream code expects timezone-aware or naive datetimes. Prefer `utc=True` for consistent UTC output when a timezone is present in the string, or ensure `tzinfo` is handled if `produce_naive=True`.
gotcha `parse()` delegates to Python's native `datetime.datetime.fromisoformat()`. While generally effective, this means it may accept some ISO 8601 formatted timestamps that do not strictly adhere to all nuances of RFC 3339.
Fix: Be aware that not all parsed timestamps might be strictly RFC 3339 compliant, even if `pyrfc3339` successfully parses them. If strict validation is required, additional checks might be necessary.

Install

pip install pyrfc3339 Install stable version

Imports

generate, parse
```
from pyrfc3339 import generate, parse
```

Quickstart

Demonstrates how to generate RFC 3339 timestamps from timezone-aware `datetime` objects and parse RFC 3339 strings back into `datetime` objects, including handling of naive datetimes for generation.

from datetime import datetime, timezone, timedelta
from pyrfc3339 import generate, parse

# Get current UTC time and generate RFC 3339 string
now_utc = datetime.now(timezone.utc)
print(f"Current UTC: {now_utc.isoformat()}")
rfc3339_timestamp = generate(now_utc)
print(f"Generated RFC 3339: {rfc3339_timestamp}")

# Parse an RFC 3339 timestamp
parsed_dt_utc = parse('2009-01-01T10:01:02Z')
print(f"Parsed UTC: {parsed_dt_utc}")

# Parse with an offset
parsed_dt_offset = parse('2009-01-01T14:01:02-04:00')
print(f"Parsed with offset: {parsed_dt_offset}")

# Example of generating from a naive datetime (requires accept_naive=True)
try:
    generate(datetime(2023, 1, 1, 12, 0, 0))
except ValueError as e:
    print(f"Expected error for naive datetime: {e}")

naive_as_utc = generate(datetime(2023, 1, 1, 12, 0, 0), accept_naive=True)
print(f"Generated from naive (as UTC): {naive_as_utc}")

view raw JSON →