datedelta 1.4
Like datetime.timedelta, for date arithmetic.
License: BSD-3-Clause
Requires Python: >=3.6,<4.0

datedelta
#########

``datedelta.datedelta`` is ``datetime.timedelta`` for date arithmetic.

.. code-block:: pycon

    >>> import datetime
    >>> import datedelta

    >>> datetime.date(2025, 4, 22) + 2 * datedelta.WEEK
    datetime.date(2025, 5, 6)

    >>> datetime.date(2025, 4, 22) + 3 * datedelta.MONTH
    datetime.date(2025, 7, 22)

It accounts for oddities of the Gregorian calendar.

.. code-block:: pycon

    >>> datetime.date(2024, 2, 29) + datedelta.YEAR
    datetime.date(2025, 3, 1)

    >>> datetime.date(2024, 2, 29) + 4 * datedelta.YEAR
    datetime.date(2028, 2, 29)

It's convenient for computing yearly, monthly, or weekly subscriptions periods.

.. code-block:: pycon

    >>> start_date = datetime.date(2024, 1, 30)
    >>> for n in range(12):
    ...     print(repr(start_date + n * datedelta.MONTH))
    datetime.date(2024, 1, 30)
    datetime.date(2024, 3, 1)
    datetime.date(2024, 3, 30)
    datetime.date(2024, 4, 30)
    datetime.date(2024, 5, 30)
    datetime.date(2024, 6, 30)
    datetime.date(2024, 7, 30)
    datetime.date(2024, 8, 30)
    datetime.date(2024, 9, 30)
    datetime.date(2024, 10, 30)
    datetime.date(2024, 11, 30)
    datetime.date(2024, 12, 30)

    >>> start_date = datetime.date(2024, 1, 31)
    >>> for n in range(12):
    ...     print(repr(start_date + n * datedelta.MONTH))
    datetime.date(2024, 1, 31)
    datetime.date(2024, 3, 1)
    datetime.date(2024, 3, 31)
    datetime.date(2024, 5, 1)
    datetime.date(2024, 5, 31)
    datetime.date(2024, 7, 1)
    datetime.date(2024, 7, 31)
    datetime.date(2024, 8, 31)
    datetime.date(2024, 10, 1)
    datetime.date(2024, 10, 31)
    datetime.date(2024, 12, 1)
    datetime.date(2024, 12, 31)

It guarantees consistent results on arithmetic operations that it supports.

Behavior
========

There are two date arithmetic traps in the Gregorian calendar:

1. Leap years. Problems arise when adding years to a February 29th gives a
   result in a non-leap year.

2. Variable number of days in months. Problems arise when adding months to a
   29th, 30th or 31st gives a result in a month where that day doesn't exist.

In both cases, datedelta changes the result to the first day of the next month.

This method gives consistent results provided periods are represented by
(start date inclusive, end date exclusive) — that's [start date, end date) if
you prefer the mathematical notation. This representation of periods is akin
to 0-based indexing, which is the convention Python uses.

For example:

* If someone subscribes for a year starting on 2020-02-29 inclusive, the end
  date must be 2021-03-01 exclusive. If it was 2020-02-28 exclusive, that day
  would be missing from the subscription period.

* If someone subscribes for three months starting on 2020-03-31 inclusive, the
  end date must be 2020-07-01 exclusive. If it was 2020-06-30 exclusive, that
  day would be missing from the subscription period.

Operations are always performed on years, then months, then days. This order
usually provides the expected behavior. It also minimizes loss of precision.

Installation
============

.. code-block:: bash

    pip install datedelta

Usage
=====

The most common operations are adding a ``datedelta`` to a ``date`` and
subtracting a ``datedelta`` from a ``date``.

Basic intervals
---------------

The ``YEAR``, ``MONTH``, ``WEEK``, and ``DAY`` constants support common
calculations with little code.

