Backport of datetime.fromisoformat

2.0.3 · active · verified Thu Apr 09

This library provides a backport of Python 3.11's extended `datetime.fromisoformat` functionality to older Python versions (prior to 3.11). It allows parsing a wider range of ISO 8601 formatted strings, including those with timezone offsets using colons and fractional seconds. The current version is 2.0.3, with releases occurring on an as-needed basis to address compatibility or new Python version changes.

Warnings

gotcha This library relies on monkey-patching. The `datetime.fromisoformat` method will only be extended if `backports.datetime_fromisoformat` is imported *after* the `datetime` module.
Fix: Always ensure `import datetime` appears before `import backports.datetime_fromisoformat` in your code.
breaking Version 2.0.0 changed the underlying logic for the backported `fromisoformat` methods. Prior to 2.0.0, it backported Python 3.7's logic; from 2.0.0 onwards, it backports Python 3.11's logic, supporting a wider range of ISO 8601 formats.
Fix: Applications migrating from 1.x.x to 2.x.x should be aware that `fromisoformat` will now accept more varied ISO 8601 strings. This is generally an improvement, but verify if any strict parsing assumptions were made based on older 3.7 behavior.
gotcha This library is designed for Python versions older than 3.11. Installing and importing it on Python 3.11 or newer has no effect on `datetime.fromisoformat` and adds unnecessary overhead.
Fix: Conditionally install the package using environment markers in your `pyproject.toml` or `requirements.txt`: `backports-datetime-fromisoformat; python_version < '3.11'`.

Install

pip install "backports-datetime-fromisoformat; python_version < '3.11'" Conditional install for Python < 3.11
pip install backports-datetime-fromisoformat Unconditional install

Imports

datetime.fromisoformat
```
import datetime
import backports.datetime_fromisoformat
```
This library monkey-patches the built-in `datetime.datetime` and `datetime.date` objects. You must import `datetime` first, then `backports.datetime_fromisoformat` to apply the patch. It does not expose `fromisoformat` directly from its own namespace.

Quickstart

This example demonstrates how to use the backported `fromisoformat` method. By importing `backports.datetime_fromisoformat` after `datetime`, it monkey-patches the standard library's `datetime` objects to accept ISO 8601 strings that conform to Python 3.11's broader parsing capabilities, such as timezone offsets with colons.

import datetime
import backports.datetime_fromisoformat

# This string would fail on Python < 3.11 without the backport due to the colon in the timezone offset
isodate_str = "2023-10-27T10:00:00.123456+05:30"

try:
    dt_object = datetime.datetime.fromisoformat(isodate_str)
    print(f"Successfully parsed: {dt_object}")
    print(f"Type: {type(dt_object)}")
except ValueError as e:
    print(f"Error parsing date: {e}")

view raw JSON →