polytool 0.1.0__py3-none-any.whl

polytool/__init__.py

@@ -0,0 +1,4 @@
+"""polytool — one-binary CLI bundling 26 everyday utilities."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

polytool/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m polytool` invocation."""
+
+from polytool.cli import app
+
+if __name__ == "__main__":
+    app()

polytool/cli/__init__.py

@@ -0,0 +1,82 @@
+"""Root Typer app — subcommand groups are added by their own modules.
+
+Subcommand modules must keep top-level imports light (typer/rich/stdlib only).
+Heavy imports (Pillow, ffmpeg, rembg) happen inside command bodies via
+`polytool.core.lazy.require_extra`.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from polytool import __version__
+from polytool.cli import (
+    clip,
+    color,
+    convert,
+    cron,
+    data,
+    dl,
+    enc,
+    file,
+    gen,
+    img,
+    net,
+    pdf,
+    qr,
+    shot,
+    text,
+    vid,
+)
+from polytool.core.errors import install_excepthook
+
+install_excepthook()
+
+app = typer.Typer(
+    name="polytool",
+    help="polytool — one-binary CLI bundling 26 everyday utilities (pt for short).",
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"polytool {__version__}")
+        raise typer.Exit
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """polytool — one-binary CLI bundling 26 everyday utilities."""
+
+
+app.add_typer(enc.app, name="enc")
+app.add_typer(gen.app, name="gen")
+app.add_typer(color.app, name="color")
+app.add_typer(convert.app, name="convert")
+app.add_typer(text.app, name="text")
+app.add_typer(data.app, name="data")
+app.add_typer(qr.app, name="qr")
+app.add_typer(clip.app, name="clip")
+app.add_typer(cron.app, name="cron")
+app.add_typer(net.app, name="net")
+app.add_typer(file.app, name="file")
+app.add_typer(img.app, name="img")
+app.add_typer(pdf.app, name="pdf")
+app.add_typer(vid.app, name="vid")
+app.add_typer(dl.app, name="dl")
+app.add_typer(shot.app, name="shot")
+
+
+__all__ = ["app"]

polytool/cli/clip.py

@@ -0,0 +1,71 @@
+"""Clipboard read/write."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from polytool.core.errors import PolytoolError
+from polytool.core.io import read_text
+
+app = typer.Typer(
+    name="clip",
+    help="Clipboard read/write.",
+    no_args_is_help=True,
+)
+
+
+def _pyperclip():
+    try:
+        import pyperclip  # type: ignore
+
+        return pyperclip
+    except ImportError as exc:  # pragma: no cover
+        raise PolytoolError(
+            "pyperclip is missing.",
+            hint="Reinstall polytool to restore base deps.",
+        ) from exc
+
+
+@app.command("copy")
+def cmd_copy(
+    text: Annotated[str | None, typer.Argument(help="Text (or omit to read stdin).")] = None,
+) -> None:
+    """Copy text to the system clipboard.
+
+    Examples:
+
+        pt clip copy "hello"
+        cat secret.txt | pt clip copy
+    """
+    payload = text if text is not None else read_text(None).rstrip("\n")
+    pc = _pyperclip()
+    try:
+        pc.copy(payload)
+    except pc.PyperclipException as exc:
+        raise PolytoolError(
+            f"Clipboard not available: {exc}",
+            hint="On Linux, install xclip or xsel: 'apt install xclip'.",
+        ) from exc
+    typer.echo(f"Copied {len(payload)} chars.", err=True)
+
+
+@app.command("paste")
+def cmd_paste() -> None:
+    """Print the clipboard contents to stdout.
+
+    Examples:
+
+        pt clip paste
+        pt clip paste > out.txt
+    """
+    pc = _pyperclip()
+    try:
+        text = pc.paste()
+    except pc.PyperclipException as exc:
+        raise PolytoolError(
+            f"Clipboard not available: {exc}",
+            hint="On Linux, install xclip or xsel: 'apt install xclip'.",
+        ) from exc
+    typer.echo(text, nl=False)

polytool/cli/color.py

