isochron

A modern, fully-typed ISO 8601 date/time/duration/interval parser and formatter for Python. Drop-in replacement for isodate.

Why isochron?

isodate has 129M+ downloads/month but suffers from single-maintainer risk, sporadic maintenance, and 28 open bugs. isochron fixes all known isodate bugs, adds interval/recurring interval support, and provides strict type annotations.

Installation

pip install isochron

Quick Start

import datetime
from isochron import (
    parse_date, parse_time, parse_datetime, parse_duration,
    format_datetime, Duration, UTC
)

# Parse dates (calendar, ordinal, week formats)
parse_date("2026-03-13")        # datetime.date(2026, 3, 13)
parse_date("2026-072")          # ordinal -> datetime.date(2026, 3, 13)
parse_date("2026-W11-5")        # week date -> datetime.date(2026, 3, 13)

# Parse times (with timezone support)
parse_time("14:30:00Z")         # datetime.time(14, 30, tzinfo=UTC)
parse_time("24:00:00")          # midnight -> datetime.time(0, 0)  (isodate #85 fix)

# Parse datetimes
parse_datetime("2026-03-13T14:30:00+01:00")

# Parse durations
dur = parse_duration("P1Y2M3DT4H5M6S")  # -> Duration(years=1, months=2, ...)
dur.total_seconds(reference=datetime.date(2026, 1, 1))  # requires ref (isodate #95 fix)

# Format with UTC -> Z suffix (isodate #89 fix)
format_datetime(datetime.datetime(2026, 3, 13, 14, 30, tzinfo=UTC))
# -> "2026-03-13T14:30:00Z"

# Duration arithmetic
Duration(months=1) + datetime.date(2026, 1, 31)  # -> datetime.date(2026, 2, 28)

Intervals and Recurring Intervals

from isochron import parse_interval, parse_recurring

# Start/end, start/duration, duration/end
iv = parse_interval("2026-01-01/P1M")

# Recurring intervals with iteration
for dt in parse_recurring("R3/2026-01-01/P1M"):
    print(dt)  # 2026-01-01, 2026-02-01, 2026-03-01

Migrating from isodate

# Before:
from isodate import parse_date, parse_datetime, ISO8601Error, Duration

# After (option 1 - direct):
from isochron import parse_date, parse_datetime, ParseError, Duration

# After (option 2 - compat shim):
from isochron.compat import parse_date, parse_datetime, ISO8601Error, Duration

The isochron.compat module maps all isodate public names to their isochron equivalents.

API Reference

Parsing

Formatting

Types

• Duration -- Immutable, hashable dataclass with years, months, days, seconds, microseconds. Supports arithmetic with dates, datetimes, and timedeltas.
• Interval -- Frozen dataclass with start, end, duration.
• RecurringInterval -- Iterable frozen dataclass with recurrences and interval.
• UTC -- Alias for datetime.timezone.utc.
• FixedOffset(offset_minutes) -- Fixed UTC-offset tzinfo subclass.

Exceptions

• ISO8601Error -- Base exception for all isochron errors.
• ParseError -- Raised when input cannot be parsed. Has optional string and position attributes.
• FormatError -- Raised when a value cannot be formatted to ISO 8601.

strftime Format Codes

strftime(dt, fmt) supports all standard Python % directives plus these ISO 8601 extras:

isodate Bugs Fixed

License

BSD-3-Clause