Period.floor#

Period.floor(datetime_obj)[source]#

Return the first instant of the interval that contains the supplied datetime.

Shorthand for period.datetime(period.ordinal(datetime_obj)) - snapping a timestamp onto this period’s grid. Unlike truncating with a datetime.timedelta, it works for calendar periods and for periods carrying an offset.

Parameters:: datetime_obj (datetime) – The datetime to floor. Any tzinfo it carries is ignored, as in ordinal().
Return type:: datetime
Returns:: A datetime object marking the first instant of the interval containing datetime_obj, carrying this Period’s own tzinfo

Examples

>>> from datetime import datetime
>>> reading = datetime(2024, 3, 15, 9, 47, 30)
>>> Period.of_minutes(15).floor(reading)
datetime.datetime(2024, 3, 15, 9, 45)
>>> Period.of_months(1).floor(reading)
datetime.datetime(2024, 3, 1, 0, 0)

An offset moves every boundary, and with it what a timestamp floors to.

>>> Period.of_days(1).with_hour_offset(9).floor(datetime(2024, 3, 15, 7, 30))
datetime.datetime(2024, 3, 14, 9, 0)

A floored datetime always lands on a boundary.

>>> pt15m = Period.of_minutes(15)
>>> pt15m.is_aligned(pt15m.floor(reading))
True