aniso8601

library10.0.1pypypi✓ verified 25d ago

aniso8601 is a Python library designed for robust parsing of ISO 8601 strings into native Python `datetime` and `timedelta` objects. It supports durations, dates, times, and datetimes, adhering strictly to the ISO 8601 standard. The current version is 10.0.1, and it maintains an active, though irregular, release cadence.

serialization

pip install aniso8601

package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · ANISO8601

aniso8601

serializationpythonv10.0.1

Install

1.7s avg

Import

18ms

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 v10.0.1 · 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.020s · 18.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.016s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

parse_datetime

✓ from aniso8601 import parse_datetime

✗ from aniso8601.parse import parse_datetime

parse_duration

✓ from aniso8601 import parse_duration

parse_date

✓ from aniso8601 import parse_date

This quickstart demonstrates parsing ISO 8601 duration and datetime strings using `aniso8601.parse.parse_duration` and `aniso8601.parse.parse_datetime`. It also shows how to catch `ISO8601Error` for invalid inputs.

import aniso8601.parse import datetime # Parse an ISO 8601 duration string duration_str = "P3Y6M4DT12H30M5S" duration = aniso8601.parse.parse_duration(duration_str) print(f"Parsed Duration: {duration} (Type: {type(duration)})\n") # Parse an ISO 8601 datetime string with timezone datetime_str = "2023-01-15T10:00:00+01:00" dt = aniso8601.parse.parse_datetime(datetime_str) print(f"Parsed Datetime: {dt} (Type: {type(dt)}, TZ: {dt.tzinfo})\n") # Parse an ISO 8601 datetime string (UTC) utc_datetime_str = "2024-03-01T14:30:00Z" utc_dt = aniso8601.parse.parse_datetime(utc_datetime_str) print(f"Parsed UTC Datetime: {utc_dt} (Type: {type(utc_dt)}, TZ: {utc_dt.tzinfo})\n") # Handle potential parsing errors try: invalid_str = "invalid-date-string" aniso8601.parse.parse_datetime(invalid_str) except aniso8601.ISO8601Error as e: print(f"Error parsing '{invalid_str}': {e}")

Debug

Known issues

breakingStarting with v9.0.0, the return types for `parse_duration` and `parse_datetime` changed. `parse_duration` now returns `datetime.timedelta` (instead of `aniso8601.Duration`) and `parse_datetime` returns `datetime.datetime` (instead of `aniso8601.DateTime`). Code relying on the specific `aniso8601` custom objects will break.

fix

Update code to expect `datetime.timedelta` and `datetime.datetime` objects. If custom behavior was required, consider extending native types or reimplementing logic.

affects: >=9.0.0

breakingIn v10.0.0, Python 3.6 support was dropped. Additionally, the `parse_repeating_interval` function was removed entirely, and all exception classes were moved directly under the `aniso8601` package (e.g., `aniso8601.ISO8601Error` instead of `aniso8601.exceptions.ISO8601Error`).

fix

Upgrade to Python 3.7 or newer. Remove calls to `parse_repeating_interval` and implement custom logic if needed. Update exception import paths from `aniso8601.exceptions` to `aniso8601`.

affects: >=10.0.0

gotchaaniso8601 is strict about ISO 8601 compliance. It does not attempt to 'guess' or be lenient with non-standard formats. Input strings must strictly conform to the ISO 8601 specification to be parsed successfully. This can lead to unexpected `ISO8601Error` for subtly malformed strings.

fix

Ensure input strings are strictly ISO 8601 compliant. Validate inputs before passing them to aniso8601 parsing functions, or wrap calls in `try...except aniso8601.ISO8601Error` blocks.

affects: All versions

gotchaWhen parsing datetimes without an explicit timezone offset (e.g., '2023-01-15T10:00:00'), `parse_datetime` will return a naive `datetime` object (i.e., `dt.tzinfo` will be `None`). It does not assume UTC or any local timezone by default for such strings.

fix

Always provide timezone information (e.g., '2023-01-15T10:00:00Z' for UTC or '+01:00' for an offset) if you require timezone-aware datetime objects. If you receive a naive datetime, you must explicitly localize it using a library like `pytz` or `zoneinfo` (Python 3.9+).

affects: All versions

gotchaThe `aniso8601` library does not expose a submodule named `parse`. Core parsing functions (e.g., `parse_datetime`, `parse_duration`) are directly available under the `aniso8601` package. Attempting to import `aniso8601.parse` will result in a `ModuleNotFoundError`.

fix

Refactor import statements. Instead of `import aniso8601.parse` or `from aniso8601.parse import ...`, use `from aniso8601 import ...` to access parsing functions directly from the `aniso8601` package (e.g., `from aniso8601 import parse_datetime`).

affects: All versions

breakingThe `aniso8601.parse` submodule has been removed or restructured. Direct import of `aniso8601.parse` will result in a `ModuleNotFoundError`.

fix

Update import statements. Parsing functions (e.g., `parse_datetime`, `parse_duration`) should be imported directly from the top-level `aniso8601` package (e.g., `from aniso8601 import parse_datetime`).

affects: >=9.0.0

Upgrade

Version history

10.0.1latest on PyPI · released Apr 18, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

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

homepagehttps://codeberg.org/nielsenb-jf/aniso8601 ↗

docshttps://aniso8601.readthedocs.io/ ↗

changeloghttps://codeberg.org/nielsenb-jf/aniso8601/src/branch/main/CHANGELOG.rst ↗