{"id":1230,"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":"python","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"},{"fix":"Ensure input strings to `ciso8601.parse_rfc3339` always include a time component and timezone offset. If you need to parse date-only ISO 8601 strings, use `ciso8601.parse_datetime` instead.","message":"The `ciso8601.parse_rfc3339` function strictly adheres to the RFC 3339 specification, requiring both date and time components in the input string. Date-only strings, while valid ISO 8601, will raise an error (e.g., 'Time is mandatory in RFC 3339 format') because they do not conform to RFC 3339. For more flexible parsing that supports date-only ISO 8601 strings, use `ciso8601.parse_datetime`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'2.3.3':46 '3339':22 '8601':19 'activ':51 'bug':62 'c':14,69 'c-extens':68 'cadenc':53 'ciso8601':5 'current':43 'date':39 'datetim':3,23,27,64 'design':31 'extens':15,70 'fast':1 'fix':63 'high':12 'iso':18 'iso8601':2,65 'librari':9,41 'maintain':49 'maximum':33 'new':58 'object':28 'often':35 'optim':13 'outperform':36 'pars':17,40,66 'parser':4 'perform':34,67 'provid':10 'python':8,26,38,59 'regular':55 'releas':52 'rfc':21 'rfc3339':71 'string':24 'updat':56 'version':44,60","created_at":"2026-04-06T16:55:37.002642+00:00","updated_at":"2026-04-16T02:12:44.963917+00:00","problems":[{"fix":"On Windows, ensure you have Microsoft Visual C++ 14.0 or greater installed (usually via 'Build Tools for Visual Studio'). On Linux, install Python development headers (e.g., `sudo apt-get install python3-dev` or `sudo yum install python3-devel`) and a C compiler (e.g., `sudo apt-get install build-essential` or `sudo yum install gcc`). For macOS, ensure Xcode Command Line Tools are installed (`xcode-select --install`).","cause":"This error occurs during installation when pip attempts to build the C extension for ciso8601 but fails due to missing compilation tools or development headers specific to your operating system or Python installation.","error":"ERROR: Failed building wheel for ciso8601"},{"fix":"Install the library using pip: `pip install ciso8601`. If it was installed but still not found, check that your Python interpreter and environment variables are correctly configured to point to the location where the package was installed, or try reactivating your virtual environment.","cause":"This means the ciso8601 library is not installed in the Python environment you are currently using, or its installation failed previously.","error":"ModuleNotFoundError: No module named 'ciso8601'"},{"fix":"Ensure the input string strictly adheres to the ISO 8601 or RFC 3339 standard formats supported by ciso8601. Review the ciso8601 documentation for supported date, time, and timezone formats. For example, '2014-12-05T12:30:45.123456Z' or '2014-12-05T12:30:45+05:30' are typically valid.","cause":"ciso8601's `parse_datetime` function was called with a string that does not conform to the supported subset of ISO 8601 or RFC 3339 formats, or is malformed.","error":"ValueError: Invalid ISO 8601 date time string"},{"fix":"If working in a Python 2 environment and needing to parse timezone-aware strings, install the `pytz` library: `pip install pytz`. For Python 3, this dependency is not needed.","cause":"This specific error occurs in Python 2 environments when attempting to parse a timezone-aware ISO 8601 string using `ciso8601` without the `pytz` library installed. In Python 3, `pytz` is not required for this purpose as `ciso8601` utilizes the built-in `datetime.timezone` class.","error":"ImportError: Cannot parse a timestamp with time zone information without the pytz dependency."}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.3.3","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/closeio/ciso8601","docs":null,"changelog":null,"pypi":"https://pypi.org/project/ciso8601/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}