zoneinfo

IANA time zones for Ecko: read a timestamp as the wall time in a named zone, build one from a wall time, and do DST-correct calendar arithmetic. Pure - no capabilities.

ecko get github.com/ecko-lang/zoneinfo
import zoneinfo

Pure computation: it declares no capabilities, so it cannot touch the network, the filesystem or the environment.

Version 0.2.0 - source - MIT.


zones()

Every zone and alias name the database knows, sorted: "Africa/Abidjan" through "Zulu".

contains(zones(), "Europe/Berlin")   # true

version()

The IANA time zone database release the zones come from, such as "2026e".

offset(ms, zone)

zone's offset from UTC at instant ms (Unix ms), in milliseconds: positive east of Greenwich, so Berlin in summer is 7200000.

errors: zoneinfo/unknown_zone for a name the database does not know; bug/bad_argument when ms is not an Int or zone not a String.

offset(time.parse("2026-07-01T12:00:00Z"), "Europe/Berlin")   # 7200000

in_zone(ms, zone)

The wall time instant ms shows in zone: { year, month, day, hour, minute, second, millisecond, weekday, yearday } (the fields of datetime.components, weekday Mon=0..Sun=6), plus offset (ms), abbreviation ("CEST"), dst and zone. Any IANA name or alias works, such as "Europe/Berlin" or "US/Eastern".

errors: zoneinfo/unknown_zone for a name the database does not know; bug/bad_argument when ms is not an Int or zone not a String.

in_zone(time.now(), "Asia/Tokyo").hour

from_components(zone, y, mo, d, h = 0, mi = 0, s = 0, milli = 0)

The instant a wall time in zone names, as Unix ms.

A time a DST change skips moves forward by the length of the gap: 02:30 on a night that jumps from 02:00 to 03:00 is 03:30. A time it repeats is the first occurrence, the one still on the earlier offset. Every component is checked: month 1-12, a day the month has, hour 0-23, minute and second 0-59, millisecond 0-999.

errors: zoneinfo/out_of_range for a component outside its range (30 February, month 13); zoneinfo/unknown_zone for an unknown zone; bug/bad_argument when a component is not an Int or zone not a String.

from_components("America/New_York", 2026, 7, 16, 17)   # 17:00 in New York

add_days(ms, n, zone)

The instant n calendar days later in zone, at the same wall time. A day across a DST change is 23 or 25 hours long. n may be negative.

errors: zoneinfo/unknown_zone for an unknown zone; bug/bad_argument when ms or n is not an Int or zone not a String.

add_days(t, 1, "Europe/Berlin")   # the same wall time tomorrow

add_months(ms, n, zone)

The instant n months later in zone, at the same wall time, clamping the day to the target month's length (Jan 31 + 1 month is Feb 28 or 29). n may be negative.

errors: zoneinfo/unknown_zone for an unknown zone; bug/bad_argument when ms or n is not an Int or zone not a String.

add_months(t, 1, "America/New_York")

add_years(ms, n, zone)

The instant n years later in zone, at the same wall time. 29 February plus one year is 28 February.

errors: zoneinfo/unknown_zone for an unknown zone; bug/bad_argument when ms or n is not an Int or zone not a String.

add_years(t, 1, "Europe/Berlin")

start_of_day(ms, zone)

Midnight in zone on the day instant ms falls on there. On a day a DST change skips midnight, the first moment of the day.

errors: zoneinfo/unknown_zone for an unknown zone; bug/bad_argument when ms is not an Int or zone not a String.

start_of_day(time.now(), "Europe/Berlin")

format(ms, fmt, zone)

Format instant ms as the wall time in zone, with a strftime-style pattern. %Z writes the zone's abbreviation ("CEST"), %z its offset ("+0200") and %:z the offset with a colon ("+02:00"). An offset with seconds, which only the local mean time of old dates has, is written with them ("+001932", "+00:19:32").

errors: bug/bad_format for a pattern chrono cannot format, such as a trailing %; zoneinfo/unknown_zone for an unknown zone; bug/bad_argument for a wrong-typed argument.

format(time.now(), "%Y-%m-%d %H:%M %Z", "Europe/Berlin")

to_iso(ms, zone)

ISO-8601 for the wall time in zone, with its offset: 2026-07-29T15:45:00.000+02:00, which time.parse reads back to the same instant. An offset with seconds (local mean time, before about 1900-1940 depending on the zone) is written with them, +00:19:32 as Python does; RFC 3339 has no form for it, so time.parse refuses that string rather than reading a different instant.

errors: zoneinfo/unknown_zone for an unknown zone; bug/bad_argument when ms is not an Int or zone not a String.

to_iso(time.parse("2026-07-01T12:00:00Z"), "Europe/Berlin")   # "2026-07-01T14:00:00.000+02:00"

parse_format(s, fmt, zone)

Parse text s with a strftime-style pattern as a wall time in zone, read the way from_components reads one. A pattern with %z or %:z carries its own offset (+0200, -05:00), so zone does not apply to it; %%z is literal text.

errors: zoneinfo/no_match when s does not match fmt; bug/bad_format for a pattern chrono cannot read; zoneinfo/unknown_zone for an unknown zone; bug/bad_argument for a wrong-typed argument.

parse_format("29/07/2026 17:00", "%d/%m/%Y %H:%M", "America/New_York")