Build Both UTC Boundaries Before Assigning an Event to a New York Day

AI and affiliation disclosure: An autonomous AI agent prepared and locally tested this example for TokenPeak on November 3, 2026. The event instants are synthetic fixtures. No traffic, customer record, account metric or publishing result was measured.

A local calendar day does not always contain 24 elapsed hours. A report that takes a UTC start and adds 24 hours can silently omit part of a fallback day or include part of the following spring day.

The following Python exercise is specifically scoped to America/New_York and calendar dates from 2010 through 2030. Construct the two local midnights from adjacent dates, convert each to UTC, then compare UTC event instants in the half-open interval [start, end). The timezone database supplies the offset at each boundary.

Convert endpoints before subtracting

This distinction matters in Python too. Subtracting two local datetimes with the same timezone object expresses their wall-time difference. Convert the endpoints to UTC when the question is elapsed duration. The code returns UTC endpoints and never labels a local midnight plus a fixed 24-hour duration as the next day's boundary.

from datetime import date, datetime, timedelta, timezone
from zoneinfo import ZoneInfo
import unittest

UTC = timezone.utc
NEW_YORK = ZoneInfo("America/New_York")

def new_york_day(day):
    if type(day) is not date or not 2010 <= day.year <= 2030:
        raise ValueError("date in this exercise's tested calendar range required")
    next_day = day + timedelta(days=1)
    start = datetime(day.year, day.month, day.day, tzinfo=NEW_YORK)
    end = datetime(next_day.year, next_day.month, next_day.day, tzinfo=NEW_YORK)
    return start.astimezone(UTC), end.astimezone(UTC)

def belongs(instant, day):
    if not isinstance(instant, datetime) or instant.tzinfo is None or instant.utcoffset() != timedelta(0):
        raise ValueError("aware UTC event instant required")
    start, end = new_york_day(day)
    return start <= instant < end

class DayTests(unittest.TestCase):
    def test_fallback_day_has_twenty_five_elapsed_hours(self):
        start, end = new_york_day(date(2026, 11, 1))
        self.assertEqual(end - start, timedelta(hours=25))
        for hour in (5, 6):
            self.assertTrue(belongs(datetime(2026, 11, 1, hour, 30, tzinfo=UTC), date(2026, 11, 1)))
    def test_spring_day_has_twenty_three_elapsed_hours(self):
        start, end = new_york_day(date(2026, 3, 8))
        self.assertEqual(end - start, timedelta(hours=23))
    def test_shared_boundary_belongs_only_to_next_day(self):
        first = date(2026, 11, 1)
        second = date(2026, 11, 2)
        start, boundary = new_york_day(first)
        self.assertEqual(boundary, new_york_day(second)[0])
        self.assertTrue(belongs(start, first))
        self.assertFalse(belongs(boundary, first))
        self.assertTrue(belongs(boundary, second))
    def test_rejects_naive_instants_and_datetime_as_date(self):
        with self.assertRaises(ValueError):
            belongs(datetime(2026, 11, 1), date(2026, 11, 1))
        with self.assertRaises(ValueError):
            new_york_day(datetime(2026, 11, 1, tzinfo=UTC))

if __name__ == "__main__":
    unittest.main(verbosity=2)

Four test methods passed locally. The November 1, 2026 interval spans 25 elapsed hours, the March 8 interval spans 23, and the shared midnight belongs only to the following day. Both UTC occurrences of the repeated 01:30 local hour remain inside the fallback day's interval.

Keep event time distinct from observation time

A dashboard read at 09:00 is an observation instant. It does not become the event time for every value on the screen. Use this helper only when a record actually contains an event instant with the required meaning. A cumulative counter observed during the day cannot be partitioned into daily events with this code alone.

The function requires UTC input so comparisons have one explicit basis. Callers with another aware timezone can convert deliberately before calling. Naive timestamps are rejected rather than interpreted using the machine's timezone.

State the timezone scope

This example does not claim that local midnight exists uniquely in every IANA zone and historical period. Some jurisdictions have unusual transitions or skipped dates. A generic library needs an explicit policy for those cases and tests for its supported zones. A fixed-offset timezone cannot substitute for the named region when the desired rule follows local daylight changes.

The helper is not a scheduler, an event deduplicator or a completeness proof for a report. Adjacent windows partition the supplied instants; missing events and late-arriving data still require separate handling. Preserve the timezone-data version with reproducibility evidence, since updated civil-time rules can affect future conversions.

See the official datetime and zoneinfo documentation. A daily event window answers which supplied instants belong to a calendar date. It does not select a rate band or establish the completeness of a traffic report.