Rounding

Note

The API for rounding is largely inspired by that of Temporal (JavaScript)

It’s often useful to truncate or round a datetime or TimeDelta to a specific unit. For example, you might want to round a datetime to the nearest hour, or truncate it into 15-minute intervals.

The round method allows you to do this:

>>> d = PlainDateTime(2023, 12, 28, 11, 32, 8)
PlainDateTime("2023-12-28 11:32:08")
>>> d.round("hour")
PlainDateTime("2023-12-28 12:00:00")
>>> d.round("minute", increment=15, mode="ceil")
PlainDateTime("2023-12-28 11:45:00")

Modes

Different rounding modes are available. They differ on two axes:

• Whether they round towards/away from zero (trunc/expand) or up/down (ceil/floor)

• How they break ties

This results in the following modes:

Mode	Rounding direction	Tie-breaking	Examples	stdlib equivalent
ceil	up	n/a	3.1→4, -3.1→-3	ceil()
floor	down	n/a	3.1→3, -3.1→-4	floor()
trunc	towards zero	n/a	3.1→3, -3.1→-3	trunc(), int
expand	away from zero	n/a	3.1→4, -3.1→-4	n/a
half_ceil	nearest increment	up	3.5→4, -3.5→-3	n/a
half_floor	nearest increment	down	3.5→3, -3.5→-4	n/a
half_trunc	nearest increment	towards zero	3.5→3, -3.5→-3	n/a
half_expand	nearest increment	away from zero	3.5→4, -3.5→-4	n/a
half_even	nearest increment	to even	3.5→4, 4.5→4,	round()

For positive values, the behavior of ceil/floor and trunc/expand is the same. The difference is only visible for negative values.

Supported units

The unit argument allows you to specify the unit to round to. Allowed values depend on the type of the object being rounded:

Type	weeks	days	hours and smaller
TimeDelta	✅ [1]	✅ [1]	✅
ZonedDateTime,	❌	✅	✅
PlainDateTime,	❌	✅	✅
OffsetDateTime,	❌	✅	✅
Instant	❌	❌ [2]	✅

Increment

The increment argument allows you to specify the rounding increment. For example, you can round to the nearest 15 minutes by setting increment=15 and unit="minute".

There are some restrictions on the allowed increments:

• The increment must be a positive, non-zero integer.

• In case of rounding datetimes, the increment must be a divide a 24-hour day evenly. For example, you can round to the nearest 90 minutes (16 increments per day), but not to the nearest 7 seconds.

---

[1] (1,2)

This assumes days are always 24 hours long, which is not always the case in practice due to daylight saving time changes. Thus, a DaysNotAlways24HoursWarning is issued when rounding a TimeDelta to days or weeks. Suppress it with ignore_days_not_always_24h_warning if you know this is acceptable for your use case:

>>> d = TimeDelta(hours=50)
>>> with ignore_days_not_always_24h_warning():
...     d.round("day")
TimeDelta("PT48h")

[2]

This is explicitly disallowed because an Instant has no concept of days. Treating a UTC “day” as a locally meaningful concept is a common source of bugs, so it’s better to disallow it entirely. You can still round to the nearest 24 hours by setting unit="hour" and increment=24.