{"library":"ciso8601","title":"Fast ISO8601 Datetime Parser","description":"ciso8601 is a Python library providing a highly optimized C extension for parsing ISO 8601 and RFC 3339 datetime strings into Python `datetime` objects. It is designed for maximum performance, often outperforming other Python date parsing libraries. The current version is 2.3.3, and it maintains an active release cadence with regular updates for new Python versions and bug fixes.","status":"active","version":"2.3.3","language":"en","source_language":"en","source_url":"https://github.com/closeio/ciso8601","tags":["datetime","iso8601","parsing","performance","c-extension","rfc3339"],"install":[{"cmd":"pip install ciso8601","lang":"bash","label":"Install ciso8601"}],"dependencies":[{"reason":"Required for parsing timezone-aware ISO 8601 strings in Python 2.7; not needed for Python 3.","package":"pytz","optional":true}],"imports":[{"symbol":"parse_datetime","correct":"from ciso8601 import parse_datetime"},{"note":"Use this to parse timezone-aware strings as naive datetimes, ignoring timezone information, which can be faster.","symbol":"parse_datetime_as_naive","correct":"from ciso8601 import parse_datetime_as_naive"},{"note":"For strict RFC 3339 parsing.","symbol":"parse_rfc3339","correct":"from ciso8601 import parse_rfc3339"}],"quickstart":{"code":"import ciso8601\n\n# Parse a naive datetime string\ndate_str_naive = \"2023-10-27T10:00:00\"\ndt_naive = ciso8601.parse_datetime(date_str_naive)\nprint(f\"Naive: {dt_naive} (Type: {type(dt_naive)}) (TZ: {dt_naive.tzinfo})\")\n\n# Parse a timezone-aware datetime string\ndate_str_aware = \"2023-10-27T10:00:00+01:00\"\ndt_aware = ciso8601.parse_datetime(date_str_aware)\nprint(f\"Aware: {dt_aware} (Type: {type(dt_aware)}) (TZ: {dt_aware.tzinfo})\")\n\n# Parse as naive, even if timezone is present\ndate_str_aware_to_naive = \"2023-10-27T10:00:00Z\"\ndt_forced_naive = ciso8601.parse_datetime_as_naive(date_str_aware_to_naive)\nprint(f\"Forced Naive: {dt_forced_naive} (Type: {type(dt_forced_naive)}) (TZ: {dt_forced_naive.tzinfo})\")\n\n# Strict RFC 3339 parsing\n# RFC 3339 requires a full date and time with a timezone offset or 'Z'\ntry:\n    dt_rfc3339 = ciso8601.parse_rfc3339(\"2023-10-27T10:00:00Z\")\n    print(f\"RFC3339: {dt_rfc3339} (TZ: {dt_rfc3339.tzinfo})\")\n    ciso8601.parse_rfc3339(\"2023-10-27\") # This will raise ValueError\nexcept ValueError as e:\n    print(f\"Error parsing non-RFC3339 string with parse_rfc3339: {e}\")","lang":"python","description":"This quickstart demonstrates basic parsing of ISO 8601 strings, including naive and timezone-aware datetimes. It also shows how to explicitly parse as naive, ignoring timezone information, and how to use the strict RFC 3339 parser."},"warnings":[{"fix":"Review the official `CHANGELOG` on GitHub for specific migration steps. Test thoroughly when upgrading.","message":"Version 2.0.0 introduced significant changes to the core implementation that were not entirely backwards compatible. Users upgrading from pre-2.0.0 versions should consult the `CHANGELOG` for migration guidance.","severity":"breaking","affected_versions":"<2.0.0 to 2.x.x"},{"fix":"Remove any arguments passed to `FixedOffset.dst()`, `FixedOffset.tzname()`, or `FixedOffset.utcoffset()` calls. These methods should now be called without arguments.","message":"In v2.3.0, the `FixedOffset`'s `dst`, `tzname`, and `utcoffset` methods no longer accept arguments, removing an improper ability that existed in previous versions.","severity":"breaking","affected_versions":"<2.3.0"},{"fix":"Upgrade to ciso8601 version 2.3.3 or newer to resolve the memory leak.","message":"Versions prior to 2.3.3 contained a memory leak in the `FixedOffset_fromutc` function, particularly when dealing with timezone-aware datetimes.","severity":"gotcha","affected_versions":"<2.3.3"},{"fix":"Ensure input strings conform to the supported subset of ISO 8601 as detailed in the project's documentation. If broader ISO 8601 parsing is required, consider `dateutil.parser.isoparse` or Python 3.11+'s `datetime.fromisoformat`.","message":"ciso8601 only supports a common subset of the ISO 8601 specification. For example, it only supports the HYPHEN-MINUS (`-`) character for timezone separators, not MINUS SIGN (`−`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install the necessary build tools and Python development headers for your operating system. For Windows, install 'Build Tools for Visual Studio'.","message":"When installing ciso8601 on systems without pre-built wheels, compilation from source is required. This necessitates having a C compiler (e.g., GCC on Linux, MSVC on Windows) and Python development headers (e.g., `python3-dev` on Debian/Ubuntu) installed.","severity":"gotcha","affected_versions":"All versions (when installing from source)"},{"fix":"Benchmark `ciso8601.parse_datetime` against `datetime.fromisoformat` for your specific use case on Python 3.11+ to determine if `ciso8601` offers a sufficient performance advantage.","message":"For Python 3.11 and newer, the standard library's `datetime.fromisoformat` offers highly performant ISO 8601 parsing. While `ciso8601` still aims to be faster, the performance difference may not be significant enough to warrant an external dependency for all use cases, especially if `datetime.fromisoformat` meets requirements.","severity":"gotcha","affected_versions":"All versions, especially when using Python >= 3.11"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}