@@ -0,0 +1,125 @@
+"""Color converter (hex / rgb / hsl / hsv / cmyk)."""
+
+from __future__ import annotations
+
+import colorsys
+import re
+from typing import Annotated
+
+import typer
+
+from polytool.core.errors import PolytoolError
+
+app = typer.Typer(
+    name="color",
+    help="Convert colors between hex, rgb, hsl, hsv, cmyk.",
+    no_args_is_help=True,
+)
+
+HEX_RE = re.compile(r"^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$")
+RGB_RE = re.compile(r"^rgba?\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)")
+HSL_RE = re.compile(
+    r"^hsla?\s*\(\s*(\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?)\s*%\s*,\s*(\d+(?:\.\d+)?)\s*%"
+)
+HSV_RE = re.compile(
+    r"^hsva?\s*\(\s*(\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?)\s*%\s*,\s*(\d+(?:\.\d+)?)\s*%"
+)
+
+
+def _parse(spec: str) -> tuple[float, float, float]:
+    """Parse any supported color spec into normalized 0..1 RGB."""
+    s = spec.strip()
+    m = HEX_RE.match(s)
+    if m:
+        h = m.group(1)
+        if len(h) == 3:
+            h = "".join(c * 2 for c in h)
+        r = int(h[0:2], 16) / 255
+        g = int(h[2:4], 16) / 255
+        b = int(h[4:6], 16) / 255
+        return r, g, b
+    m = RGB_RE.match(s)
+    if m:
+        return int(m.group(1)) / 255, int(m.group(2)) / 255, int(m.group(3)) / 255
+    m = HSL_RE.match(s)
+    if m:
+        h = float(m.group(1)) / 360
+        l_ = float(m.group(3)) / 100
+        sat = float(m.group(2)) / 100
+        r, g, b = colorsys.hls_to_rgb(h, l_, sat)
+        return r, g, b
+    m = HSV_RE.match(s)
+    if m:
+        h = float(m.group(1)) / 360
+        sat = float(m.group(2)) / 100
+        v = float(m.group(3)) / 100
+        r, g, b = colorsys.hsv_to_rgb(h, sat, v)
+        return r, g, b
+    raise PolytoolError(
+        f"Could not parse color {spec!r}",
+        hint="Try forms like #3366ff, rgb(51,102,255), hsl(220,100%,60%).",
+    )
+
+
+def _to_hex(r: float, g: float, b: float) -> str:
+    return f"#{int(r * 255):02x}{int(g * 255):02x}{int(b * 255):02x}"
+
+
+def _to_rgb(r: float, g: float, b: float) -> str:
+    return f"rgb({int(r * 255)}, {int(g * 255)}, {int(b * 255)})"
+
+
+def _to_hsl(r: float, g: float, b: float) -> str:
+    h, l_, s = colorsys.rgb_to_hls(r, g, b)
+    return f"hsl({h * 360:.0f}, {s * 100:.0f}%, {l_ * 100:.0f}%)"
+
+
+def _to_hsv(r: float, g: float, b: float) -> str:
+    h, s, v = colorsys.rgb_to_hsv(r, g, b)
+    return f"hsv({h * 360:.0f}, {s * 100:.0f}%, {v * 100:.0f}%)"
+
+
+def _to_cmyk(r: float, g: float, b: float) -> str:
+    k = 1 - max(r, g, b)
+    if k >= 1:
+        return "cmyk(0%, 0%, 0%, 100%)"
+    c = (1 - r - k) / (1 - k)
+    m = (1 - g - k) / (1 - k)
+    y = (1 - b - k) / (1 - k)
+    return f"cmyk({c * 100:.0f}%, {m * 100:.0f}%, {y * 100:.0f}%, {k * 100:.0f}%)"
+
+
+@app.command("convert")
+def cmd_convert(
+    spec: Annotated[str, typer.Argument(help="Color in hex, rgb(...), hsl(...), or hsv(...).")],
+    to: Annotated[
+        str, typer.Option("--to", "-t", help="hex | rgb | hsl | hsv | cmyk | all")
+    ] = "all",
+) -> None:
+    """Convert a color between formats.
+
+    Examples:
+
+        pt color convert "#3366ff"
+        pt color convert "rgb(51,102,255)" --to hsl
+        pt color convert "hsl(220,100%,60%)" --to cmyk
+    """
+    r, g, b = _parse(spec)
+    converters = {
+        "hex": _to_hex,
+        "rgb": _to_rgb,
+        "hsl": _to_hsl,
+        "hsv": _to_hsv,
+        "cmyk": _to_cmyk,
+    }
+    if to == "all":
+        for name, fn in converters.items():
+            typer.echo(f"{name:5} {fn(r, g, b)}")
+    else:
+        fn = converters.get(to.lower())
+        if fn is None:
+            raise PolytoolError(
+                f"Unknown target {to!r}",
+                hint=f"One of: {', '.join(converters)}",
+            )
+        typer.echo(fn(r, g, b))

