{"library":"iso8601","title":"Simple module to parse ISO 8601 dates","description":"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.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/micktwomey/pyiso8601","tags":["date parsing","ISO 8601","datetime","timezone","utility"],"install":[{"cmd":"pip install iso8601","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.7 or higher.","package":"python","optional":false}],"imports":[{"note":"The primary function `parse_date` is directly accessible after importing the module.","symbol":"parse_date","correct":"import iso8601\ndatetime_obj = iso8601.parse_date('2007-01-25T12:00:00Z')"}],"quickstart":{"code":"import iso8601\nfrom datetime import datetime, timezone\n\n# Parse a full ISO 8601 datetime string with UTC timezone\ndatetime_str_utc = '2023-10-27T10:00:00Z'\ndatetime_obj_utc = iso8601.parse_date(datetime_str_utc)\nprint(f\"Parsed UTC: {datetime_obj_utc}\")\nassert datetime_obj_utc == datetime(2023, 10, 27, 10, 0, tzinfo=timezone.utc)\n\n# Parse a datetime string with an offset timezone\ndatetime_str_offset = '2023-10-27T10:00:00-05:00'\ndatetime_obj_offset = iso8601.parse_date(datetime_str_offset)\nprint(f\"Parsed Offset: {datetime_obj_offset}\")\n\n# Parse a date-only string (time defaults to 00:00:00 UTC)\ndate_str = '2023-10-27'\ndatetime_obj_date_only = iso8601.parse_date(date_str)\nprint(f\"Parsed Date Only: {datetime_obj_date_only}\")\nassert datetime_obj_date_only == datetime(2023, 10, 27, 0, 0, tzinfo=iso8601.UTC)\n\n# Parse a date with a space separator instead of 'T'\ndatetime_str_space = '2023-10-27 10:00:00+01:00'\ndatetime_obj_space = iso8601.parse_date(datetime_str_space)\nprint(f\"Parsed with Space: {datetime_obj_space}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.7 or newer, or pin `iso8601` to `<2.0.0`.","message":"Version 2.0.0 dropped support for Python 3.6. Users on Python 3.6 must remain on `iso8601<2.0.0`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade to Python 3.6 or newer, or pin `iso8601` to `<1.0.0` for Python 2.x environments.","message":"Version 1.0.0 dropped support for Python 2.x and required Python 3.6 or newer.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"The 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').","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your code explicitly handles 'Z' for UTC or upgrade to >=0.1.8 for correct behavior.","message":"Prior 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.","severity":"gotcha","affected_versions":"<0.1.8"},{"fix":"Use `iso8601.parse_date(datestring, default_timezone=None)` to get a naive `datetime` object for strings lacking timezone information.","message":"If 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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}