.. code-block:: pycon

    >>> import datetime
    >>> import datedelta

    >>> datetime.date(2022, 1, 1) + datedelta.YEAR
    datetime.date(2023, 1, 1)

    >>> datetime.date(2023, 1, 1) - datedelta.YEAR
    datetime.date(2022, 1, 1)

    >>> datetime.date(2024, 2, 29) + datedelta.YEAR
    datetime.date(2025, 3, 1)

    >>> datetime.date(2025, 3, 1) - datedelta.YEAR
    datetime.date(2024, 3, 1)

    >>> datetime.date(2022, 1, 1) + datedelta.MONTH
    datetime.date(2022, 2, 1)

    >>> datetime.date(2022, 2, 1) - datedelta.MONTH
    datetime.date(2022, 1, 1)

    >>> datetime.date(2022, 1, 31) + datedelta.MONTH
    datetime.date(2022, 3, 1)

    >>> datetime.date(2022, 3, 1) - datedelta.MONTH
    datetime.date(2022, 2, 1)

    >>> datetime.date(2022, 1, 1) + datedelta.WEEK
    datetime.date(2022, 1, 8)

    >>> datetime.date(2022, 1, 1) - datedelta.WEEK
    datetime.date(2021, 12, 25)

    >>> datetime.date(2022, 1, 1) + datedelta.DAY
    datetime.date(2022, 1, 2)

    >>> datetime.date(2022, 1, 1) - datedelta.DAY
    datetime.date(2021, 12, 31)

``datedelta.DAY`` behaves exactly like ``datetime.timedelta(1)``. It's only
provided for consistency.

Arbitrary intervals
-------------------

``datedelta`` objects provide support for arbitrary calculations.

.. code-block:: pycon

    >>> import datetime
    >>> import datedelta

    >>> datetime.date(2022, 3, 23) + datedelta.datedelta(years=1, months=1, days=-1)
    datetime.date(2023, 4, 22)

    >>> datetime.date(2022, 3, 23) - datedelta.datedelta(years=-1, months=-1, days=1)
    datetime.date(2023, 4, 22)

    >>> datetime.date(2024, 2, 29) + datedelta.datedelta(years=2)
    datetime.date(2026, 3, 1)

    >>> datetime.date(2024, 2, 29) - datedelta.datedelta(years=2)
    datetime.date(2022, 3, 1)

    >>> datetime.date(2024, 2, 29) + datedelta.datedelta(years=2, days=-1)
    datetime.date(2026, 2, 28)

    >>> datetime.date(2024, 2, 29) - datedelta.datedelta(years=2, days=1)
    datetime.date(2022, 2, 28)

    >>> datetime.date(2024, 2, 29) + datedelta.datedelta(years=2, months=6)
    datetime.date(2026, 9, 1)

    >>> datetime.date(2024, 2, 29) - datedelta.datedelta(years=2, months=-6)
    datetime.date(2022, 9, 1)

    >>> datetime.date(2024, 2, 29) + datedelta.datedelta(years=4)
    datetime.date(2028, 2, 29)

    >>> datetime.date(2024, 2, 29) - datedelta.datedelta(years=4)
    datetime.date(2020, 2, 29)

    >>> datetime.date(2024, 2, 29) + datedelta.datedelta(years=4, days=1)
    datetime.date(2028, 3, 1)

    >>> datetime.date(2024, 2, 29) - datedelta.datedelta(years=4, days=-1)
    datetime.date(2020, 3, 1)

    >>> datetime.date(2024, 2, 29) + datedelta.datedelta(years=4, months=6)
    datetime.date(2028, 8, 29)

    >>> datetime.date(2024, 2, 29) - datedelta.datedelta(years=4, months=-6)
    datetime.date(2020, 8, 29)

These results are mathematically consistent, as explained in "Behavior" above.

Other operations
----------------

``datedelta`` instances can be added, subtracted, and multiplied with an
integer. However, there are some restrictions on addition and subtraction.

Adding then subtracting a given datedelta to a date doesn't always return the
original date. In order to prevent bugs caused by this behavior, when the result
of adding or subtracting two ``datedelta`` isn't well defined, a ``ValueError``
is raised.

