iso8601

iso8601 is a small, focused Python module that parses the most common forms of ISO 8601 date and time strings (for example, 2007-01-14T20:34:22+00:00) into standard library datetime.datetime objects. It handles full timestamps, date-only values, fractional seconds, and a wide range of timezone notations, with no third-party dependencies.

With a single public function, parse_date, plus a lightweight is_iso8601 validity check, the library aims to do one thing well. It is a pragmatic choice for reading timestamps from APIs, logs, and data files where you need a dependable datetime without pulling in a larger date/time toolkit.

What You Get

• A single parse_date(datestring, default_timezone=UTC) function that returns a timezone-aware datetime.datetime
• An is_iso8601 helper for quickly checking whether a string looks like a valid ISO 8601 value
• A ParseError exception (a ValueError subclass) raised with a clear message when input cannot be parsed
• Configurable default-timezone handling, including passing None to get naive datetime objects
• Zero runtime dependencies and inline type hints via a bundled py.typed marker

Common Use Cases

• Parsing ISO 8601 timestamps returned from REST and GraphQL APIs into datetime objects
• Reading timestamp fields from CSV, JSON, or log files during ingestion or ETL work
• Normalizing user- or system-supplied date strings before storage or comparison
• Validating that incoming strings conform to an ISO 8601 shape before further processing

Under The Hood

Architecture - The entire library lives in iso8601/iso8601.py (~162 lines) and is re-exported through iso8601/init.py. Parsing is driven by a single verbose compiled regular expression (ISO8601_REGEX) whose named groups capture year, month, day, hour, minute, second, fractional seconds, and timezone components. parse_date matches the string, drops None groups, and constructs a datetime.datetime, delegating timezone resolution to parse_timezone, which maps Z to UTC, builds a FixedOffset for signed offsets, and falls back to a caller-supplied default timezone. A companion is_iso8601 reuses the same regex for a boolean validity check.

Tech Stack - Pure Python targeting >=3.7,<4.0 with no runtime dependencies, relying only on the standard library (datetime, re, decimal, typing). Packaging is handled by Poetry with poetry-core as the build backend (pyproject.toml). Development tooling includes pytest and hypothesis for testing, mypy and ruff for static analysis, Sphinx for docs, and a Nix/devenv plus justfile setup for reproducible environments.

Code Quality - The code is compact, fully type-annotated, and ships a py.typed marker for downstream type checking. Errors are funneled into a single ParseError (a ValueError subclass) with descriptive messages. Tests live in iso8601/test_iso8601.py (~282 lines) and use pytest with hypothesis property-based testing, giving strong coverage for such a small surface. The main trade-off is the reliance on one dense regex, which is powerful but harder to read than a hand-written parser.

API Design - The public surface is intentionally minimal: parse_date, is_iso8601, ParseError, UTC, and FixedOffset. parse_date(datestring, default_timezone=UTC) requires essentially no boilerplate and reads naturally, with the default-timezone parameter offering a clean escape hatch for naive datetimes. Documentation is available via a README and Read the Docs, and the narrow scope keeps the learning curve very low.