======== ciso8601

.. image:: https://img.shields.io/pypi/v/ciso8601.svg :target: https://pypi.org/project/ciso8601/

.. image:: https://img.shields.io/pypi/pyversions/ciso8601.svg :target: https://pypi.org/project/ciso8601/

ciso8601 converts ISO 8601_ or RFC 3339_ date time strings into Python datetime objects.

Since it's written as a C module, it is much faster than other Python libraries. Tested with cPython 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14.

.. _ISO 8601: https://en.wikipedia.org/wiki/ISO_8601 .. _RFC 3339: https://tools.ietf.org/html/rfc3339

(Interested in working on projects like this? Close_ is looking for great engineers_ to join our team)

.. _Close: https://close.com .. _great engineers: https://jobs.close.com

.. contents:: Contents

Quick start

.. code:: bash

% pip install ciso8601

.. code:: python

In [1]: import ciso8601

In [2]: ciso8601.parse_datetime('2014-12-05T12:30:45.123456-05:30') Out[2]: datetime.datetime(2014, 12, 5, 12, 30, 45, 123456, tzinfo=pytz.FixedOffset(330))

In [3]: ciso8601.parse_datetime('20141205T123045') Out[3]: datetime.datetime(2014, 12, 5, 12, 30, 45)

Migration to v2

Version 2.0.0 of ciso8601 changed the core implementation. This was not entirely backwards compatible, and care should be taken when migrating See CHANGELOG_ for the Migration Guide.

.. _CHANGELOG: https://github.com/closeio/ciso8601/blob/master/CHANGELOG.md

When should I not use ciso8601?

ciso8601 is not necessarily the best solution for every use case (especially since Python 3.11). See Should I use ciso8601?_

.. _Should I use ciso8601?: https://github.com/closeio/ciso8601/blob/master/why_ciso8601.md

Error handling

Starting in v2.0.0, ciso8601 offers strong guarantees when it comes to parsing strings.

parse_datetime(dt: String): datetime is a function that takes a string and either:

• Returns a properly parsed Python datetime, if and only if the entire string conforms to the supported subset of ISO 8601
• Raises a ValueError with a description of the reason why the string doesn't conform to the supported subset of ISO 8601

If time zone information is provided, an aware datetime object will be returned. Otherwise, a naive datetime is returned.

Benchmark

Parsing a timestamp with no time zone information (e.g., 2014-01-09T21:48:00):

.. include:benchmark_with_no_time_zone.rst

.. table::

+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|             Module             |Python 3.14|Python 3.13|Python 3.12|Python 3.11|Relative slowdown (versus ciso8601, latest Python)|…|Python 3.10|Python 3.9|Python 3.8|
+================================+===========+===========+===========+===========+==================================================+=+===========+==========+==========+
|ciso8601                        |69.3 nsec  |60.4 nsec  |64.8 nsec  |59.5 nsec  |N/A                                               |…|89.4 nsec  |85.7 nsec |93.5 nsec |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|backports.datetime_fromisoformat|N/A        |N/A        |N/A        |N/A        |0.9x                                              |…|76.4 nsec  |71.6 nsec |79 nsec   |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|datetime (builtin)              |125 nsec   |123 nsec   |136 nsec   |127 nsec   |1.8x                                              |…|N/A        |N/A       |N/A       |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|udatetime                       |543 nsec   |543 nsec   |538 nsec   |520 nsec   |7.8x                                              |…|544 nsec   |544 nsec  |553 nsec  |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|python-dateutil                 |3.14 usec  |3.41 usec  |4.03 usec  |3.46 usec  |45.3x                                             |…|4.14 usec  |4.16 usec |4.22 usec |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|str2date                        |3.21 usec  |3.28 usec  |3.61 usec  |3.51 usec  |46.3x                                             |…|3.76 usec  |3.71 usec |3.91 usec |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|pendulum                        |4.19 usec  |152 nsec   |126 nsec   |136 nsec   |60.4x                                             |…|148 nsec   |145 nsec  |181 nsec  |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|iso8601utils                    |N/A        |N/A        |N/A        |N/A        |53.9x                                             |…|N/A        |4.62 usec |5.05 usec |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|iso8601                         |4.97 usec  |5.14 usec  |5.37 usec  |5.33 usec  |71.6x                                             |…|5.21 usec  |5.25 usec |5.7 usec  |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|isodate                         |5.24 usec  |5.72 usec  |5.9 usec   |5.53 usec  |75.6x                                             |…|5.61 usec  |5.81 usec |6.07 usec |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|PySO8601                        |9.56 usec  |10.2 usec  |9.53 usec  |7.99 usec  |137.9x                                            |…|9.53 usec  |9.98 usec |27.8 usec |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|aniso8601                       |12.2 usec  |12.3 usec  |12.9 usec  |11.7 usec  |175.7x                                            |…|15.5 usec  |16 usec   |15.7 usec |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|zulu                            |12.4 usec  |12.5 usec  |13.8 usec  |13.1 usec  |178.3x                                            |…|14.3 usec  |14.6 usec |14.3 usec |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|arrow                           |42.5 usec  |42.9 usec  |42.4 usec  |42.5 usec  |612.6x                                            |…|49.8 usec  |50.1 usec |49.1 usec |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|maya                            |46.6 usec  |35.4 usec  |42.5 usec  |39.1 usec  |671.5x                                            |…|44.1 usec  |44.8 usec |46.7 usec |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|metomi-isodatetime              |808 usec   |852 usec   |810 usec   |831 usec   |11647.5x                                          |…|1.1 msec   |1.09 msec |1.11 msec |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|moment                          |1.22 msec  |1.3 msec   |1.3 msec   |1.38 msec  |17631.5x                                          |…|1.36 msec  |1.4 msec  |1.39 msec |
+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+

ciso8601 takes 69.3 nsec, which is 1.8x faster than datetime (builtin), the next fastest Python 3.14 parser in this comparison.

.. </include:benchmark_with_no_time_zone.rst>

Parsing a timestamp with time zone information (e.g., 2014-01-09T21:48:00-05:30):

.. include:benchmark_with_time_zone.rst

.. table::

+--------------------------------+-----------+-----------+-----------+-----------+--------------------------------------------------+-+-----------+----------+----------+
|             Module             |Python 3.14|Python 3.13|Python 3.12|Python 3.11|Relative slowdown (versus ciso8601, latest Python)|…|Python 3.10|Python 3.9|Python 3.8|
+================================+===========+===========+===========+===========+==================================================+=+===========+==========+==========+
|ciso8601                        |71.8 nsec  |70.3 nsec  |75.1 nsec  |67.3 nsec  |N/A                                               |…|98.3 nsec  |92.9 nsec |97.8 nsec |
+------