polytool/cli/convert.py

@@ -0,0 +1,151 @@
+"""Unit / timestamp / number-base converter."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from polytool.core.errors import PolytoolError
+
+app = typer.Typer(
+    name="convert",
+    help="Unit, timestamp, number-base converters.",
+    no_args_is_help=True,
+)
+
+
+@app.command("unit")
+def cmd_unit(
+    value: Annotated[str, typer.Argument(help="Value with unit, e.g. '100 km' or '3 hours'.")],
+    to: Annotated[str, typer.Option("--to", "-t", help="Target unit, e.g. 'mi'.")],
+) -> None:
+    """Convert physical units (length, mass, time, temperature, ...).
+
+    Examples:
+
+        pt convert unit "100 km" --to mi
+        pt convert unit "20 degC" --to degF
+        pt convert unit "5 hours" --to seconds
+    """
+    import pint
+
+    ureg = pint.UnitRegistry()
+    ureg.autoconvert_offset_to_baseunit = True
+    try:
+        q = ureg.Quantity(value)
+        result = q.to(to)
+    except Exception as exc:
+        raise PolytoolError(
+            f"Could not convert {value!r} to {to!r}: {exc}",
+            hint="Try units like 'km', 'mi', 'kg', 'lb', 'celsius', 'fahrenheit'.",
+        ) from exc
+    typer.echo(f"{result:.4f~P}")
+
+
+@app.command("timestamp")
+def cmd_timestamp(
+    value: Annotated[str, typer.Argument(help="Unix epoch (sec or ms) or ISO datetime.")],
+    to: Annotated[
+        str, typer.Option("--to", "-t", help="Target: 'iso', 'epoch', 'epoch-ms', 'rfc822'")
+    ] = "iso",
+) -> None:
+    """Convert between epoch seconds/ms and ISO 8601 / RFC 822.
+
+    Examples:
+
+        pt convert timestamp 1715200000
+        pt convert timestamp 1715200000000 --to iso
+        pt convert timestamp "2025-04-08T20:26:40Z" --to epoch
+    """
+    from datetime import UTC, datetime
+
+    from dateutil import parser as dt_parser
+
+    dt: datetime
+    s = value.strip()
+    if s.lstrip("-").isdigit():
+        n = int(s)
+        if abs(n) > 10**12:  # ms heuristic
+            dt = datetime.fromtimestamp(n / 1000, tz=UTC)
+        else:
+            dt = datetime.fromtimestamp(n, tz=UTC)
+    else:
+        try:
+            dt = dt_parser.parse(s)
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=UTC)
+        except Exception as exc:
+            raise PolytoolError(f"Could not parse {value!r}") from exc
+
+    out = to.lower()
+    if out == "iso":
+        typer.echo(dt.isoformat())
+    elif out == "epoch":
+        typer.echo(str(int(dt.timestamp())))
+    elif out == "epoch-ms":
+        typer.echo(str(int(dt.timestamp() * 1000)))
+    elif out == "rfc822":
+        typer.echo(dt.strftime("%a, %d %b %Y %H:%M:%S %z"))
+    else:
+        raise PolytoolError(
+            f"Unknown target {to!r}",
+            hint="One of: iso, epoch, epoch-ms, rfc822",
+        )
+
+
+@app.command("base")
+def cmd_base(
+    value: Annotated[
+        str,
+        typer.Argument(help="Number in current base (use 0x/0b/0o prefix or --from)."),
+    ],
+    to: Annotated[
+        str,
+        typer.Option("--to", "-t", help="Target base: 2, 8, 10, 16 (or bin/oct/dec/hex)"),
+    ] = "10",
+    from_: Annotated[
+        str | None,
+        typer.Option("--from", "-f", help="Source base (default: auto-detect)"),
+    ] = None,
+) -> None:
+    """Convert numbers between bases (binary, octal, decimal, hex).
+
+    Examples:
+
+        pt convert base 0xff --to 10
+        pt convert base 255 --to hex
+        pt convert base 11111111 --from 2 --to dec
+    """
+    bases = {"2": 2, "bin": 2, "8": 8, "oct": 8, "10": 10, "dec": 10, "16": 16, "hex": 16}
+    target = bases.get(to.lower())
+    if target is None:
+        raise PolytoolError(
+            f"Unknown target base {to!r}", hint="One of: 2/bin, 8/oct, 10/dec, 16/hex"
+        )
+
+    if from_ is None:
+        try:
+            n = int(value, 0)
+        except ValueError as exc:
+            raise PolytoolError(
+                f"Could not parse {value!r}",
+                hint="Pass --from or use 0x/0b/0o prefix.",
+            ) from exc
+    else:
+        src = bases.get(from_.lower())
+        if src is None:
+            raise PolytoolError(f"Unknown source base {from_!r}")
+        try:
+            n = int(value, src)
+        except ValueError as exc:
+            raise PolytoolError(f"{value!r} is not a base-{src} number") from exc
+
+    if target == 2:
+        typer.echo(bin(n)[2:] if n >= 0 else "-" + bin(-n)[2:])
+    elif target == 8:
+        typer.echo(oct(n)[2:] if n >= 0 else "-" + oct(-n)[2:])
+    elif target == 10:
+        typer.echo(str(n))
+    elif target == 16:
+        typer.echo(hex(n)[2:] if n >= 0 else "-" + hex(-n)[2:])

polytool/cli/cron.py

@@ -0,0 +1,60 @@
+"""Cron expression explainer."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from polytool.core.errors import PolytoolError
+
+app = typer.Typer(
+    name="cron",
+    help="Cron expression explainer.",
+    no_args_is_help=True,
+)
+
+
+@app.command("explain")
+def cmd_explain(
+    expression: Annotated[str, typer.Argument(help="Cron expression, e.g. '0 9 * * MON'")],
+) -> None:
+    """Render a cron expression in plain English.
+
+    Examples:
+
+        pt cron explain "0 9 * * MON"
+        pt cron explain "*/5 * * * *"
+    """
+    from cron_descriptor import ExpressionDescriptor
+
+    try:
+        descr = str(ExpressionDescriptor(expression))
+    except Exception as exc:
+        raise PolytoolError(f"Invalid cron expression: {exc}") from exc
+    typer.echo(descr)
+
+
+@app.command("next")
+def cmd_next(
+    expression: Annotated[str, typer.Argument(help="Cron expression")],
+    count: Annotated[int, typer.Option("--count", "-n", help="How many runs to show")] = 5,
+) -> None:
+    """Show the next N firing times of a cron schedule (UTC).
+
+    Examples:
+
+        pt cron next "0 9 * * MON" --count 3
+    """
+    from datetime import UTC, datetime
+
+    from croniter import croniter
+
+    try:
+        it = croniter(expression, datetime.now(UTC))
+    except Exception as exc:
+        raise PolytoolError(f"Invalid cron expression: {exc}") from exc
+
+    for _ in range(count):
+        nxt = it.get_next(datetime)
+        typer.echo(nxt.isoformat())

