Epoch Time Converter#

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#

bash

# 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+.