DEV Community

fulfillmentyx
fulfillmentyx

Posted on Edited on

Selecting a warehouse date boundary in a local time-zone test

By YX Fulfillment

At 16:20 UTC it is already the next day in Shanghai. In Los Angeles it is still the same day. Group the event by the date printed on the UTC timestamp and the Shanghai report credits it to the wrong day.

Define the report day in an IANA time zone and store the source as an offset-aware instant. For a range query, construct the local start of the day and the local start of the next day, then convert both to UTC. The sample uses synthetic instants and a half-open interval.

from datetime import datetime, time, timedelta, timezone
from zoneinfo import ZoneInfo

UTC = timezone.utc

def belongs(instant, start, stop):
    return start <= instant < stop

event = datetime(2026, 5, 12, 16, 20, tzinfo=UTC)
for name, expected_day in (
    ("Asia/Shanghai", "2026-05-13"),
    ("America/Los_Angeles", "2026-05-12"),
):
    zone = ZoneInfo(name)
    local = event.astimezone(zone)
    day = local.date()
    start = datetime.combine(day, time.min, zone).astimezone(UTC)
    stop = datetime.combine(day + timedelta(days=1), time.min, zone).astimezone(UTC)
    assert day.isoformat() == expected_day
    assert belongs(event, start, stop)
    assert belongs(start, start, stop)
    assert not belongs(stop, start, stop)
    print(name, local.isoformat(), "report day:", day)
    print("UTC query interval:", start.isoformat(), "to", stop.isoformat())
print("Source instant:", event.isoformat())
Enter fullscreen mode Exit fullscreen mode

Output from a local run on Python 3.9.6

Asia/Shanghai 2026-05-13T00:20:00+08:00 report day: 2026-05-13
UTC query interval: 2026-05-12T16:00:00+00:00 to 2026-05-13T16:00:00+00:00
America/Los_Angeles 2026-05-12T09:20:00-07:00 report day: 2026-05-12
UTC query interval: 2026-05-12T07:00:00+00:00 to 2026-05-13T07:00:00+00:00
Source instant: 2026-05-12T16:20:00+00:00
Enter fullscreen mode Exit fullscreen mode

Each report assigns the event to the day its own staff see on the clock, while both can link back to the same UTC instant for reconciliation. The exclusive end ensures an event exactly at the next boundary belongs only to the next day. Use matching comparisons in the database, typically greater than or equal to start and strictly less than stop.

A local day can span 23 or 25 UTC hours during a daylight-saving transition. Building the next local midnight is safer than adding 24 UTC hours to the first. For a shift-based report, replace midnight with the documented shift cutoff. Where a cutoff can be ambiguous or nonexistent under daylight-saving rules, settle that policy separately and add specific test dates.

Top comments (0)