polytool/cli/data.py

@@ -0,0 +1,188 @@
+"""Data format converter (json / yaml / toml / csv / xml)."""
+
+from __future__ import annotations
+
+import csv as _csv
+import io
+import json as _json
+import tomllib
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from polytool.core.errors import PolytoolError
+from polytool.core.io import read_text, write_text
+
+app = typer.Typer(
+    name="data",
+    help="Data format converter (json/yaml/toml/csv/xml).",
+    no_args_is_help=True,
+)
+
+FORMATS = ("json", "yaml", "yml", "toml", "csv", "xml")
+
+
+def _detect_format(path: Path | None, hint: str | None) -> str:
+    if hint:
+        h = hint.lower()
+        if h not in FORMATS:
+            raise PolytoolError(
+                f"Unknown format {hint!r}",
+                hint=f"One of: {', '.join(FORMATS)}",
+            )
+        return "yaml" if h == "yml" else h
+    if path is None:
+        raise PolytoolError(
+            "Cannot detect format from stdin",
+            hint="Pass --from json|yaml|toml|csv|xml.",
+        )
+    suffix = path.suffix.lstrip(".").lower()
+    if suffix in {"yml"}:
+        return "yaml"
+    if suffix in FORMATS:
+        return suffix
+    raise PolytoolError(
+        f"Cannot detect format from extension {suffix!r}",
+        hint="Pass --from explicitly.",
+    )
+
+
+def _load(text: str, fmt: str) -> Any:
+    if fmt == "json":
+        return _json.loads(text)
+    if fmt == "yaml":
+        from ruamel.yaml import YAML
+
+        return YAML(typ="safe").load(io.StringIO(text))
+    if fmt == "toml":
+        return tomllib.loads(text)
+    if fmt == "csv":
+        reader = _csv.DictReader(io.StringIO(text))
+        return list(reader)
+    if fmt == "xml":
+        import xmltodict
+
+        return xmltodict.parse(text)
+    raise PolytoolError(f"Unsupported format: {fmt}")
+
+
+def _dump(data: Any, fmt: str, *, pretty: bool = True) -> str:
+    if fmt == "json":
+        return _json.dumps(data, indent=2 if pretty else None, ensure_ascii=False) + "\n"
+    if fmt == "yaml":
+        from ruamel.yaml import YAML
+
+        y = YAML()
+        y.default_flow_style = False
+        buf = io.StringIO()
+        y.dump(data, buf)
+        return buf.getvalue()
+    if fmt == "toml":
+        import tomli_w
+
+        if not isinstance(data, dict):
+            raise PolytoolError(
+                "TOML output requires a top-level mapping",
+                hint='Wrap your list in a key, e.g. {"items": [...]}.',
+            )
+        return tomli_w.dumps(data)
+    if fmt == "csv":
+        if not isinstance(data, list):
+            raise PolytoolError(
+                "CSV output requires a list of records",
+                hint="Wrap your value in a JSON array of objects.",
+            )
+        if not data:
+            return ""
+        if not isinstance(data[0], dict):
+            raise PolytoolError("CSV output requires a list of dicts")
+        buf = io.StringIO(newline="")
+        writer = _csv.DictWriter(buf, fieldnames=list(data[0].keys()))
+        writer.writeheader()
+        writer.writerows(data)
+        return buf.getvalue()
+    if fmt == "xml":
+        import xmltodict
+
+        if not isinstance(data, dict):
+            raise PolytoolError(
+                "XML output requires a top-level mapping",
+                hint='Wrap data: {"root": {...}}',
+            )
+        return xmltodict.unparse(data, pretty=pretty)
+    raise PolytoolError(f"Unsupported format: {fmt}")
+
+
+@app.command("convert")
+def cmd_convert(
+    source: Annotated[
+        Path | None, typer.Argument(help="Source file (or '-' / omit for stdin)")
+    ] = None,
+    to: Annotated[str, typer.Option("--to", "-t", help="Target: json|yaml|toml|csv|xml")] = "json",
+    from_: Annotated[
+        str | None,
+        typer.Option("--from", "-f", help="Source format (default: from extension)"),
+    ] = None,
+    output: Annotated[
+        Path | None, typer.Option("--output", "-o", help="Output file (default: stdout)")
+    ] = None,
+) -> None:
+    """Convert between JSON / YAML / TOML / CSV / XML.
+
+    Examples:
+
+        pt data convert config.yaml --to json
+        pt data convert data.csv --to json --output data.json
+        cat x.toml | pt data convert --from toml --to yaml
+    """
+    src_fmt = _detect_format(source, from_)
+    tgt_fmt = to.lower()
+    if tgt_fmt == "yml":
+        tgt_fmt = "yaml"
+    if tgt_fmt not in FORMATS:
+        raise PolytoolError(f"Unknown target {to!r}", hint=f"One of: {', '.join(FORMATS)}")
+    text = read_text(source)
+    data = _load(text, src_fmt)
+    write_text(output, _dump(data, tgt_fmt))
+
+
+@app.command("pretty")
+def cmd_pretty(
+    source: Annotated[Path | None, typer.Argument(help="File (or '-' / omit for stdin)")] = None,
+    from_: Annotated[
+        str | None, typer.Option("--from", "-f", help="Format (default: from extension)")
+    ] = None,
+) -> None:
+    """Pretty-print structured data in its current format.
+
+    Examples:
+
+        pt data pretty messy.json
+        cat x.yaml | pt data pretty --from yaml
+    """
+    fmt = _detect_format(source, from_)
+    data = _load(read_text(source), fmt)
+    typer.echo(_dump(data, fmt, pretty=True), nl=False)
+
+
+@app.command("validate")
+def cmd_validate(
+    source: Annotated[Path | None, typer.Argument(help="File (or '-' / omit for stdin)")] = None,
+    from_: Annotated[
+        str | None, typer.Option("--from", "-f", help="Format (default: from extension)")
+    ] = None,
+) -> None:
+    """Validate that a file parses cleanly. Exit 0 = valid, 1 = invalid.
+
+    Examples:
+
+        pt data validate config.yaml
+        cat suspect.json | pt data validate --from json
+    """
+    fmt = _detect_format(source, from_)
+    try:
+        _load(read_text(source), fmt)
+    except Exception as exc:
+        raise PolytoolError(f"Invalid {fmt}: {exc}") from exc
+    typer.echo(f"OK ({fmt})")