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