pyrfc3339.generator – Generate RFC 3339 timestamps

pyrfc3339.generator.generate(dt: datetime, utc: bool = True, accept_naive: bool = False, microseconds: bool = False) → str

Generate an RFC 3339-formatted timestamp from a datetime.datetime.

>>> from datetime import datetime, timezone
>>> from zoneinfo import ZoneInfo
>>> generate(datetime(2009, 1, 1, 12, 59, 59, 0, timezone.utc))
'2009-01-01T12:59:59Z'

The timestamp be normalized to UTC unless utc=False is specified, in which case it will use the timezone from the datetime’s tzinfo attribute.

>>> eastern = ZoneInfo('US/Eastern')
>>> dt = datetime(2009, 1, 1, 12, 59, 59, tzinfo=eastern)
>>> generate(dt)
'2009-01-01T17:59:59Z'
>>> generate(dt, utc=False)
'2009-01-01T12:59:59-05:00'

Unless accept_naive=True is specified, the datetime must not be naive.

>>> generate(datetime(2009, 1, 1, 12, 59, 59, 0))
Traceback (most recent call last):
...
ValueError: naive datetime and accept_naive is False

>>> generate(datetime(2009, 1, 1, 12, 59, 59, 0), accept_naive=True)
'2009-01-01T12:59:59Z'

If, however, accept_naive=True is specified, the datetime is assumed to represent a UTC time. Attempting to generate a local timestamp from a naive datetime will result in an error.

>>> generate(datetime(2009, 1, 1, 12, 59, 59, 0), accept_naive=True, utc=False)
Traceback (most recent call last):
...
ValueError: cannot generate a local timestamp from a naive datetime
Parameters:

  • dt (datetime.datetime) – the datetime for which to generate an RFC 3339 timestamp.

  • utc (bool) – True to normalize the supplied datetime.datetime to UTC; False otherwise. Defaults to True.

  • accept_naive (bool) – True if generate() should accept a ‘naive’ datetime (that is, one without timezone information) and treat it as a UTC timestamp; False otherwise. Defaults to False.

  • microseconds (bool) – True to generate a timestamp which includes fractional seconds, if present; False otherwise. Defaults to False. Note that fractional seconds are truncated, not rounded when microseconds is False.

Returns:

the supplied datetime instance represented as an RFC 3339 timestamp

Return type:

str