pyRFC3339

https://pyrfc3339.readthedocs.io/
Admin
pyRFC3339 parses and generates RFC 3339-compliant timestamps using Python datetime.datetime objects.
Tokens:5,349
Snippets:29
Trust Score:9.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### Import and use pyrfc3339 generate and parse functions

Source: https://pyrfc3339.readthedocs.io/en/latest/pyrfc3339.html

Shows how to import generate and parse from pyrfc3339, and demonstrates generating an RFC 3339 timestamp from a UTC datetime and parsing two example timestamps. The output for generate is abbreviated with '...' in the source.

```python
>>> from pyrfc3339 import generate, parse
>>> from datetime import datetime, timezone
>>> generate(datetime.now(timezone.utc))
'...T...Z'
>>> parse('2009-01-01T10:01:02Z')
datetime.datetime(2009, 1, 1, 10, 1, 2, tzinfo=datetime.timezone.utc)
>>> parse('2009-01-01T14:01:02-04:00')
datetime.datetime(2009, 1, 1, 14, 1, 2, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=72000)))
```

--------------------------------

### datetime_utcoffset with aware datetime

Source: https://pyrfc3339.readthedocs.io/en/latest/utils.html

Shows how to use datetime_utcoffset with an aware datetime. The example creates a datetime with a timezone and prints the UTC offset in seconds.

```python
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> z = ZoneInfo('US/Eastern')
>>> dt = datetime(2024, 11, 5, 19, 7, 6, tzinfo=z)
>>> datetime_utcoffset(dt)
-18000.0
```

--------------------------------

### generate(datetime)

Source: https://pyrfc3339.readthedocs.io/en/latest/pyrfc3339.html

Generates an RFC 3339 timestamp string from a datetime object. The example shows generating a timestamp from a timezone-aware datetime.

```APIDOC
## generate(datetime)

### Description
Generates an RFC 3339 timestamp string from a datetime object.

### Method
Function

### Signature
`generate(datetime)`

### Parameters
- **datetime** (datetime.datetime) - Required - A timezone-aware datetime object.

### Return Value
- **str** - The RFC 3339 formatted timestamp string.

### Example
```python
>>> from pyrfc3339 import generate
>>> from datetime import datetime, timezone
>>> generate(datetime.now(timezone.utc))
'...T...Z'
```
```

--------------------------------

### Generate and parse RFC 3339 timestamps with pyRFC3339

Source: https://pyrfc3339.readthedocs.io/en/latest/intro.html

Shows the primary API: generate() creates an RFC 3339 string from a datetime, and parse() converts RFC 3339 strings back to datetime objects. The parse examples include UTC and an explicit -04:00 offset, which yields a timezone with a negative UTC offset.

```python
>>> from pyrfc3339 import generate, parse
>>> from datetime import UTC, datetime
>>> generate(datetime.now(UTC))
'...T...Z'
>>> parse('2009-01-01T10:01:02Z')
datetime.datetime(2009, 1, 1, 10, 1, 2, tzinfo=datetime.timezone.utc)
>>> parse('2009-01-01T14:01:02-04:00')
datetime.datetime(2009, 1, 1, 14, 1, 2, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=72000)))


```

--------------------------------

### parse(timestamp)

Source: https://pyrfc3339.readthedocs.io/en/latest/pyrfc3339.html

Parses an RFC 3339 timestamp string into a datetime object. The example shows parsing both UTC and offset timestamps.

```APIDOC
## parse(timestamp)

### Description
Parses an RFC 3339 timestamp string into a datetime object.

### Method
Function

### Signature
`parse(timestamp)`

### Parameters
- **timestamp** (str) - Required - An RFC 3339 formatted timestamp string.

### Return Value
- **datetime.datetime** - The parsed datetime object with timezone information.

### Examples
```python
>>> from pyrfc3339 import parse
>>> parse('2009-01-01T10:01:02Z')
datetime.datetime(2009, 1, 1, 10, 1, 2, tzinfo=datetime.timezone.utc)
>>> parse('2009-01-01T14:01:02-04:00')
datetime.datetime(2009, 1, 1, 14, 1, 2, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=72000)))
```
```

--------------------------------

