Epoch Time Converter

Convert between Unix epoch timestamps (seconds or milliseconds) and human-readable date strings in any IANA timezone. Use when the user provides a number that looks like a Unix timestamp (10 digits ≈ seconds, 13 digits ≈ milliseconds) and asks what time it is, or provides a date/time string and wants the corresponding epoch value. Triggers on phrases like "what time is 1700000000", "convert epoch", "unix timestamp to date", "to UTC", "to Asia/Shanghai", "epoch in milliseconds".

Overview

Two-way conversion between Unix epoch timestamps and human-readable datetimes, with explicit timezone handling. Backed by a single self-contained Python script that uses only the standard library (datetime, zoneinfo).

Quick start

# Epoch seconds -> human time in a given timezone
python3 scripts/epoch.py to-date 1700000000 --tz Asia/Shanghai
# -> 2023-11-15 06:13:20 +08:00 (Asia/Shanghai)

# Epoch milliseconds -> human time
python3 scripts/epoch.py to-date 1700000000000 --unit ms --tz UTC

# Human time -> epoch seconds (input timezone is required)
python3 scripts/epoch.py to-epoch "2023-11-15 06:13:20" --tz Asia/Shanghai
# -> 1700000000

# Human time -> epoch milliseconds
python3 scripts/epoch.py to-epoch "2023-11-15T06:13:20" --tz Asia/Shanghai --unit ms

Decision tree

1. Input is purely numeric → use to-date.
   • 10 digits → --unit s (default).
   • 13 digits → --unit ms.
2. Input looks like a date/time string → use to-epoch and require --tz.
3. If the user did not specify a timezone for to-date, default to UTC and explicitly tell them which timezone you used.

Output format

Both subcommands print one line: <value> (<context>). Always echo this raw output back to the user, then add a one-line plain-language summary.

Edge cases to watch

• Bare numbers without a unit hint: prefer length-based detection (10 vs 13 digits) over guessing.
• Strings without timezone offsets (e.g. 2024-01-01 09:00) are interpreted in the --tz value; do not silently fall back to system local time.
• Negative epoch values (pre-1970) are supported.

Resources

scripts/

• epoch.py — CLI implementing to-date and to-epoch. Pure stdlib; runs on any Python 3.9+.