aniso8601 Library

Common errors

• ModuleNotFoundError: No module named 'aniso8601'

  cause The 'aniso8601' library is not installed in the current Python environment.
  fix Install the library using pip: 'pip install aniso8601'.

• ImportError: No module named aniso8601

  cause The 'aniso8601' module is not found, possibly due to it not being installed or the virtual environment not being activated.
  fix Ensure the virtual environment is activated and install the module with 'pip install aniso8601'.

• aniso8601.exceptions.LeapSecondError: Leap seconds are not supported.

  cause The 'aniso8601' library does not support parsing ISO 8601 strings that include leap seconds.
  fix Avoid parsing datetime strings that include leap seconds, as they are not supported by 'aniso8601'.

• ValueError: Fractional months and years are not defined for relative intervals.

  cause Attempting to parse a duration with 'relative=True' that includes fractional months or years, which is not supported.
  fix Ensure that durations with 'relative=True' do not include fractional months or years.

• RuntimeError: dateutil must be installed for relative duration support.

  cause The 'python-dateutil' library is required for parsing relative durations but is not installed.
  fix Install the 'python-dateutil' library using pip: 'pip install python-dateutil'.

Warnings

• breaking Starting 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.
• breaking In 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`.
• gotcha aniso8601 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.
• gotcha When 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+).
• gotcha The `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`).
• breaking The `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`).

Install

• pip install aniso8601 Install aniso8601

Imports

• parse_datetime

  from aniso8601.parse import parse_datetime

• parse_date

  from aniso8601.parse import parse_date

• parse_time

  from aniso8601.parse import parse_time

• parse_duration

  from aniso8601.parse import parse_duration

• ISO8601Error
  wrong:

  from aniso8601.exceptions import ISO8601Error

  correct:

  from aniso8601 import ISO8601Error

  Exceptions were moved directly under the aniso8601 package in v10.0.0.

Quickstart

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}")