RFC 3339 Date/Time Formatting

6.2 · active · verified Sat Apr 11

The `rfc3339` library for Python provides utilities to format `datetime` objects into RFC 3339 compliant strings and to parse such strings back into `datetime` objects. It closely adheres to the RFC 3339 standard, including providing its own UTC `tzinfo` implementation. While the PyPI package `6.2` was last released in 2019, the primary GitHub repository shows recent maintenance activity, indicating it's still actively maintained, albeit with a slow release cadence.

Warnings

gotcha The `rfc3339` library, like Python's standard `datetime` module, does not support or account for leap seconds in its parsing or generation. While RFC 3339 specifies them, this library (and Python's native `datetime`) treats all minutes as 60 seconds long.
Fix: Applications requiring precise handling of leap seconds must implement custom logic or use specialized libraries that provide this functionality, as it's not handled by standard Python `datetime` or this library.
gotcha The library explicitly states it does not implement RFC 3339 Section 4.3, "Unknown Local Offset Convention." This means it might not correctly handle or generate timestamps where the local offset is truly unknown and represented by '-00:00' semantically distinct from '+00:00' or 'Z'.
Fix: When dealing with timestamps that might originate from systems using the 'Unknown Local Offset Convention', verify how the specific string format is handled. For strict adherence, consider manual parsing or pre-processing if '-00:00' must carry this specific semantic meaning.
gotcha The parsing routines in `rfc3339` primarily focus on Section 5.6, "Internet Date/Time Format." While this is a common and strict profile of RFC 3339 (and ISO 8601), more lenient or alternative RFC 3339 compliant variations might not be parsed correctly. For broader ISO 8601 parsing, other libraries like `python-dateutil` might be more suitable.
Fix: Ensure input strings strictly adhere to the 'Internet Date/Time Format' profile (e.g., 'T' separator, explicit offset like 'Z' or '+HH:MM'). If you encounter parsing failures for valid RFC 3339 strings, inspect their exact format against Section 5.6 of the RFC.
gotcha Python's `datetime` module itself has complexities with timezones, especially when dealing with naive datetimes or converting between different timezone representations (local vs. UTC, DST transitions). While `rfc3339` provides its own UTC `tzinfo`, inconsistencies can arise if not carefully managed with the underlying `datetime` objects.
Fix: Always ensure your `datetime` objects are timezone-aware (e.g., created with `timezone.utc` or `pytz` timezones) before passing them to `rfc3339` functions for consistent results. Avoid mixing timezone-aware and naive `datetime` objects.

Install

pip install rfc3339 Install latest version

Imports

rfc3339
```
import rfc3339
```
The library itself is imported as `rfc3339`.

Quickstart

This quickstart demonstrates how to format a `datetime` object into an RFC 3339 compliant string and parse such a string back into a `datetime` object using the `rfc3339` library. It also includes an example of parsing a string with a specific timezone offset.

from datetime import datetime, timezone
import rfc3339

# Get current UTC time
now_utc = datetime.now(timezone.utc)

# Format a datetime object to RFC 3339 string
rfc3339_string = rfc3339.rfc3339(now_utc)
print(f"Formatted: {rfc3339_string}")

# Parse an RFC 3339 string back to a datetime object
parsed_datetime = rfc3339.parse_rfc3339(rfc3339_string)
print(f"Parsed: {parsed_datetime}")

# Example with a specific date and offset
date_with_offset_str = "2023-10-27T10:00:00-05:00"
parsed_with_offset = rfc3339.parse_rfc3339(date_with_offset_str)
print(f"Parsed with offset: {parsed_with_offset}")

view raw JSON →