Period.ordinal

abstractmethod Period.ordinal(datetime_obj)

Return the ordinal of the interval that contains the supplied datetime.

The ordinal identifies one interval on this period’s timeline: the one that starts at or before datetime_obj and ends before the next begins. Ordinals are consecutive integers, so the interval following ordinal n is always n + 1.

Parameters:

datetime_obj (datetime) – The datetime whose interval is wanted. Any tzinfo it carries is ignored.

Return type:

int

Returns:

An integer ordinal value

Raises:

OverflowError – If this period’s offset shifts the calculation outside the datetime range. Only reachable for a period with an offset, at the very start of the timeline.

Examples

>>> from datetime import datetime

Every datetime in March 2024 shares one ordinal …

>>> p1m = Period.of_months(1)
>>> d = datetime(2024, 3, 15, 9, 47)
>>> n = p1m.ordinal(d)
>>> n == p1m.ordinal(datetime(2024, 3, 1)) == p1m.ordinal(datetime(2024, 3, 31, 23, 59))
True

… which Period.datetime() turns back into the start of that month.

>>> p1m.datetime(n)
datetime.datetime(2024, 3, 1, 0, 0)
>>> p1m.datetime(n) <= d < p1m.datetime(n + 1)
True

Note

An ordinal only means anything to the Period that produced it. Each period numbers the timeline in its own units, and feeding one period’s ordinal to another’s datetime() gives a wrong answer rather than an error:

>>> from datetime import datetime
>>> n = Period.of_months(1).ordinal(datetime(2024, 3, 15))
>>> n
24290
>>> Period.of_days(1).datetime(n)
datetime.datetime(67, 7, 3, 0, 0)