Metadata-Version: 2.1
Name: timedelta-isoformat
Version: 0.6.2.12
Summary: Supplemental ISO8601 duration format support for datetime.timedelta
Author-email: James Addison <jay@jp-hosting.net>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://pypi.org/project/timedelta-isoformat/
Project-URL: Source, https://github.com/jayaddison/timedelta-isoformat.git/
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE

timedelta-isoformat
===================

The `timedelta-isoformat <https://pypi.org/project/timedelta-isoformat/>`_ library provides supplemental `ISO 8601 duration <https://en.wikipedia.org/wiki/ISO_8601#Durations>`_ support to the `datetime.timedelta <https://docs.python.org/3/library/datetime.html#datetime.timedelta>`_ class.

The library is pure-Python, and does not depend upon regular expressions.

Functionality is provided in a subclass of ``datetime.timedelta`` that implements additional ``isoformat()`` and ``fromisoformat(duration_string)`` methods.

Usage
-----

.. code-block:: pycon

   >>> from timedelta_isoformat import timedelta
   >>> from datetime import datetime
   >>>
   >>> first = datetime(year=2022, month=10, day=2)
   >>> second = datetime(year=2022, month=11, day=27, hour=14)
   >>>
   >>> td = timedelta(seconds=(second - first).total_seconds())
   >>> td.isoformat()
   'PT1358H'
   >>>
   >>> first + timedelta.fromisoformat('PT1358H')
   datetime.datetime(2022, 11, 27, 14, 0)

Design decisions
----------------

A variety of ISO 8601 duration parsers exist across a range of programming languages, and many of them have made slightly different design decisions.

Some of the significant design decisions made within this library are:

* Values in parsed duration strings must be zero-or-greater (``PT1H`` is considered valid; ``P-2D`` is not)
* Empty time segments at the end of duration strings are allowed (``P1DT`` is considered valid)
* Measurement limits are checked within date/time segments (``PT20:59:01`` is within limits; ``PT20:60:01`` is not)
* Measurement values are parsed into floating-point values (at the time of writing, precise procedural algorithms to parse base-ten strings into integers for large inputs are not practical -- or not widely known)
* When inputs are reliably known to be of correct type and format, assertions should be safe to remove (for example, by including the `-O command-line flag when invoking the Python interpreter <https://docs.python.org/3/using/cmdline.html#cmdoption-O>`_) to improve runtime performance
