epochlens 0.1.0__tar.gz

epochlens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 epochlens contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

epochlens-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: epochlens
+Version: 0.1.0
+Summary: A smart bidirectional timestamp inspector: paste any unix timestamp (s/ms/us/ns auto-detected) or date, see every representation. Zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/epochlens-py
+Project-URL: Repository, https://github.com/jjdoor/epochlens-py
+Project-URL: Issues, https://github.com/jjdoor/epochlens-py/issues
+Keywords: timestamp,epoch,unix-time,datetime,iso8601,converter,cli,date,devtools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# epochlens
+
+**A smart, bidirectional timestamp inspector.** Paste any unix timestamp — in
+seconds, milliseconds, microseconds *or* nanoseconds, auto-detected — or a date
+string, and see every representation at once. No flags to remember, no `date -r`
+vs `date -d @` platform roulette.
+
+```bash
+pipx run epochlens 1718750000
+#   input     1718750000  (unix seconds)
+#
+#   unix s    1718750000
+#   unix ms   1718750000000
+#   unix µs   1718750000000000
+#   unix ns   1718750000000000000
+#   iso utc   2024-06-18T22:33:20Z
+#   iso local 2024-06-19T06:33:20+08:00
+#   relative  2 minutes ago
+#   rfc 2822  Tue, 18 Jun 2024 22:33:20 +0000
+```
+
+Zero dependencies, pure standard library. Also on npm (`npx epochlens`) — the two
+builds produce **byte-for-byte identical** output.
+
+## Why
+
+`date` can do this, but `date -r 1718750000` (BSD/macOS) and `date -d @1718750000`
+(GNU/Linux) are *different commands*, neither auto-detects whether you pasted
+seconds or milliseconds, and neither shows you all the forms at once. Online
+epoch converters do, but you have to leave the terminal and paste your data into
+someone else's website.
+
+`epochlens` is the one command that just works on every platform, guesses the
+unit the way you'd expect, and goes **both directions**:
+
+```bash
+epochlens 1718750000123          # millis? micros? it figures it out
+epochlens 2024-06-18T22:33:20Z   # date string -> every epoch precision
+epochlens now                    # the current moment, all forms
+echo 1718750000 | epochlens      # reads stdin too
+```
+
+## Usage
+
+```bash
+epochlens <timestamp|date>
+epochlens --unit ms 1718750000      # force the unit if the guess is wrong
+epochlens --offset +05:30 1718750000  # add a row in a fixed UTC offset
+epochlens --json 1718750000          # machine-readable
+```
+
+**Auto-detection.** A bare number is classified by magnitude: ~10 digits →
+seconds, ~13 → milliseconds, ~16 → microseconds, ~19 → nanoseconds. The detected
+unit is always echoed back so you can catch a wrong guess and re-run with
+`--unit`. A value with a decimal point is read as seconds.
+
+**Accepted input.** Unix timestamps (any precision), ISO 8601
+(`2024-06-18T22:33:20Z`, `2024-06-18 22:33:20`, `2024-06-18`, with or without a
+`Z`/`±HH:MM` offset), and RFC 2822 (`Tue, 18 Jun 2024 22:33:20 +0000`). A date
+string **without** an offset is read as UTC.
+
+**`--json`** emits the unix values as **strings** so nanosecond precision
+survives a 19-digit integer:
+
+```json
+{
+  "input": "1718750000123",
+  "detected": "unix milliseconds",
+  "unix": { "s": "1718750000", "ms": "1718750000123", "us": "1718750000123000", "ns": "1718750000123000000" },
+  "iso_utc": "2024-06-18T22:33:20.123Z",
+  "iso_local": "2024-06-19T06:33:20.123+08:00",
+  "iso_offset": null,
+  "relative": "2 minutes ago",
+  "rfc2822": "Tue, 18 Jun 2024 22:33:20 +0000"
+}
+```
+
+Exit codes: `0` ok · `2` error (unparseable input, out-of-range date).
+
+## How it works
+
+Date/time handling is a minefield of cross-platform and cross-language
+disagreements, so epochlens does **none** of its conversion through the
+runtime's date library. `datetime.fromisoformat`, `isoformat`, `strftime` (and
+Node's `Date.parse`/`toISOString`) all differ between (and within) the two
+runtimes. Instead every conversion is plain integer arithmetic over a
+proleptic-Gregorian
+[civil-day algorithm](https://howardhinnant.github.io/date_algorithms.html), and
+all formatting is hand-rolled. That's what lets the Node and Python builds stay
+byte-identical, and it's why nanosecond values stay exact (native ints in
+Python, BigInt in Node).
+
+## Scope
+
+The MVP shows UTC, your machine's local time, and any fixed `--offset`. Named
+IANA zones (`--tz America/New_York`) are intentionally left out for now: Python's
+`zoneinfo` needs an OS tz database that Windows lacks, which would break the
+zero-dependency promise. Natural-language *input* (`"3 days ago"`) is also out of
+scope — relative time is shown as output only.
+
+## Install
+
+```bash
+pip install epochlens   # or pipx run epochlens
+npm i -g epochlens      # Node build, identical behaviour
+```
+
+Python ≥ 3.8 or Node ≥ 18. No dependencies.
+
+## License
+
+MIT

epochlens-0.1.0/README.md