.. code-block:: pycon

    >>> import datedelta

    >>> datedelta.YEAR + datedelta.YEAR
    datedelta.datedelta(years=2)

    >>> 3 * datedelta.YEAR
    datedelta.datedelta(years=3)

    >>> datedelta.YEAR - datedelta.DAY
    datedelta.datedelta(years=1, days=-1)

    >>> datedelta.YEAR - datedelta.YEAR
    Traceback (most recent call last):
        ...
    ValueError: cannot subtract datedeltas with same signs

    >>> datedelta.datedelta(months=6) + datedelta.datedelta(months=-3)
    Traceback (most recent call last):
        ...
    ValueError: cannot add datedeltas with opposite signs

Limitations
===========

Additions involving ``datedelta`` are neither associative nor commutative in
general.

Here are two examples where adding a ``datedelta`` then subtracting it doesn't
return the original value:

.. code-block:: pycon

    >>> import datetime
    >>> import datedelta

    >>> datetime.date(2024, 2, 29) + datedelta.datedelta(years=1)
    datetime.date(2025, 3, 1)

    >>> datetime.date(2025, 3, 1) - datedelta.datedelta(years=1)
    datetime.date(2024, 3, 1)

    >>> datetime.date(2024, 1, 31) + datedelta.datedelta(months=1)
    datetime.date(2024, 3, 1)

    >>> datetime.date(2024, 3, 1) - datedelta.datedelta(months=1)
    datetime.date(2024, 2, 1)

Here are two examples where adding two ``datedelta`` gives a different result
depending on the order of operations:

.. code-block:: pycon

    >>> import datetime
    >>> import datedelta

    >>> datetime.date(2024, 2, 29) + datedelta.datedelta(months=6) + datedelta.datedelta(years=1)
    datetime.date(2025, 8, 29)

    >>> datetime.date(2024, 2, 29) + datedelta.datedelta(years=1) + datedelta.datedelta(months=6)
    datetime.date(2025, 9, 1)

    >>> datetime.date(2024, 1, 31) + datedelta.datedelta(months=2) + datedelta.datedelta(months=5)
    datetime.date(2024, 8, 31)

    >>> datetime.date(2024, 1, 31) + datedelta.datedelta(months=5) + datedelta.datedelta(months=2)
    datetime.date(2024, 9, 1)

To avoid problems, you should always start from the same reference date and add
a single ``datedelta``. Don't chain additions or subtractions.

To minimize the risk of incorrect results, ``datedelta`` only implements
operations that have unambiguous semantics:

* Adding a datedelta to a date
* Subtracting a datedelta from a date
* Adding a datedelta to a datedelta when components have the same sign
* Subtracting a datedelta from a datedelta when components have opposite signs

(PEP 20 says: "In the face of ambiguity, refuse the temptation to guess.")

Alternatives
============

``datedelta.datedelta`` is smarter than ``datetime.timedelta`` because it knows
about years and months in addition to days.

Compared to ``pendulum.Duration`` or ``dateutil.relativedelta.relativedelta``,
``datedelta.datedelta`` has a few benefits:

* It handles non-existing results in a mathematically consistent fashion: it
  adjusts to the first day of the next month while pendulum and dateutil adjust
  to the last day of the current month.
* It provides an API designed to prevent programming mistakes: it requires
  keyword arguments, rejects operations expressing incorrect business logic, and
  omits error-prone features of dateutil like the "replace" behavior or explicit
  control of leap days.
* It has very small footprint, by virtue of providing of very small subset of
  the features found in pendulum or dateutil. That makes it a good choice if
  you're otherwise happy with the standard library's datetime module.

Changelog
=========

1.3
---

* Add ``WEEK`` constant.

1.2
---

* Optimize hashing and pickling.

1.1
---

* Add ``YEAR``, ``MONTH``, and ``DAY`` constants.

1.0
---

* Initial stable release.