### Generate timestamp with timezone normalization and utc=False

Source: https://pyrfc3339.readthedocs.io/en/latest/generator.html

Demonstrates normalization to UTC by default and local timezone output when utc=False.

```python
>>> 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'

```

--------------------------------

### Generate timestamp from naive datetime with accept_naive=True

Source: https://pyrfc3339.readthedocs.io/en/latest/generator.html

With accept_naive=True, a naive datetime is treated as UTC and generates a timestamp.

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

```

--------------------------------

### generate(dt, utc=True, accept_naive=False, microseconds=False)

Source: https://pyrfc3339.readthedocs.io/en/latest/generator.html

Generates an RFC 3339-formatted timestamp from a datetime.datetime object. The timestamp is normalized to UTC by default, but can be generated in the datetime's own timezone by setting utc=False. Naive datetimes are rejected unless accept_naive=True, in which case they are treated as UTC. Fractional seconds are included only if microseconds=True.

```APIDOC
## generate(dt, utc=True, accept_naive=False, microseconds=False)

### Description
Generates an RFC 3339-formatted timestamp from a `datetime.datetime` object. The timestamp is normalized to UTC by default, but can be generated in the datetime's own timezone by setting `utc=False`. Naive datetimes are rejected unless `accept_naive=True`, in which case they are treated as UTC. Fractional seconds are included only if `microseconds=True`.

### Method
Function

### Signature
`generate(dt: datetime.datetime, utc: bool = True, accept_naive: bool = False, microseconds: bool = False) -> str`

### Parameters
- **dt** (datetime.datetime) - Required - The datetime for which to generate an RFC 3339 timestamp.
- **utc** (bool) - Optional - True to normalize the supplied datetime to UTC; False otherwise. Defaults to True.
- **accept_naive** (bool) - Optional - True if generate() should accept a 'naive' datetime (one without timezone information) and treat it as a UTC timestamp; False otherwise. Defaults to False.
- **microseconds** (bool) - Optional - 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
- **str** - The supplied datetime instance represented as an RFC 3339 timestamp.

### Examples
```python
>>> from datetime import datetime, UTC
>>> from zoneinfo import ZoneInfo
>>> generate(datetime(2009, 1, 1, 12, 59, 59, 0, UTC))
'2009-01-01T12:59:59Z'

>>> 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'

>>> 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'

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

--------------------------------

### Error for naive datetime without accept_naive

Source: https://pyrfc3339.readthedocs.io/en/latest/generator.html

Shows the ValueError raised when a naive datetime is passed without accept_naive=True.

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

```

--------------------------------

### Normalize timestamp to UTC with utc=True

Source: https://pyrfc3339.readthedocs.io/en/latest/parser.html

Parses a timestamp with an offset and normalizes it to UTC when utc=True, setting tzinfo to datetime.timezone.utc.

```python
>>> parse('2009-01-01T06:01:02-04:00', utc=True)
datetime.datetime(2009, 1, 1, 10, 1, 2, tzinfo=datetime.timezone.utc)
```

--------------------------------

### Error for local timestamp from naive datetime

Source: https://pyrfc3339.readthedocs.io/en/latest/generator.html

Attempting to generate a local timestamp from a naive datetime raises ValueError.

```python
>>> 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

```

--------------------------------

### Generate RFC 3339 timestamp from UTC datetime

Source: https://pyrfc3339.readthedocs.io/en/latest/generator.html

Basic usage of generate() with a UTC datetime, producing a timestamp ending in 'Z'.

```python
>>> from datetime import datetime, UTC
>>> from zoneinfo import ZoneInfo
>>> generate(datetime(2009, 1, 1, 12, 59, 59, 0, UTC))
'2009-01-01T12:59:59Z'

```

--------------------------------

### datetime_utcoffset with naive datetime raises AssertionError

Source: https://pyrfc3339.readthedocs.io/en/latest/utils.html

Shows that passing a naive datetime (without timezone) to datetime_utcoffset raises an AssertionError.

```python
>>> dt = datetime(2024, 11, 5, 19, 7, 6)
>>> datetime_utcoffset(dt)
Traceback (most recent call last):
...
AssertionError
```

--------------------------------