@@ -0,0 +1,112 @@
+# epochlens
+
+**A smart, bidirectional timestamp inspector.** Paste any unix timestamp — in
+seconds, milliseconds, microseconds *or* nanoseconds, auto-detected — or a date
+string, and see every representation at once. No flags to remember, no `date -r`
+vs `date -d @` platform roulette.
+
+```bash
+pipx run epochlens 1718750000
+#   input     1718750000  (unix seconds)
+#
+#   unix s    1718750000
+#   unix ms   1718750000000
+#   unix µs   1718750000000000
+#   unix ns   1718750000000000000
+#   iso utc   2024-06-18T22:33:20Z
+#   iso local 2024-06-19T06:33:20+08:00
+#   relative  2 minutes ago
+#   rfc 2822  Tue, 18 Jun 2024 22:33:20 +0000
+```
+
+Zero dependencies, pure standard library. Also on npm (`npx epochlens`) — the two
+builds produce **byte-for-byte identical** output.
+
+## Why
+
+`date` can do this, but `date -r 1718750000` (BSD/macOS) and `date -d @1718750000`
+(GNU/Linux) are *different commands*, neither auto-detects whether you pasted
+seconds or milliseconds, and neither shows you all the forms at once. Online
+epoch converters do, but you have to leave the terminal and paste your data into
+someone else's website.
+
+`epochlens` is the one command that just works on every platform, guesses the
+unit the way you'd expect, and goes **both directions**:
+
+```bash
+epochlens 1718750000123          # millis? micros? it figures it out
+epochlens 2024-06-18T22:33:20Z   # date string -> every epoch precision
+epochlens now                    # the current moment, all forms
+echo 1718750000 | epochlens      # reads stdin too
+```
+
+## Usage
+
+```bash
+epochlens <timestamp|date>
+epochlens --unit ms 1718750000      # force the unit if the guess is wrong
+epochlens --offset +05:30 1718750000  # add a row in a fixed UTC offset
+epochlens --json 1718750000          # machine-readable
+```
+
+**Auto-detection.** A bare number is classified by magnitude: ~10 digits →
+seconds, ~13 → milliseconds, ~16 → microseconds, ~19 → nanoseconds. The detected
+unit is always echoed back so you can catch a wrong guess and re-run with
+`--unit`. A value with a decimal point is read as seconds.
+
+**Accepted input.** Unix timestamps (any precision), ISO 8601
+(`2024-06-18T22:33:20Z`, `2024-06-18 22:33:20`, `2024-06-18`, with or without a
+`Z`/`±HH:MM` offset), and RFC 2822 (`Tue, 18 Jun 2024 22:33:20 +0000`). A date
+string **without** an offset is read as UTC.
+
+**`--json`** emits the unix values as **strings** so nanosecond precision
+survives a 19-digit integer:
+
+```json
+{
+  "input": "1718750000123",
+  "detected": "unix milliseconds",
+  "unix": { "s": "1718750000", "ms": "1718750000123", "us": "1718750000123000", "ns": "1718750000123000000" },
+  "iso_utc": "2024-06-18T22:33:20.123Z",
+  "iso_local": "2024-06-19T06:33:20.123+08:00",
+  "iso_offset": null,
+  "relative": "2 minutes ago",
+  "rfc2822": "Tue, 18 Jun 2024 22:33:20 +0000"
+}
+```
+
+Exit codes: `0` ok · `2` error (unparseable input, out-of-range date).
+
+## How it works
+
+Date/time handling is a minefield of cross-platform and cross-language
+disagreements, so epochlens does **none** of its conversion through the
+runtime's date library. `datetime.fromisoformat`, `isoformat`, `strftime` (and
+Node's `Date.parse`/`toISOString`) all differ between (and within) the two
+runtimes. Instead every conversion is plain integer arithmetic over a
+proleptic-Gregorian
+[civil-day algorithm](https://howardhinnant.github.io/date_algorithms.html), and
+all formatting is hand-rolled. That's what lets the Node and Python builds stay
+byte-identical, and it's why nanosecond values stay exact (native ints in
+Python, BigInt in Node).
+
+## Scope
+
+The MVP shows UTC, your machine's local time, and any fixed `--offset`. Named
+IANA zones (`--tz America/New_York`) are intentionally left out for now: Python's
+`zoneinfo` needs an OS tz database that Windows lacks, which would break the
+zero-dependency promise. Natural-language *input* (`"3 days ago"`) is also out of
+scope — relative time is shown as output only.
+
+## Install
+
+```bash
+pip install epochlens   # or pipx run epochlens
+npm i -g epochlens      # Node build, identical behaviour
+```
+
+Python ≥ 3.8 or Node ≥ 18. No dependencies.
+
+## License
+
+MIT

