ts-toolkit 0.1.0__tar.gz

ts_toolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Joye
+
+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.

ts_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: ts-toolkit
+Version: 0.1.0
+Summary: Instant timestamp converter — zero-dependency CLI for epoch ↔ human-readable conversion
+Author-email: Eric Joye <eric@joye.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ts — Instant Timestamp Converter
+
+Zero-dependency CLI tool for bidirectional epoch ↔ human-readable timestamp conversion.
+
+## Install
+
+### Option 1: curl (fastest)
+```bash
+curl -fsSL https://raw.githubusercontent.com/ericjoye/ts-cli/main/ts \
+  -o /usr/local/bin/ts && chmod +x /usr/local/bin/ts
+```
+
+### Option 2: pip
+```bash
+pip install ts-cli
+```
+
+### Option 3: copy
+```bash
+cp ts /usr/local/bin/ts && chmod +x /usr/local/bin/ts
+```
+
+Requires **Python 3.9+** (uses `zoneinfo` from stdlib). No pip dependencies.
+
+## Usage
+
+```bash
+ts                          # Current time: epoch (s/ms/μs) + UTC + local
+ts 1718901234               # Epoch seconds → human
+ts 1718901234000            # Epoch milliseconds → human (auto-detected)
+ts 1718901234000000         # Epoch microseconds → human (auto-detected)
+ts "2024-06-20T14:33:54Z"  # ISO 8601 → epoch
+ts "2024-06-20 14:33:54"   # Human → epoch
+ts now                      # Current epoch in seconds
+ts 1718901234 1718902000    # Batch: multiple timestamps
+cat timestamps.txt | ts --stdin  # Pipe mode
+ts 1718901234 --tz America/New_York  # Convert to timezone
+ts 1718901234 --local       # Convert to local timezone
+```
+
+## Features
+
+- **Auto-detection**: Distinguishes seconds (≤10 digits), milliseconds (11–13), microseconds (16+)
+- **Bidirectional**: Epoch → human AND human → epoch
+- **ISO 8601**: Full support for `YYYY-MM-DDTHH:MM:SSZ` and variants
+- **Timezone support**: `--tz IANA_NAME` or `--local` for system timezone
+- **Batch mode**: Multiple args or `--stdin` pipe
+- **Zero dependencies**: Single Python file, stdlib only
+
+## Running tests
+
+```bash
+pip install pytest
+pytest test_ts.py -v
+```
+
+## License
+
+MIT

ts_toolkit-0.1.0/README.md

@@ -0,0 +1,59 @@
+# ts — Instant Timestamp Converter
+
+Zero-dependency CLI tool for bidirectional epoch ↔ human-readable timestamp conversion.
+
+## Install
+
+### Option 1: curl (fastest)
+```bash
+curl -fsSL https://raw.githubusercontent.com/ericjoye/ts-cli/main/ts \
+  -o /usr/local/bin/ts && chmod +x /usr/local/bin/ts
+```
+
+### Option 2: pip
+```bash
+pip install ts-cli
+```
+
+### Option 3: copy
+```bash
+cp ts /usr/local/bin/ts && chmod +x /usr/local/bin/ts
+```
+
+Requires **Python 3.9+** (uses `zoneinfo` from stdlib). No pip dependencies.
+
+## Usage
+
+```bash
+ts                          # Current time: epoch (s/ms/μs) + UTC + local
+ts 1718901234               # Epoch seconds → human
+ts 1718901234000            # Epoch milliseconds → human (auto-detected)
+ts 1718901234000000         # Epoch microseconds → human (auto-detected)
+ts "2024-06-20T14:33:54Z"  # ISO 8601 → epoch
+ts "2024-06-20 14:33:54"   # Human → epoch
+ts now                      # Current epoch in seconds
+ts 1718901234 1718902000    # Batch: multiple timestamps
+cat timestamps.txt | ts --stdin  # Pipe mode
+ts 1718901234 --tz America/New_York  # Convert to timezone
+ts 1718901234 --local       # Convert to local timezone
+```
+
+## Features
+
+- **Auto-detection**: Distinguishes seconds (≤10 digits), milliseconds (11–13), microseconds (16+)
+- **Bidirectional**: Epoch → human AND human → epoch
+- **ISO 8601**: Full support for `YYYY-MM-DDTHH:MM:SSZ` and variants
+- **Timezone support**: `--tz IANA_NAME` or `--local` for system timezone
+- **Batch mode**: Multiple args or `--stdin` pipe
+- **Zero dependencies**: Single Python file, stdlib only
+
+## Running tests
+
+```bash
+pip install pytest
+pytest test_ts.py -v
+```
+
+## License
+
+MIT

