Rounding and boundaries

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")

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

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, -3.5→-4

round()

For positive values, the behavior of ceil is identical to expand and the behavior of floor is identical to trunc. The difference is only visible for negative values. A datetime, a Time, and an Instant count as positive, also before 1970, so only a TimeDelta shows the difference between trunc and floor.

The default mode is half_even, and the default unit is "second", so round() with no arguments does what Python’s own round() does. The delta methods in_units(), since(), and until() default to "trunc" instead: a difference in whole units is counted, not rounded, so since() says how many whole hours have passed, as a clock would.

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]

✅

Time

❌

❌

✅ [3]

A TimeDelta can be passed as the unit itself, on every type that has round():

>>> d.round(TimeDelta(minutes=15))
PlainDateTime("2023-12-28 11:30:00")

Such a unit must divide a 24-hour day evenly everywhere except on TimeDelta.round(), where it may be any positive delta. It cannot be combined with increment=. It never emits DaysAssumed24HoursWarning, since a delta claims no calendar, while the named "day" and "week" units do. Suppress that warning by passing days_assumed_24h_ok=True if you know the assumption is acceptable for your use case:

>>> d = TimeDelta(hours=50)
>>> d.round("day", days_assumed_24h_ok=True)
TimeDelta("PT48h")

Instant.round("day") is rejected: an Instant has no calendar, so a day has no midnight to start at. To round to periods of exactly 24 hours, pass "hour" with increment=24, or hours(24). As with every increment on an Instant, the periods are counted from midnight UTC, not from the epoch.

Increment

The increment argument sets the rounding increment: the step the value is rounded to, as a count of the unit. For example, you can round to the nearest 15 minutes by setting increment=15 and unit="minute".

Increments are counted from midnight (UTC for an Instant), so half_even breaks a tie toward the even multiple counted from there. Time(1, 30).round("minute", increment=20, mode="half_even") is 01:20: 90 minutes is 4.5 increments, and 4 is even. Temporal counts within the hour on its local types, and gives 01:40.

There are some restrictions on the allowed increments:

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

  • On a datetime, a Time, or an Instant, the increment must 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. TimeDelta.round() has no such rule.

In in_units(), since(), and until(), round_increment= applies to the smallest component, and the half_* modes measure nearness to that component’s multiples before any carry: 5 hours 59 minutes in hours and minutes with round_increment=7 and round_mode="half_expand" is PT5h56m (3 minutes away), not the carried PT6h0m (1 minute away).

Boundaries

Where round() moves a value to the nearest increment of a unit, start_of() and end_of() move it to the edges of the unit it lies in. They exist on Date, PlainDateTime, OffsetDateTime, and ZonedDateTime:

>>> d = PlainDateTime(2023, 12, 28, 11, 32, 8)
>>> d.start_of("month")
PlainDateTime("2023-12-01 00:00:00")
>>> d.end_of("hour")
PlainDateTime("2023-12-28 11:59:59.999999999")
>>> Date(2023, 12, 28).start_of("week_mon")
Date("2023-12-25")

The units are "year", "month", "week_mon", "week_sun", "day", "hour", "minute", and "second"; a Date takes the first four. A week can start on Monday (ISO) or on Sunday, so the unit says which: a bare "week" is rejected. start_of() on "day" or a smaller unit is round() with mode="floor", and Date has no round(), since it has nothing below a day to round.

end_of() returns the last nanosecond of the unit, so that the end_of() of one unit is one nanosecond before the start_of() of the next.

A ZonedDateTime day is not always 24 hours long. day_length() gives the difference between consecutive day starts:

>>> ZonedDateTime(2023, 3, 26, 12, tz="Europe/Amsterdam").day_length()
TimeDelta("PT23h")
>>> ZonedDateTime(2023, 10, 29, 12, tz="Europe/Amsterdam").day_length()
TimeDelta("PT25h")

For values near a time zone transition, see the start_of() and end_of() docstrings.

On an OffsetDateTime, round(), start_of(), and end_of() keep the offset, which may be stale at the new time, so they emit StaleOffsetWarning; pass stale_offset_ok=True to accept it. To stay correct across transitions, round a ZonedDateTime instead.