### parse(timestamp: str, utc: bool = False, produce_naive: bool = False) -> datetime

Source: https://pyrfc3339.readthedocs.io/en/latest/parser.html

Parses an RFC 3339-formatted timestamp and returns a datetime.datetime object. Supports timezone normalization to UTC and optional naive datetime output.

```APIDOC
## parse(timestamp: str, utc: bool = False, produce_naive: bool = False) -> datetime

### Description
Parse an RFC 3339-formatted timestamp and return a datetime.datetime. If the timestamp is in UTC, the tzinfo attribute is set to datetime.timezone.utc. Otherwise, a datetime.timezone instance with the appropriate offset is used. If utc=True, the result is normalized to UTC. If produce_naive=True, the returned datetime has no timezone attached.

### Method
Function

### Signature
parse(timestamp: str, utc: bool = False, produce_naive: bool = False) -> datetime

### Parameters
- **timestamp** (str) - Required - The RFC 3339 timestamp to be parsed.
- **utc** (bool) - Optional - True to normalize the timestamp to UTC; False otherwise. Defaults to False.
- **produce_naive** (bool) - Optional - True if the produced datetime instance should not have a timezone attached (naive); False otherwise. Defaults to False.

### Returns
- **datetime.datetime** - The parsed timestamp.

### Examples
```python
>>> parse('2009-01-01T10:01:02Z')
datetime.datetime(2009, 1, 1, 10, 1, 2, tzinfo=datetime.timezone.utc)

>>> parse('2009-01-01T14:01:02-04:00')
datetime.datetime(2009, 1, 1, 14, 1, 2, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=72000)))

>>> parse('2009-01-01T06:01:02-04:00', utc=True)
datetime.datetime(2009, 1, 1, 10, 1, 2, tzinfo=datetime.timezone.utc)

>>> parse('2009-01-01T06:01:02')
datetime.datetime(2009, 1, 1, 6, 1, 2)
```

### Exceptions
Raises ValueError for invalid input, e.g., hour out of range.
```python
>>> parse('2009-01-01T25:01:02Z')
Traceback (most recent call last):
...
ValueError: hour must be in 0..23
```
```

--------------------------------

### pyrfc3339.parser.parse()

Source: https://pyrfc3339.readthedocs.io/en/latest/doc.html

This snippet documents the `parse()` function from the `pyrfc3339.parser` module, which parses an RFC 3339 timestamp string into a datetime object.

```APIDOC
## `pyrfc3339.parser.parse()`

### Description
Parses an RFC 3339 formatted timestamp string into a datetime object.

### Method
Function call

### Endpoint
`pyrfc3339.parser.parse(timestamp, utc=False, produce_naive=False)`

### Parameters
- **timestamp** (str) - Required - The RFC 3339 timestamp string to parse.
- **utc** (bool) - Optional - If True, the returned datetime will be in UTC. Default is False.
- **produce_naive** (bool) - Optional - If True, a naive datetime object is returned. Default is False.

### Request Example
```python
from pyrfc3339 import parse

timestamp = '2023-01-01T12:00:00+00:00'
result = parse(timestamp)
```

### Response
#### Success Response
- **result** (datetime) - The parsed datetime object.

#### Response Example
```python
datetime.datetime(2023, 1, 1, 12, 0, tzinfo=datetime.timezone.utc)
```
```

--------------------------------

### pyrfc3339.generator.generate()

Source: https://pyrfc3339.readthedocs.io/en/latest/doc.html

This snippet documents the `generate()` function from the `pyrfc3339.generator` module, which converts a datetime object into an RFC 3339 timestamp string.

```APIDOC
## `pyrfc3339.generator.generate()`

### Description
Generates an RFC 3339 formatted timestamp string from a given datetime object.

### Method
Function call

### Endpoint
`pyrfc3339.generator.generate(dt, utc=False, accept_naive=False)`

### Parameters
- **dt** (datetime) - Required - The datetime object to convert to an RFC 3339 string.
- **utc** (bool) - Optional - If True, the output will be in UTC (Z) format. Default is False.
- **accept_naive** (bool) - Optional - If True, naive datetime objects are accepted. Default is False.

### Request Example
```python
from pyrfc3339 import generate
from datetime import datetime

