timeweave

Timezone detection, conversion, and a self-maintaining IANA rule cache. Python 3.9+.

Install

pip install timeweave

Layers

Library use

import timeweave

info = timeweave.detect_timezone()
print(info["timezone"], info["utc_offset"], info["dst_active"])

result = timeweave.convert_timezone(
    "2024-03-10 02:30", ["UTC", "Asia/Tokyo"], from_zone="America/New_York"
)
print(result["instant_utc"], result["local_time_kind"])

parsed = timeweave.parse_datetime("Sun, 10 Mar 2024 07:30:00 +0000")

CLI

tzkit detect --use-ip
tzkit convert '2024-03-10 02:30' --from America/New_York --to UTC --to Asia/Tokyo
tzkit parse 'Sun, 10 Mar 2024 07:30:00 +0000'
tzkit list Europe --transitions --sort offset

tz-update check --json
tz-compile refresh --force
tz-compile status

DST policy

Wall-clock times that fall in a DST gap or fold are classified, never guessed silently:

• --ambiguous earliest|latest|raise — repeated wall times (fold)
• --nonexistent shift_forward|shift_backward|raise — skipped wall times (gap)

raise exits 6 so CI catches the case.

Auto-update

detect_timezone() and convert_timezone() start a non-blocking daemon-thread update check, at most once per 24h, gated by a marker file. Failures are logged and swallowed; the caller's result is never affected.

Disable it:

Environment

Security notes

• SHA-256 proves integrity, not authenticity. If the same host serves the payload and the checksum, it controls both. Set TIMEWEAVE_SIGNATURE_URL and TIMEWEAVE_GPG_KEYRING against a trusted key for real authenticity.
• The compiler targets an app-owned directory by default. Writing into /usr/share/zoneinfo requires --system, needs root, and affects every process on the host. Prefer your OS's signed tzdata package for the system tree; use this module for isolated, air-gapped, or version-pinned caches.
• Archive members and Zone/Link names are validated before zic runs, and compiler output is re-checked for containment afterwards.
• The zic path is a fixed absolute constant, validated executable, and is never read from a network response.

License

MIT