iso8601

library2.1.0pypypi✓ verified 24d ago

This module parses the most common forms of ISO 8601 date strings (e.g., 2007-01-14T20:34:22+00:00) into `datetime` objects. It simplifies the process of converting various ISO 8601 date and time formats into Python's native `datetime` types. The library is actively maintained, with a typical release cadence of a few minor/patch versions per year, ensuring compatibility and bug fixes.

serialization

pip install iso8601

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · ISO8601

iso8601

serializationpythonv2.1.0

Install

1.6s avg

Import

20ms

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 v2.1.0 · 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.022s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.018s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

parse_date

✓ import iso8601 datetime_obj = iso8601.parse_date('2007-01-25T12:00:00Z')

The primary function `parse_date` is directly accessible after importing the module.

The `parse_date` function is the main entry point for parsing ISO 8601 strings. It automatically handles various common formats including full datetimes with and without timezones, and date-only strings. By default, missing timezone information will result in a UTC-aware datetime object unless a `default_timezone` is specified or set to `None` for naive datetimes.

import iso8601 from datetime import datetime, timezone # Parse a full ISO 8601 datetime string with UTC timezone datetime_str_utc = '2023-10-27T10:00:00Z' datetime_obj_utc = iso8601.parse_date(datetime_str_utc) print(f"Parsed UTC: {datetime_obj_utc}") assert datetime_obj_utc == datetime(2023, 10, 27, 10, 0, tzinfo=timezone.utc) # Parse a datetime string with an offset timezone datetime_str_offset = '2023-10-27T10:00:00-05:00' datetime_obj_offset = iso8601.parse_date(datetime_str_offset) print(f"Parsed Offset: {datetime_obj_offset}") # Parse a date-only string (time defaults to 00:00:00 UTC) date_str = '2023-10-27' datetime_obj_date_only = iso8601.parse_date(date_str) print(f"Parsed Date Only: {datetime_obj_date_only}") assert datetime_obj_date_only == datetime(2023, 10, 27, 0, 0, tzinfo=iso8601.UTC) # Parse a date with a space separator instead of 'T' datetime_str_space = '2023-10-27 10:00:00+01:00' datetime_obj_space = iso8601.parse_date(datetime_str_space) print(f"Parsed with Space: {datetime_obj_space}")

Debug

Known issues

breakingVersion 2.0.0 dropped support for Python 3.6. Users on Python 3.6 must remain on `iso8601<2.0.0`.

fix

Upgrade to Python 3.7 or newer, or pin `iso8601` to `<2.0.0`.

affects: >=2.0.0

breakingVersion 1.0.0 dropped support for Python 2.x and required Python 3.6 or newer.

fix

Upgrade to Python 3.6 or newer, or pin `iso8601` to `<1.0.0` for Python 2.x environments.

affects: >=1.0.0

gotchaThe library deviates from the strict ISO 8601 specification by allowing a space character (' ') instead of 'T' as a date-time separator and parsing single-digit days/months without leading zeros (e.g., 'YYYY-M-D').

fix

Be aware that `iso8601` is more permissive than strict ISO 8601. If strict adherence is critical, pre-validation might be necessary or consider `datetime.fromisoformat` (Python 3.7+) for stricter parsing of common formats.

affects: All versions

gotchaPrior to version 0.1.8, if a date string included 'Z' (indicating UTC), the `default_timezone` parameter might have incorrectly overridden it. From 0.1.8 onwards, 'Z' correctly implies UTC and takes precedence. This was a fix but could be a breaking change if relying on the previous incorrect behavior.

fix

Ensure your code explicitly handles 'Z' for UTC or upgrade to >=0.1.8 for correct behavior.

affects: <0.1.8

gotchaIf no timezone information is provided in the string, `iso8601` defaults to UTC. If you need naive `datetime` objects for strings without explicit timezone, you must pass `default_timezone=None` to `parse_date`.

fix

Use `iso8601.parse_date(datestring, default_timezone=None)` to get a naive `datetime` object for strings lacking timezone information.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'iso8601'

The 'iso8601' package has not been installed in the current Python environment.

fix

pip install iso8601

AttributeError: module 'iso8601' has no attribute 'parse'

The user is attempting to call a method named 'parse' which does not exist directly on the 'iso8601' module; the primary function for parsing ISO 8601 date strings is 'parse_date'.

fix

Use `iso8601.parse_date()` instead of `iso8601.parse()`.

ValueError: Invalid format

The input string provided to `iso8601.parse_date()` does not conform to a recognizable ISO 8601 date format, or contains invalid date/time components (e.g., an invalid month or day).

fix

Ensure the input string strictly adheres to a valid ISO 8601 format supported by the library, or use a more flexible parsing library like `python-dateutil` for highly variable inputs.

Upgrade

Version history

2.1.0latest on PyPI · released Oct 3, 2023

Audit

Dependencies

pythonrequiredRequires Python 3.7 or higher.

Agent activity

18 hits · last 30 days

node

Resources

githubhttps://github.com/micktwomey/pyiso8601 ↗

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

docshttps://pyiso8601.readthedocs.io/en/latest/ ↗