pyrfc3339

library2.1.0pypypi✓ verified 27d ago

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.

serialization

pip install pyrfc3339

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYRFC3339

pyrfc3339

serializationpythonv2.1.0

Install

1.5s avg

Import

104ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.110s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.098s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

generate, parse

✓ from pyrfc3339 import generate, parse

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}")

Debug

Known issues

breakingVersion 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`.

affects: >=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.

affects: All

gotchaWhen 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`.

affects: All

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.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pyrfc3339'

The pyrfc3339 library has not been installed in the Python environment, or the environment where the code is run does not have access to the installed package.

fix

Install the library using pip: `pip install pyrfc3339`

TypeError: datetime object must be timezone aware

The pyrfc3339.generate function requires the input datetime object to be timezone-aware; it cannot process naive datetimes.

fix

Provide a timezone-aware datetime object, typically by localizing it to UTC or another timezone using `pytz` or `zoneinfo` (e.g., `dt_aware = dt_naive.replace(tzinfo=timezone.utc)` or `pytz.utc.localize(dt_naive)`).

AttributeError: 'NoneType' object has no attribute 'group'

The `pyrfc3339.parse` function received an input string that does not conform to the expected RFC 3339 format, causing the internal regular expression match to return `None`.

fix

Ensure the input string is a valid RFC 3339 timestamp (e.g., '2014-01-01T12:00:00Z' or '2014-01-01T12:00:00+01:00').

ValueError: Non-zero microsecond value

The `pyrfc3339.parse` function raises a `ValueError` if the input string contains zero-value fractional seconds (e.g., `.000000Z`), expecting them to be omitted or represent actual non-zero values.

fix

Remove the zero-value fractional seconds from the input string (e.g., change '2018-09-06T09:30:00.000000Z' to '2018-09-06T09:30:00Z').

Upgrade

Version history

2.1.0latest on PyPI · released Aug 23, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kurtraschke/pyRFC3339 ↗

packagehttps://pypi.org/project/pyrfc3339/ ↗

docshttps://pyrfc3339.readthedocs.io/ ↗

changeloghttps://github.com/kurtraschke/pyRFC3339/blob/main/CHANGES.rst ↗