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