ts_toolkit-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ts-toolkit"
+version = "0.1.0"
+description = "Instant timestamp converter — zero-dependency CLI for epoch ↔ human-readable conversion"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Eric Joye", email = "eric@joye.com"},
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Utilities",
+]
+
+[project.scripts]
+ts = "ts:main"
+
+[tool.setuptools]
+py-modules = ["ts"]

ts_toolkit-0.1.0/setup.cfg

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

ts_toolkit-0.1.0/ts.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""ts — Instant timestamp converter for developers.
+
+Zero-dependency CLI tool for bidirectional epoch ↔ human-readable
+timestamp conversion. Auto-detects seconds, milliseconds, and microseconds.
+"""
+
+import argparse
+import sys
+import time
+from datetime import datetime, timezone, timedelta
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+
+# ---------------------------------------------------------------------------
+# Epoch detection helpers
+# ---------------------------------------------------------------------------
+
+def detect_epoch_unit(value: int) -> str:
+    """Return 's', 'ms', or 'us' based on digit-length heuristics."""
+    digits = len(str(abs(value)))
+    if digits <= 10:
+        return "s"
+    elif digits <= 13:
+        return "ms"
+    else:
+        return "us"
+
+
+def epoch_to_dt(value: int, tz: ZoneInfo | None = None) -> datetime:
+    """Convert an epoch value to a timezone-aware datetime (UTC base)."""
+    unit = detect_epoch_unit(value)
+    if unit == "s":
+        dt = datetime.fromtimestamp(value, tz=timezone.utc)
+    elif unit == "ms":
+        dt = datetime.fromtimestamp(value / 1000, tz=timezone.utc)
+    else:
+        dt = datetime.fromtimestamp(value / 1_000_000, tz=timezone.utc)
+    if tz is not None:
+        dt = dt.astimezone(tz)
+    return dt
+
+
+# ---------------------------------------------------------------------------
+# Human-readable → epoch parsing
+# ---------------------------------------------------------------------------
+
+def parse_human_to_epoch(text: str, tz: ZoneInfo | None = None) -> int:
+    """Parse a human-readable datetime string and return epoch seconds.
+
+    Supports: ISO 8601, common date/datetime formats, and the keyword 'now'.
+    """
+    text = text.strip()
+
+    if text.lower() == "now":
+        return int(time.time())
+
+    # Ordered list of formats to try
+    formats = [
+        "%Y-%m-%dT%H:%M:%S%z",
+        "%Y-%m-%dT%H:%M:%S.%f%z",
+        "%Y-%m-%dT%H:%M:%SZ",
+        "%Y-%m-%dT%H:%M:%S.%fZ",
+        "%Y-%m-%dT%H:%M:%S",
+        "%Y-%m-%dT%H:%M:%S.%f",
+        "%Y-%m-%d %H:%M:%S",
+        "%Y-%m-%d %H:%M:%S.%f",
+        "%Y-%m-%d",
+    ]
+
+    dt: datetime | None = None
+    for fmt in formats:
+        try:
+            dt = datetime.strptime(text, fmt)
+            break
+        except ValueError:
+            continue
+
+    if dt is None:
+        raise ValueError(f"Cannot parse datetime: {text!r}")
+
+    # If no timezone info, treat as UTC unless --tz / --local was given
+    if dt.tzinfo is None:
+        if tz is not None:
+            dt = dt.replace(tzinfo=tz)
+        else:
+            dt = dt.replace(tzinfo=timezone.utc)
+
+    return int(dt.timestamp())
+
+
+# ---------------------------------------------------------------------------
+# Formatting helpers
+# ---------------------------------------------------------------------------
+
+def fmt_utc(dt: datetime) -> str:
+    """Return 'YYYY-MM-DD HH:MM:SS UTC'."""
+    utc_dt = dt.astimezone(timezone.utc)
+    return utc_dt.strftime("%Y-%m-%d %H:%M:%S UTC")
+
+
+def fmt_tz(dt: datetime) -> str:
+    """Return 'YYYY-MM-DD HH:MM:SS <TZ_NAME>'."""
+    tzname = dt.tzinfo.tzname(dt) if hasattr(dt.tzinfo, "tzname") else str(dt.tzinfo)
+    return dt.strftime(f"%Y-%m-%d %H:%M:%S {tzname}")
+
+
+# ---------------------------------------------------------------------------
+# Core conversion logic
+# ---------------------------------------------------------------------------
+
+def convert_one(token: str, tz: ZoneInfo | None = None) -> str:
+    """Convert a single token (epoch int or human string) and return a display line."""
+    token = token.strip()
+    if not token:
+        return ""
+
+    # Try integer epoch first
+    try:
+        value = int(token)
+    except ValueError:
+        pass
+    else:
+        unit = detect_epoch_unit(value)
+        dt = epoch_to_dt(value, tz=tz)
+        if tz is not None:
+            return f"{token} → {fmt_tz(dt)}"
+        return f"{token} → {fmt_utc(dt)}"
+
+    # Human-readable → epoch
+    try:
+        epoch_s = parse_human_to_epoch(token, tz=tz)
+    except ValueError:
+        return f"{token} → ERROR: unrecognised format"
+
+    if tz is not None:
+        dt = datetime.fromtimestamp(epoch_s, tz=tz)
+        return f"{token} → {epoch_s} ({fmt_tz(dt)})"
+    dt = datetime.fromtimestamp(epoch_s, tz=timezone.utc)
+    return f"{token} → {epoch_s} ({fmt_utc(dt)})"
+
+
+def show_current(tz: ZoneInfo | None = None) -> list[str]:
+    """Return lines describing the current time."""
+    now = time.time()
+    epoch_s = int(now)
+    epoch_ms = int(now * 1000)
+    epoch_us = int(now * 1_000_000)
+    lines = [
+        f"Epoch s : {epoch_s}",
+        f"Epoch ms: {epoch_ms}",
+        f"Epoch μs: {epoch_us}",
+    ]
+    dt_utc = datetime.fromtimestamp(now, tz=timezone.utc)
+    lines.append(f"UTC     : {fmt_utc(dt_utc)}")
+
+    if tz is not None:
+        dt_tz = datetime.fromtimestamp(now, tz=tz)
+        lines.append(f"{tz.key}: {fmt_tz(dt_tz)}")
+    else:
+        # Show local time
+        dt_local = datetime.fromtimestamp(now)
+        local_tz = dt_local.astimezone().tzinfo
+        local_name = local_tz.tzname(dt_local) if hasattr(local_tz, "tzname") else str(local_tz)
+        lines.append(f"Local   : {dt_local.strftime('%Y-%m-%d %H:%M:%S')} {local_name}")
+
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ts",
+        description="Instant timestamp converter — epoch ↔ human-readable",
+        epilog="Examples:\n  ts\n  ts 1718901234\n  ts 1718901234000 --tz America/New_York\n  ts 2024-06-20T14:33:54Z\n  ts now\n  ts 1718901234 1718902000\n  cat timestamps.txt | ts --stdin\n",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "values",
+        nargs="*",
+        help="Timestamp(s) to convert: epoch int, ISO date, or 'now'",
+    )
+    parser.add_argument(
+        "--tz",
+        metavar="TZ",
+        default=None,
+        help="Target timezone (e.g. America/New_York, Europe/London)",
+    )
+    parser.add_argument(
+        "--local",
+        action="store_true",
+        default=False,
+        help="Use system local timezone (overrides --tz)",
+    )
+    parser.add_argument(
+        "--stdin",
+        action="store_true",
+        default=False,
+        help="Read timestamps from stdin (one per line)",
+    )
+    return parser
+
+
+def resolve_tz(args) -> ZoneInfo | None:
+    """Return the ZoneInfo to use, or None for UTC."""
+    if args.local:
+        # Derive local timezone
+        local_dt = datetime.now().astimezone()
+        tzinfo = local_dt.tzinfo
+        if isinstance(tzinfo, ZoneInfo):
+            return tzinfo
+        # Fallback: try common resolution via time module
+        try:
+            local_tz_name = time.tzname[0]
+            # Not all names are IANA — best effort
+            return ZoneInfo(local_tz_name)
+        except (ZoneInfoNotFoundError, Exception):
+            # Last resort: fixed offset
+            offset = timedelta(seconds=-time.timezone if time.daylight == 0 else -time.altzone)
+            # Can't make a ZoneInfo from fixed offset easily; return UTC
+            return None
+    if args.tz:
+        try:
+            return ZoneInfo(args.tz)
+        except ZoneInfoNotFoundError:
+            print(f"ERROR: unknown timezone {args.tz!r}", file=sys.stderr)
+            sys.exit(1)
+    return None
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    tz = resolve_tz(args)
+
+    # No args → show current time
+    if not args.values and not args.stdin:
+        for line in show_current(tz):
+            print(line)
+        return
+
+    # Collect tokens
+    tokens: list[str] = []
+    if args.stdin:
+        for line in sys.stdin:
+            stripped = line.strip()
+            if stripped:
+                tokens.append(stripped)
+    tokens.extend(args.values)
+
+    if not tokens:
+        parser.print_help()
+        sys.exit(1)
+
+    for token in tokens:
+        result = convert_one(token, tz=tz)
+        if result:
+            print(result)
+
+
+if __name__ == "__main__":
+    main()

ts_toolkit-0.1.0/ts_toolkit.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: ts-toolkit
+Version: 0.1.0
+Summary: Instant timestamp converter — zero-dependency CLI for epoch ↔ human-readable conversion
+Author-email: Eric Joye <eric@joye.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ts — Instant Timestamp Converter
+
+Zero-dependency CLI tool for bidirectional epoch ↔ human-readable timestamp conversion.
+
+## Install
+
+### Option 1: curl (fastest)
+```bash
+curl -fsSL https://raw.githubusercontent.com/ericjoye/ts-cli/main/ts \
+  -o /usr/local/bin/ts && chmod +x /usr/local/bin/ts
+```
+
+### Option 2: pip
+```bash
+pip install ts-cli
+```
+
+### Option 3: copy
+```bash
+cp ts /usr/local/bin/ts && chmod +x /usr/local/bin/ts
+```
+
+Requires **Python 3.9+** (uses `zoneinfo` from stdlib). No pip dependencies.
+
+## Usage
+
+```bash
+ts                          # Current time: epoch (s/ms/μs) + UTC + local
+ts 1718901234               # Epoch seconds → human
+ts 1718901234000            # Epoch milliseconds → human (auto-detected)
+ts 1718901234000000         # Epoch microseconds → human (auto-detected)
+ts "2024-06-20T14:33:54Z"  # ISO 8601 → epoch
+ts "2024-06-20 14:33:54"   # Human → epoch
+ts now                      # Current epoch in seconds
+ts 1718901234 1718902000    # Batch: multiple timestamps
+cat timestamps.txt | ts --stdin  # Pipe mode
+ts 1718901234 --tz America/New_York  # Convert to timezone
+ts 1718901234 --local       # Convert to local timezone
+```
+
+## Features
+
+- **Auto-detection**: Distinguishes seconds (≤10 digits), milliseconds (11–13), microseconds (16+)
+- **Bidirectional**: Epoch → human AND human → epoch
+- **ISO 8601**: Full support for `YYYY-MM-DDTHH:MM:SSZ` and variants
+- **Timezone support**: `--tz IANA_NAME` or `--local` for system timezone
+- **Batch mode**: Multiple args or `--stdin` pipe
+- **Zero dependencies**: Single Python file, stdlib only
+
+## Running tests
+
+```bash
+pip install pytest
+pytest test_ts.py -v
+```
+
+## License
+
+MIT

ts_toolkit-0.1.0/ts_toolkit.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+ts.py
+ts_toolkit.egg-info/PKG-INFO
+ts_toolkit.egg-info/SOURCES.txt
+ts_toolkit.egg-info/dependency_links.txt
+ts_toolkit.egg-info/entry_points.txt
+ts_toolkit.egg-info/top_level.txt

ts_toolkit-0.1.0/ts_toolkit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ts_toolkit-0.1.0/ts_toolkit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ts = ts:main

ts_toolkit-0.1.0/ts_toolkit.egg-info/top_level.txt

@@ -0,0 +1 @@
+ts