dt = datetime(2023, 1, 1, 12, 0, 0)
result = generate(dt)
```

### Response
#### Success Response
- **result** (str) - The RFC 3339 formatted timestamp string.

#### Response Example
```python
'2023-01-01T12:00:00+00:00'
```
```

--------------------------------

### pyrfc3339.utils.datetime_utcoffset()

Source: https://pyrfc3339.readthedocs.io/en/latest/doc.html

This snippet documents the `datetime_utcoffset()` function from the `pyrfc3339.utils` module, which returns the UTC offset of a datetime object.

```APIDOC
## `pyrfc3339.utils.datetime_utcoffset()`

### Description
Returns the UTC offset of a given datetime object as a timedelta.

### Method
Function call

### Endpoint
`pyrfc3339.utils.datetime_utcoffset(dt)`

### Parameters
- **dt** (datetime) - Required - The datetime object to get the UTC offset from.

### Request Example
```python
from pyrfc3339.utils import datetime_utcoffset
from datetime import datetime, timezone

dt = datetime(2023, 1, 1, tzinfo=timezone.utc)
offset = datetime_utcoffset(dt)
```

### Response
#### Success Response
- **offset** (timedelta) - The UTC offset of the datetime object.

#### Response Example
```python
datetime.timedelta(0)
```
```

--------------------------------

### Parse UTC timestamp with parse()

Source: https://pyrfc3339.readthedocs.io/en/latest/parser.html

Parses an RFC 3339 timestamp with a 'Z' suffix, returning a datetime with tzinfo set to datetime.timezone.utc.

```python
>>> parse('2009-01-01T10:01:02Z')
datetime.datetime(2009, 1, 1, 10, 1, 2, tzinfo=datetime.timezone.utc)
```

--------------------------------

### pyrfc3339.utils.datetime_utcoffset(dt)

Source: https://pyrfc3339.readthedocs.io/en/latest/utils.html

Returns the UTC offset for an aware datetime.datetime in seconds. Raises an AssertionError if the datetime is naive.

```APIDOC
## pyrfc3339.utils.datetime_utcoffset(dt)

### Description
Returns the UTC offset for an aware `datetime.datetime` in seconds. Raises an `AssertionError` if the datetime is naive.

### Method
Function

### Signature
`datetime_utcoffset(dt: datetime) -> float`

### Parameters
- **dt** (_datetime.datetime_) - Required - a `datetime` instance; must be aware (that is, have a timezone attached)

### Returns
- the UTC offset of the supplied `datetime` in seconds

### Return Type
float

### Example
```python
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> z = ZoneInfo('US/Eastern')
>>> dt = datetime(2024, 11, 5, 19, 7, 6, tzinfo=z)
>>> datetime_utcoffset(dt)
-18000.0
```

### Error Handling
Raises an `AssertionError` if the datetime is naive (no timezone attached).

```python
>>> dt = datetime(2024, 11, 5, 19, 7, 6)
>>> datetime_utcoffset(dt)
Traceback (most recent call last):
...
AssertionError
```
```

--------------------------------

### Parse timestamp with timezone offset using parse()

Source: https://pyrfc3339.readthedocs.io/en/latest/parser.html

Parses an RFC 3339 timestamp with a negative offset, creating a datetime.timezone instance with the appropriate offset.

```python
>>> parse('2009-01-01T14:01:02-04:00')
datetime.datetime(2009, 1, 1, 14, 1, 2, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=72000)))
```

--------------------------------

### Parse timestamp without timezone using parse()

Source: https://pyrfc3339.readthedocs.io/en/latest/parser.html

Parses a timestamp without timezone information, returning a naive datetime (no tzinfo).

```python
>>> parse('2009-01-01T06:01:02')
datetime.datetime(2009, 1, 1, 6, 1, 2)
```

--------------------------------

### Parse invalid timestamp raises ValueError

Source: https://pyrfc3339.readthedocs.io/en/latest/parser.html

Shows that blatantly invalid input raises a ValueError, as demonstrated by an hour value of 25.

```python
>>> parse('2009-01-01T25:01:02Z')
Traceback (most recent call last):
...
ValueError: hour must be in 0..23
```
Tokens:
Raw