epochlens-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "epochlens"
+version = "0.1.0"
+description = "A smart bidirectional timestamp inspector: paste any unix timestamp (s/ms/us/ns auto-detected) or date, see every representation. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "yyfjj" }]
+keywords = ["timestamp", "epoch", "unix-time", "datetime", "iso8601", "converter", "cli", "date", "devtools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/jjdoor/epochlens-py"
+Repository = "https://github.com/jjdoor/epochlens-py"
+Issues = "https://github.com/jjdoor/epochlens-py/issues"
+
+[project.scripts]
+epochlens = "epochlens.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

epochlens-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

epochlens-0.1.0/src/epochlens/__init__.py

@@ -0,0 +1,3 @@
+"""epochlens — a smart bidirectional timestamp inspector. Zero dependencies."""
+
+__version__ = "0.1.0"

epochlens-0.1.0/src/epochlens/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

epochlens-0.1.0/src/epochlens/cli.py

@@ -0,0 +1,180 @@
+import json
+import os
+import re
+import signal
+import sys
+import time
+
+from . import __version__
+from . import core
+
+
+def _paint():
+    use_color = sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+    def col(c, s):
+        return f"\x1b[{c}m{s}\x1b[0m" if use_color else s
+
+    return {
+        "red": lambda s: col("31", s), "green": lambda s: col("32", s),
+        "yellow": lambda s: col("33", s), "dim": lambda s: col("2", s),
+        "bold": lambda s: col("1", s),
+    }
+
+
+def _help(p):
+    b = p["bold"]
+    return (
+        f"{b('epochlens')} — a smart, bidirectional timestamp inspector. Zero dependencies.\n"
+        "\n"
+        "Paste any unix timestamp (seconds, millis, micros or nanos — auto-detected) OR a\n"
+        "date string (ISO 8601 / RFC 2822), and see every representation at once: all four\n"
+        "precisions, ISO 8601 UTC + your local time, a human relative time, and RFC 2822.\n"
+        "\n"
+        f"{b('Usage')}\n"
+        "  epochlens <timestamp|date>     e.g.  epochlens 1718750000\n"
+        "  epochlens now                  Inspect the current moment\n"
+        "  echo 1718750000 | epochlens    Reads stdin when no argument is given\n"
+        "\n"
+        f"{b('Options')}\n"
+        "  --unit s|ms|us|ns   Force the unit instead of auto-detecting\n"
+        "  --offset ±HH:MM     Add a row in a fixed UTC offset (e.g. --offset +05:30)\n"
+        "  --json              Machine-readable output (unix values are strings, for precision)\n"
+        "  --help | --version\n"
+        "\n"
+        f"{b('Notes')}\n"
+        "  Date strings without an offset are read as UTC. Numbers are unambiguous.\n"
+        "  Exit  0 ok · 2 error\n"
+    )
+
+
+def _parse_offset_arg(tok, die):
+    if not tok:
+        return die("--offset needs a value like +05:30")
+    m = re.fullmatch(r"([+-])([0-9]{2}):?([0-9]{2})", tok)
+    if not m:
+        return die(f"invalid --offset: {tok} (use ±HH:MM)")
+    hh, mm = int(m.group(2)), int(m.group(3))
+    if hh > 23 or mm > 59:
+        return die(f"--offset out of range: {tok}")
+    sign = -1 if m.group(1) == "-" else 1
+    return sign * (hh * 3600 + mm * 60)
+
+
+def _local_offset_sec(ms):
+    try:
+        off = time.localtime(ms // 1000).tm_gmtoff
+        return off if off is not None else None
+    except (OverflowError, OSError, ValueError):
+        return None
+
+
+class _Exit(Exception):
+    def __init__(self, code):
+        self.code = code
+
+
+def main(argv=None):
+    try:
+        signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+    except (AttributeError, ValueError):
+        pass
+
+    argv = list(sys.argv[1:] if argv is None else argv)
+    p = _paint()
+
+    def die(msg):
+        sys.stderr.write(p["red"](f"epochlens: {msg}\n"))
+        raise _Exit(2)
+
+    try:
+        # Only honour -h/-v BEFORE a `--` terminator (after it they're data).
+        dd_idx = argv.index("--") if "--" in argv else len(argv)
+        pre = argv[:dd_idx]
+        if "-h" in pre or "--help" in pre:
+            sys.stdout.write(_help(p))
+            return 0
+        if "-v" in pre or "--version" in pre:
+            sys.stdout.write(__version__ + "\n")
+            return 0
+
+        as_json = False
+        unit = None
+        offset_sec = None
+        positional = []
+        dd_seen = False
+        i = 0
+        while i < len(argv):
+            a = argv[i]
+            if dd_seen:
+                positional.append(a)
+            elif a == "--":
+                dd_seen = True
+            elif a == "--json":
+                as_json = True
+            elif a == "--unit":
+                i += 1
+                unit = argv[i] if i < len(argv) else None
+                if unit not in ("s", "ms", "us", "ns"):
+                    die("--unit must be one of s, ms, us, ns")
+            elif a.startswith("--unit="):
+                unit = a[7:]
+                if unit not in ("s", "ms", "us", "ns"):
+                    die("--unit must be one of s, ms, us, ns")
+            elif a == "--offset":
+                i += 1
+                offset_sec = _parse_offset_arg(argv[i] if i < len(argv) else None, die)
+            elif a.startswith("--offset="):
+                offset_sec = _parse_offset_arg(a[9:], die)
+            elif a in ("-h", "--help", "-v", "--version"):
+                pass
+            elif a.startswith("-") and a != "-" and not re.match(r"-\d", a):
+                die(f"unknown option: {a} (use -- to end options)")
+            else:
+                positional.append(a)
+            i += 1
+
+        raw = core.trim_ascii(" ".join(positional))
+        if raw == "":
+            try:
+                raw = core.trim_ascii(sys.stdin.read())
+            except Exception:
+                raw = ""
+        if raw == "":
+            sys.stdout.write(_help(p))
+            return 0
+
+        env_now = os.environ.get("EPOCHLENS_NOW")
+        if env_now:
+            if not re.fullmatch(r"-?[0-9]+", env_now):
+                die("invalid EPOCHLENS_NOW (must be integer milliseconds)")
+            now_ms = int(env_now)
+        else:
+            now_ms = int(time.time() * 1000)
+
+        try:
+            ns, detected = core.parse_input(raw, {"unit": unit, "nowMs": now_ms})
+        except ValueError as e:
+            die(str(e))
+
+        ms = ns // 1_000_000
+        ctx = {
+            "rawInput": raw,
+            "detected": detected,
+            "nowMs": now_ms,
+            "localOffsetSec": _local_offset_sec(ms),
+            "explicitOffset": {"sec": offset_sec} if offset_sec is not None else None,
+        }
+
+        try:
+            result = core.compute(ns, ctx)
+        except ValueError as e:
+            die(str(e))
+
+        if as_json:
+            sys.stdout.write(json.dumps(result, indent=2, ensure_ascii=False) + "\n")
+        else:
+            sys.stdout.write(core.format_human(result, p) + "\n")
+        return 0
+    except _Exit as ex:
+        return ex.code

epochlens-0.1.0/src/epochlens/core.py

@@ -0,0 +1,297 @@
+"""epochlens core — pure timestamp parsing, conversion & rendering.
+
+No datetime.fromisoformat, no isoformat(), no clock, no IO — all of those diverge
+from the Node build. Every conversion is done with our own integer math (a
+proleptic-Gregorian civil-day algorithm) and hand-rolled formatting, so the Node
+and Python builds emit byte-for-byte identical output.
+
+"now" and the machine's local UTC offset are the only runtime-dependent inputs;
+they are passed in from cli.py so this module stays pure & testable.
+"""
+
+import re
+
+# nanoseconds per unit
+NS_PER = {"s": 1_000_000_000, "ms": 1_000_000, "us": 1_000, "ns": 1}
+UNIT_NAME = {"s": "unix seconds", "ms": "unix milliseconds",
+             "us": "unix microseconds", "ns": "unix nanoseconds"}
+MON = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+DOW = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
+
+# The ASCII whitespace set, stripped identically in both builds. Native
+# trim()/strip() disagree on exotic chars (NEL/C1/BOM), so we never use them.
+_WS = " \t\n\r\f\v"
+
+
+def trim_ascii(s):
+    return str(s).strip(_WS)
+
+
+# ---- integer helpers (parity-critical) -------------------------------------
+
+# Howard Hinnant's civil <-> days-from-1970 algorithm (proleptic Gregorian).
+# Python // floors, matching Node's Math.floor, so both languages agree exactly.
+def days_from_civil(y, m, d):
+    yy = y - (1 if m <= 2 else 0)
+    era = yy // 400
+    yoe = yy - era * 400
+    doy = (153 * (m + (-3 if m > 2 else 9)) + 2) // 5 + d - 1
+    doe = yoe * 365 + yoe // 4 - yoe // 100 + doy
+    return era * 146097 + doe - 719468
+
+
+def civil_from_days(z0):
+    z = z0 + 719468
+    era = z // 146097
+    doe = z - era * 146097
+    yoe = (doe - doe // 1460 + doe // 36524 - doe // 146096) // 365
+    y = yoe + era * 400
+    doy = doe - (365 * yoe + yoe // 4 - yoe // 100)
+    mp = (5 * doy + 2) // 153
+    d = doy - (153 * mp + 2) // 5 + 1
+    m = mp + (3 if mp < 10 else -9)
+    return (y + (1 if m <= 2 else 0), m, d)
+
+
+def components_from_ms(ms):
+    """Break an epoch-millisecond int into UTC calendar components (floor-based)."""
+    days = ms // 86400000
+    rem = ms - days * 86400000  # 0 .. 86399999
+    y, mo, d = civil_from_days(days)
+    h = rem // 3600000
+    rem -= h * 3600000
+    mi = rem // 60000
+    rem -= mi * 60000
+    s = rem // 1000
+    ms_c = rem - s * 1000
+    return {"y": y, "mo": mo, "d": d, "h": h, "mi": mi, "s": s, "ms": ms_c, "days": days}
+
+
+def _dow(days):
+    return (days % 7 + 4) % 7  # 1970-01-01 (days=0) was Thursday (=4, Sunday=0)
+
+
+_DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+
+
+def _is_leap(y):
+    return (y % 4 == 0 and y % 100 != 0) or y % 400 == 0
+
+
+def _days_in_month(y, m):
+    return 29 if (m == 2 and _is_leap(y)) else _DAYS_IN_MONTH[m - 1]
+
+
+def _validate_calendar(y, mo, d, h, mi, s):
+    if mo < 1 or mo > 12:
+        raise ValueError(f"invalid month: {mo}")
+    if d < 1 or d > _days_in_month(y, mo):
+        raise ValueError(f"invalid day: {d}")
+    if h > 23:
+        raise ValueError(f"invalid hour: {h}")
+    if mi > 59:
+        raise ValueError(f"invalid minute: {mi}")
+    if s == 60:
+        raise ValueError("leap seconds (:60) are not representable")
+    if s > 59:
+        raise ValueError(f"invalid second: {s}")
+
+
+# ---- detection & parsing ---------------------------------------------------
+
+def detect_unit(abs_int):
+    if abs_int < 100000000000:          # < 1e11
+        return "s"
+    if abs_int < 100000000000000:       # < 1e14
+        return "ms"
+    if abs_int < 100000000000000000:    # < 1e17
+        return "us"
+    return "ns"
+
+
+# All patterns use [0-9]/[ \t] (never \d/\s) so they match the Node build
+# exactly: Python re \d also matches Unicode Nd digits and \s differs from JS
+# \s on NEL/C1/BOM. Explicit classes erase that.
+def _parse_offset_token(tok):
+    m = re.fullmatch(r"([+-])([0-9]{2}):?([0-9]{2})", tok)
+    if not m:
+        raise ValueError(f"invalid offset: {tok}")
+    hh, mm = int(m.group(2)), int(m.group(3))
+    if hh > 23 or mm > 59:
+        raise ValueError(f"offset out of range: {tok}")
+    sign = -1 if m.group(1) == "-" else 1
+    return sign * (hh * 3600 + mm * 60)
+
+
+_ISO_RE = re.compile(r"([0-9]{4})-([0-9]{2})-([0-9]{2})(?:[ T]([0-9]{2}):([0-9]{2})(?::([0-9]{2})(?:\.([0-9]+))?)?(Z|[+-][0-9]{2}:?[0-9]{2})?)?")
+_RFC_RE = re.compile(r"(?:(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun),[ \t]*)?([0-9]{1,2})[ \t]+(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[ \t]+([0-9]{4})[ \t]+([0-9]{2}):([0-9]{2})(?::([0-9]{2}))?[ \t]+([+-][0-9]{4}|GMT|UTC|UT)")
+_NUM_RE = re.compile(r"([+-]?)([0-9]+)(?:\.([0-9]+))?")
+
+
+def _frac_to_ns(frac):
+    if not frac:
+        return 0
+    return (int(frac) * 1_000_000_000) // (10 ** len(frac))
+
+
+def _date_components_to_ns(y, mo, d, h, mi, s, frac, offset_sec):
+    _validate_calendar(y, mo, d, h, mi, s)
+    days = days_from_civil(y, mo, d)
+    total_sec = days * 86400 + h * 3600 + mi * 60 + s - offset_sec
+    return total_sec * 1_000_000_000 + _frac_to_ns(frac)
+
+
+def parse_input(raw, opts=None):
+    """Parse a raw input string into (ns:int, detected:str). Handles "now", a
+    bare unix timestamp (auto-detected s/ms/us/ns, overridable via opts['unit']),
+    ISO 8601 and RFC 2822. Raises ValueError on unrecognized input."""
+    opts = opts or {}
+    s = trim_ascii(raw)
+    if s == "":
+        raise ValueError("no input given")
+
+    if s.lower() == "now":
+        if opts.get("nowMs") is None:
+            raise ValueError('"now" is unavailable here')
+        return (int(opts["nowMs"]) * 1_000_000, "current time")
+
+    num_candidate = s.replace(",", "").replace("_", "")
+    nm = _NUM_RE.fullmatch(num_candidate)
+    if nm:
+        neg = nm.group(1) == "-"
+        int_digits = nm.group(2)
+        frac = nm.group(3) or ""
+        unit = opts.get("unit") or ("s" if frac else detect_unit(int(int_digits)))
+        per = NS_PER[unit]
+        ns = int(int_digits) * per
+        if frac:
+            ns += (int(frac) * per) // (10 ** len(frac))
+        if neg:
+            ns = -ns
+        return (ns, UNIT_NAME[unit] + (" (forced)" if opts.get("unit") else ""))
+
+    iso = _ISO_RE.fullmatch(s)
+    if iso:
+        y, mo, d = int(iso.group(1)), int(iso.group(2)), int(iso.group(3))
+        has_time = iso.group(4) is not None
+        h = int(iso.group(4)) if has_time else 0
+        mi = int(iso.group(5)) if iso.group(5) is not None else 0
+        sec = int(iso.group(6)) if iso.group(6) is not None else 0
+        frac = iso.group(7) or ""
+        off = iso.group(8)
+        offset_sec = _parse_offset_token(off) if (off and off != "Z") else 0
+        ns = _date_components_to_ns(y, mo, d, h, mi, sec, frac, offset_sec)
+        return (ns, "ISO 8601 datetime" if has_time else "ISO 8601 date")
+
+    rfc = _RFC_RE.fullmatch(s)
+    if rfc:
+        d = int(rfc.group(1))
+        mo = MON.index(rfc.group(2)) + 1
+        y = int(rfc.group(3))
+        h, mi = int(rfc.group(4)), int(rfc.group(5))
+        sec = int(rfc.group(6)) if rfc.group(6) is not None else 0
+        z = rfc.group(7)
+        offset_sec = _parse_offset_token(z[:3] + ":" + z[3:]) if re.fullmatch(r"[+-][0-9]{4}", z) else 0
+        ns = _date_components_to_ns(y, mo, d, h, mi, sec, "", offset_sec)
+        return (ns, "RFC 2822")
+
+    raise ValueError(
+        f'unrecognized input: "{s}"\n'
+        "accepted: a unix timestamp (s/ms/us/ns), ISO 8601 (e.g. 2024-06-18T22:33:20Z), or RFC 2822")
+
+
+# ---- formatting ------------------------------------------------------------
+
+def _iso_from_components(c):
+    s = f"{c['y']:04d}-{c['mo']:02d}-{c['d']:02d}T{c['h']:02d}:{c['mi']:02d}:{c['s']:02d}"
+    if c["ms"]:
+        s += f".{c['ms']:03d}"
+    return s
+
+
+def _offset_label(sec):
+    sign = "-" if sec < 0 else "+"
+    a = abs(sec)
+    return f"{sign}{a // 3600:02d}:{(a % 3600) // 60:02d}"
+
+
+def _iso_with_offset(ms, offset_sec):
+    # Quantize to whole minutes: the label only shows ±HH:MM, and the OS APIs
+    # disagree on sub-minute precision (Node getTimezoneOffset is minute-resolution,
+    # Python tm_gmtoff is seconds — they differ for pre-1900 LMT zones). Dropping
+    # the sub-minute part in both keeps the wall-clock byte-identical.
+    q = int(offset_sec / 60) * 60
+    return _iso_from_components(components_from_ms(ms + q * 1000)) + _offset_label(q)
+
+
+def _rfc2822(c):
+    return (f"{DOW[_dow(c['days'])]}, {c['d']:02d} {MON[c['mo'] - 1]} {c['y']:04d} "
+            f"{c['h']:02d}:{c['mi']:02d}:{c['s']:02d} +0000")
+
+
+_REL_UNITS = [("year", 31536000), ("month", 2592000), ("day", 86400),
+              ("hour", 3600), ("minute", 60), ("second", 1)]
+
+
+def relative(delta_ms):
+    """delta_ms = now - instant; positive => instant is in the past."""
+    past = delta_ms >= 0
+    secs = abs(delta_ms) // 1000
+    if secs < 1:
+        return "just now"
+    for name, size in _REL_UNITS:
+        if secs >= size:
+            v = secs // size
+            label = f"{v} {name}{'s' if v != 1 else ''}"
+            return f"{label} ago" if past else f"in {label}"
+    return "just now"
+
+
+def compute(ns, ctx):
+    """Turn a nanosecond instant (int) into the full structured result. Pure."""
+    ms = ns // 1_000_000
+    c = components_from_ms(ms)
+    if c["y"] < 1 or c["y"] > 9999:
+        raise ValueError("out of displayable range (year must be between 0001 and 9999)")
+    local = ctx.get("localOffsetSec")
+    explicit = ctx.get("explicitOffset")
+    return {
+        "input": ctx["rawInput"],
+        "detected": ctx["detected"],
+        "unix": {
+            "s": str(ns // 1_000_000_000),
+            "ms": str(ns // 1_000_000),
+            "us": str(ns // 1_000),
+            "ns": str(ns),
+        },
+        "iso_utc": _iso_from_components(c) + "Z",
+        "iso_local": _iso_with_offset(ms, local) if local is not None else None,
+        "iso_offset": _iso_with_offset(ms, explicit["sec"]) if explicit else None,
+        "relative": relative(ctx["nowMs"] - ms),
+        "rfc2822": _rfc2822(c),
+    }
+
+
+PLAIN = {"red": lambda s: s, "green": lambda s: s, "yellow": lambda s: s,
+         "dim": lambda s: s, "bold": lambda s: s}
+
+
+def format_human(r, paint=None):
+    p = paint or PLAIN
+
+    def row(label, value):
+        return f"  {p['dim'](label.ljust(9))} {value}"
+
+    lines = [f"  {p['dim']('input'.ljust(9))} {p['bold'](r['input'])}  {p['dim']('(' + r['detected'] + ')')}", ""]
+    lines.append(row("unix s", p["green"](r["unix"]["s"])))
+    lines.append(row("unix ms", r["unix"]["ms"]))
+    lines.append(row("unix µs", r["unix"]["us"]))
+    lines.append(row("unix ns", r["unix"]["ns"]))
+    lines.append(row("iso utc", p["green"](r["iso_utc"])))
+    if r["iso_local"]:
+        lines.append(row("iso local", r["iso_local"]))
+    if r["iso_offset"]:
+        lines.append(row("iso off", r["iso_offset"]))
+    lines.append(row("relative", r["relative"]))
+    lines.append(row("rfc 2822", r["rfc2822"]))
+    return "\n".join(lines)

epochlens-0.1.0/src/epochlens.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: epochlens
+Version: 0.1.0
+Summary: A smart bidirectional timestamp inspector: paste any unix timestamp (s/ms/us/ns auto-detected) or date, see every representation. Zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/epochlens-py
+Project-URL: Repository, https://github.com/jjdoor/epochlens-py
+Project-URL: Issues, https://github.com/jjdoor/epochlens-py/issues
+Keywords: timestamp,epoch,unix-time,datetime,iso8601,converter,cli,date,devtools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# epochlens
+
+**A smart, bidirectional timestamp inspector.** Paste any unix timestamp — in
+seconds, milliseconds, microseconds *or* nanoseconds, auto-detected — or a date
+string, and see every representation at once. No flags to remember, no `date -r`
+vs `date -d @` platform roulette.
+
+```bash
+pipx run epochlens 1718750000
+#   input     1718750000  (unix seconds)
+#
+#   unix s    1718750000
+#   unix ms   1718750000000
+#   unix µs   1718750000000000
+#   unix ns   1718750000000000000
+#   iso utc   2024-06-18T22:33:20Z
+#   iso local 2024-06-19T06:33:20+08:00
+#   relative  2 minutes ago
+#   rfc 2822  Tue, 18 Jun 2024 22:33:20 +0000
+```
+
+Zero dependencies, pure standard library. Also on npm (`npx epochlens`) — the two
+builds produce **byte-for-byte identical** output.
+
+## Why
+
+`date` can do this, but `date -r 1718750000` (BSD/macOS) and `date -d @1718750000`
+(GNU/Linux) are *different commands*, neither auto-detects whether you pasted
+seconds or milliseconds, and neither shows you all the forms at once. Online
+epoch converters do, but you have to leave the terminal and paste your data into
+someone else's website.
+
+`epochlens` is the one command that just works on every platform, guesses the
+unit the way you'd expect, and goes **both directions**:
+
+```bash
+epochlens 1718750000123          # millis? micros? it figures it out
+epochlens 2024-06-18T22:33:20Z   # date string -> every epoch precision
+epochlens now                    # the current moment, all forms
+echo 1718750000 | epochlens      # reads stdin too
+```
+
+## Usage
+
+```bash
+epochlens <timestamp|date>
+epochlens --unit ms 1718750000      # force the unit if the guess is wrong
+epochlens --offset +05:30 1718750000  # add a row in a fixed UTC offset
+epochlens --json 1718750000          # machine-readable
+```
+
+**Auto-detection.** A bare number is classified by magnitude: ~10 digits →
+seconds, ~13 → milliseconds, ~16 → microseconds, ~19 → nanoseconds. The detected
+unit is always echoed back so you can catch a wrong guess and re-run with
+`--unit`. A value with a decimal point is read as seconds.
+
+**Accepted input.** Unix timestamps (any precision), ISO 8601
+(`2024-06-18T22:33:20Z`, `2024-06-18 22:33:20`, `2024-06-18`, with or without a
+`Z`/`±HH:MM` offset), and RFC 2822 (`Tue, 18 Jun 2024 22:33:20 +0000`). A date
+string **without** an offset is read as UTC.
+
+**`--json`** emits the unix values as **strings** so nanosecond precision
+survives a 19-digit integer:
+
+```json
+{
+  "input": "1718750000123",
+  "detected": "unix milliseconds",
+  "unix": { "s": "1718750000", "ms": "1718750000123", "us": "1718750000123000", "ns": "1718750000123000000" },
+  "iso_utc": "2024-06-18T22:33:20.123Z",
+  "iso_local": "2024-06-19T06:33:20.123+08:00",
+  "iso_offset": null,
+  "relative": "2 minutes ago",
+  "rfc2822": "Tue, 18 Jun 2024 22:33:20 +0000"
+}
+```
+
+Exit codes: `0` ok · `2` error (unparseable input, out-of-range date).
+
+## How it works
+
+Date/time handling is a minefield of cross-platform and cross-language
+disagreements, so epochlens does **none** of its conversion through the
+runtime's date library. `datetime.fromisoformat`, `isoformat`, `strftime` (and
+Node's `Date.parse`/`toISOString`) all differ between (and within) the two
+runtimes. Instead every conversion is plain integer arithmetic over a
+proleptic-Gregorian
+[civil-day algorithm](https://howardhinnant.github.io/date_algorithms.html), and
+all formatting is hand-rolled. That's what lets the Node and Python builds stay
+byte-identical, and it's why nanosecond values stay exact (native ints in
+Python, BigInt in Node).
+
+## Scope
+
+The MVP shows UTC, your machine's local time, and any fixed `--offset`. Named
+IANA zones (`--tz America/New_York`) are intentionally left out for now: Python's
+`zoneinfo` needs an OS tz database that Windows lacks, which would break the
+zero-dependency promise. Natural-language *input* (`"3 days ago"`) is also out of
+scope — relative time is shown as output only.
+
+## Install
+
+```bash
+pip install epochlens   # or pipx run epochlens
+npm i -g epochlens      # Node build, identical behaviour
+```
+
+Python ≥ 3.8 or Node ≥ 18. No dependencies.
+
+## License
+
+MIT

epochlens-0.1.0/src/epochlens.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/epochlens/__init__.py
+src/epochlens/__main__.py
+src/epochlens/cli.py
+src/epochlens/core.py
+src/epochlens.egg-info/PKG-INFO
+src/epochlens.egg-info/SOURCES.txt
+src/epochlens.egg-info/dependency_links.txt
+src/epochlens.egg-info/entry_points.txt
+src/epochlens.egg-info/top_level.txt
+tests/test_core.py

epochlens-0.1.0/src/epochlens.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

epochlens-0.1.0/src/epochlens.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+epochlens = epochlens.cli:main

epochlens-0.1.0/src/epochlens.egg-info/top_level.txt

@@ -0,0 +1 @@
+epochlens

epochlens-0.1.0/tests/test_core.py

@@ -0,0 +1,148 @@
+import pytest
+
+from epochlens import core
+
+NOW = 1718750123000  # 2024-06-18T22:35:23Z
+
+
+def ctx(**extra):
+    base = {"rawInput": "x", "detected": "d", "nowMs": NOW, "localOffsetSec": None, "explicitOffset": None}
+    base.update(extra)
+    return base
+
+
+def test_detect_unit_bands():
+    assert core.detect_unit(1718750000) == "s"
+    assert core.detect_unit(99999999999) == "s"
+    assert core.detect_unit(100000000000) == "ms"
+    assert core.detect_unit(1718750000123) == "ms"
+    assert core.detect_unit(100000000000000) == "us"
+    assert core.detect_unit(100000000000000000) == "ns"
+
+
+def test_civil_roundtrip():
+    for days in [-719162, -100000, -1, 0, 1, 19892, 2932896]:
+        y, mo, d = core.civil_from_days(days)
+        assert core.days_from_civil(y, mo, d) == days
+    assert core.days_from_civil(1970, 1, 1) == 0
+    assert core.civil_from_days(0) == (1970, 1, 1)
+
+
+def test_parse_numeric_exact():
+    assert core.parse_input("1718750000")[0] == 1718750000000000000
+    assert core.parse_input("1718750000123")[0] == 1718750000123000000
+    assert core.parse_input("1718750000123456789")[0] == 1718750000123456789
+    assert "unix seconds" in core.parse_input("1718750000")[1]
+    assert "unix milliseconds" in core.parse_input("1718750000123")[1]
+
+
+def test_parse_fraction_separators_sign_forced():
+    assert core.parse_input("1718750000.123")[0] == 1718750000123000000
+    assert core.parse_input("1_718_750_000")[0] == 1718750000000000000
+    assert core.parse_input("1,718,750,000")[0] == 1718750000000000000
+    assert core.parse_input("-100000000")[0] == -100000000000000000
+    assert core.parse_input("1718750000", {"unit": "ms"})[0] == 1718750000000000
+    assert "forced" in core.parse_input("1718750000", {"unit": "ms"})[1]
+
+
+def test_parse_iso_variants():
+    target = 1718750000000000000
+    assert core.parse_input("2024-06-18T22:33:20Z")[0] == target
+    assert core.parse_input("2024-06-18T22:33:20")[0] == target
+    assert core.parse_input("2024-06-18 22:33:20")[0] == target
+    assert core.parse_input("2024-06-19T04:03:20+05:30")[0] == target
+    assert core.parse_input("2024-06-18")[0] == 1718668800000000000
+    assert core.parse_input("2024-06-18T22:33:20.123Z")[0] == 1718750000123000000
+
+
+def test_parse_rfc2822():
+    assert core.parse_input("Tue, 18 Jun 2024 22:33:20 +0000")[0] == 1718750000000000000
+    assert core.parse_input("18 Jun 2024 22:33:20 GMT")[0] == 1718750000000000000
+
+
+def test_parse_now():
+    assert core.parse_input("now", {"nowMs": NOW})[0] == NOW * 1_000_000
+
+
+def test_parse_rejects():
+    with pytest.raises(ValueError, match="unrecognized"):
+        core.parse_input("hello")
+    with pytest.raises(ValueError, match="leap second"):
+        core.parse_input("2016-12-31T23:59:60Z")
+    with pytest.raises(ValueError, match="invalid day"):
+        core.parse_input("2023-02-29T00:00:00Z")
+    with pytest.raises(ValueError, match="invalid month"):
+        core.parse_input("2024-13-01")
+    with pytest.raises(ValueError, match="no input"):
+        core.parse_input("")
+
+
+def test_compute_structure_and_fraction():
+    r = core.compute(1718750000000000000, ctx())
+    assert r["iso_utc"] == "2024-06-18T22:33:20Z"
+    assert r["unix"]["s"] == "1718750000"
+    assert r["unix"]["ns"] == "1718750000000000000"
+    assert r["iso_local"] is None
+    r2 = core.compute(1718750000123000000, ctx())
+    assert r2["iso_utc"] == "2024-06-18T22:33:20.123Z"
+
+
+def test_compute_offset_rows():
+    r = core.compute(1718750000000000000, ctx(localOffsetSec=8 * 3600, explicitOffset={"sec": 5 * 3600 + 30 * 60}))
+    assert r["iso_local"] == "2024-06-19T06:33:20+08:00"
+    assert r["iso_offset"] == "2024-06-19T04:03:20+05:30"
+
+
+def test_compute_epoch0_and_negative():
+    assert core.compute(0, ctx())["iso_utc"] == "1970-01-01T00:00:00Z"
+    assert core.compute(0, ctx())["rfc2822"] == "Thu, 01 Jan 1970 00:00:00 +0000"
+    neg = core.compute(-100000000000000000, ctx())
+    assert neg["iso_utc"] == "1966-10-31T14:13:20Z"
+    assert neg["rfc2822"] == "Mon, 31 Oct 1966 14:13:20 +0000"
+
+
+def test_compute_year_range():
+    with pytest.raises(ValueError, match="out of displayable range"):
+        core.compute(999999999999 * 1_000_000_000, ctx())
+
+
+def test_relative_ladder():
+    r = lambda sec: core.relative(sec * 1000)
+    assert r(0) == "just now"
+    assert r(1) == "1 second ago"
+    assert r(2) == "2 seconds ago"
+    assert r(60) == "1 minute ago"
+    assert r(3600) == "1 hour ago"
+    assert r(86400) == "1 day ago"
+    assert r(2592000) == "1 month ago"
+    assert r(31536000) == "1 year ago"
+    assert r(-1) == "in 1 second"
+    assert r(-7200) == "in 2 hours"
+
+
+def test_iso_offset_formatting():
+    assert core._iso_from_components({"y": 1, "mo": 1, "d": 1, "h": 0, "mi": 0, "s": 0, "ms": 0}) == "0001-01-01T00:00:00"
+    assert core._offset_label(0) == "+00:00"
+    assert core._offset_label(-4 * 3600) == "-04:00"
+    assert core._offset_label(5 * 3600 + 30 * 60) == "+05:30"
+
+
+def test_ascii_only_parsing_rejects_unicode_and_exotic_ws():
+    # Node parity: Python re \d / int() must NOT accept Unicode digits, and strip
+    # must NOT remove NEL/C1/BOM (which JS trim() leaves / removes differently).
+    for bad in ["٤٢", "１２３", "2024-06-18T２２:33:20Z", "1718750000\x85", "1718750000"]:
+        with pytest.raises(ValueError, match="unrecognized"):
+            core.parse_input(bad)
+
+
+def test_trim_ascii_set():
+    assert core.trim_ascii("  1718750000\t\n") == "1718750000"
+    assert core.trim_ascii("1718750000\x85") == "1718750000\x85"   # NEL kept
+    assert core.trim_ascii("1718750000") == "1718750000"  # BOM kept
+
+
+def test_offset_range_validated():
+    with pytest.raises(ValueError, match="out of range"):
+        core.parse_input("2024-06-18T00:00:00+25:00")
+    with pytest.raises(ValueError, match="out of range"):
+        core.parse_input("2024-06-18T00:00:00+05:99")