html-previewer 0.1.1__py3-none-any.whl

html_previewer/__init__.py

@@ -0,0 +1,15 @@
+"""Cross-platform client for the html-previewer ephemeral preview service."""
+from .client import (PreviewClient, PreviewError, build_zip, default_topic,
+                     parse_expiry, slugify_topic)
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "PreviewClient",
+    "PreviewError",
+    "build_zip",
+    "default_topic",
+    "parse_expiry",
+    "slugify_topic",
+    "__version__",
+]

html_previewer/__main__.py

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

html_previewer/cli.py

@@ -0,0 +1,290 @@
+"""Command-line interface: the ``preview-publish`` command.
+
+Mirrors the interface of the classic ``client/preview-publish.sh`` so muscle
+memory carries over, and adds the remaining API endpoints (--info, --expiry,
+--health, --save-config) plus --open and --json.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+import webbrowser
+from pathlib import Path
+
+from . import __version__
+from .client import PreviewClient, PreviewError, parse_expiry
+from .config import resolve, save_config
+
+PROG = "preview-publish"
+
+
+def _print_json(payload) -> None:
+    print(json.dumps(payload, indent=2, ensure_ascii=False))
+
+
+def _fmt_size(n) -> str:
+    try:
+        n = float(n)
+    except (TypeError, ValueError):
+        return "?"
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if n < 1024 or unit == "TB":
+            return f"{n:.0f} {unit}" if unit == "B" else f"{n:.1f} {unit}"
+        n /= 1024
+    return "?"
+
+
+def _fmt_span(seconds) -> str:
+    try:
+        seconds = int(seconds)
+    except (TypeError, ValueError):
+        return "?"
+    for size, name in ((86400, "day"), (3600, "hour"), (60, "minute")):
+        if seconds >= size:
+            n = seconds // size
+            return f"{n} {name}{'s' if n != 1 else ''}"
+    return f"{seconds} seconds"
+
+
+def _fmt_remaining(seconds) -> str:
+    try:
+        seconds = int(seconds)
+    except (TypeError, ValueError):
+        return "?"
+    if seconds <= 0:
+        return "expired"
+    days, rem = divmod(seconds, 86400)
+    hours, rem = divmod(rem, 3600)
+    minutes = rem // 60
+    if days:
+        return f"{days}d {hours}h left"
+    if hours:
+        return f"{hours}h {minutes}m left"
+    return f"{minutes}m left"
+
+
+def _fmt_ts(ts) -> str:
+    try:
+        return time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(int(ts)))
+    except (TypeError, ValueError, OSError):
+        return "?"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    epilog = """\
+expiry formats:
+  7        7 days
+  2m       2 minutes (also Ns / Nh / Nd)
+
+examples:
+  preview-publish ./site/ my-site 14
+  preview-publish ./page.html
+  preview-publish --dry-run ./site/ my-site
+  preview-publish --list
+  preview-publish --delete <hash>
+  preview-publish --expiry <hash> --action extend --days 30
+"""
+    ap = argparse.ArgumentParser(
+        prog=PROG,
+        description="Publish short-lived HTML previews to a html-previewer service.",
+        epilog=epilog,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    ap.add_argument("path", nargs="?", help="folder, .zip, or single .html to publish")
+    ap.add_argument("topic", nargs="?", help="URL label (default: derived from path)")
+    ap.add_argument("expiry_spec", nargs="?", metavar="EXPIRY",
+                    help="N days, or N{s,m,h,d} e.g. 2m (default: server default)")
+    ap.add_argument("--version", action="version", version=f"{PROG} {__version__}")
+
+    g = ap.add_argument_group("actions (instead of publishing)")
+    g.add_argument("--dry-run", action="store_true",
+                   help="predict update-in-place vs new URL (no upload)")
+    g.add_argument("--list", action="store_true", help="list live previews")
+    g.add_argument("--list-all", action="store_true",
+                   help="list all previews incl. expired/deleted")
+    g.add_argument("--info", metavar="HASH", help="show one preview's record")
+    g.add_argument("--delete", metavar="HASH", help="reclaim a preview now")
+    g.add_argument("--expiry", metavar="HASH",
+                   help="admin expiry control (requires --action)")
+    g.add_argument("--action", choices=("extend", "expire", "renew"),
+                   help="expiry action for --expiry (days via --days)")
+    g.add_argument("--days", type=int, metavar="N",
+                   help="days for --action extend/renew (default: 30/7)")
+    g.add_argument("--health", action="store_true", help="check server liveness")
+    g.add_argument("--save-config", action="store_true",
+                   help="save --base/--key (or env) to the config file and exit")
+
+    g = ap.add_argument_group("options")
+    g.add_argument("--new", action="store_true",
+                   default=os.environ.get("PREVIEW_NEW") == "1",
+                   help="force a brand-new URL instead of same-name update "
+                        "(env: PREVIEW_NEW=1)")
+    g.add_argument("--open", action="store_true",
+                   help="open the published URL in a browser")
+    g.add_argument("--json", action="store_true", dest="as_json",
+                   help="print raw JSON responses")
+    g.add_argument("--base", metavar="URL", help="API base URL (env: PREVIEW_API_BASE)")
+    g.add_argument("--key", metavar="KEY", help="API key (env: PREVIEW_API_KEY)")
+    g.add_argument("--config", metavar="FILE",
+                   help="config file path (default: platform config dir)")
+    return ap
+
+
+# ---- output -------------------------------------------------------------
+
+def _print_publish(res: dict) -> None:
+    action = "updated in place" if res.get("updated") else "created"
+    print(f"published topic={res.get('topic')} ({action})")
+    print(f"  url:     {res.get('url')}")
+    print(f"  expires: {_fmt_ts(res.get('expires_at'))} "
+          f"(in {_fmt_span(res.get('ttl_seconds'))})")
+    print(f"  size:    {_fmt_size(res.get('size_bytes'))}, "
+          f"{res.get('file_count', '?')} files")
+    if not res.get("has_index_html"):
+        note = ("auto-generated directory index" if res.get("auto_index")
+                else "WARNING: no index.html")
+        print(f"  index:   {note}")
+
+
+def _print_check(res: dict) -> None:
+    print(f"dry-run: topic={res.get('topic')}")
+    if res.get("action") == "update":
+        print(f"  would UPDATE in place (same URL): {res.get('url')}")
+    else:
+        print("  would CREATE a new URL")
+
+
+def _print_list(previews: list) -> None:
+    if not previews:
+        print("no previews")
+        return
+    for p in previews:
+        print(f"{p.get('hash')}  {p.get('topic')}  {p.get('status')}"
+              f"  ({_fmt_remaining(p.get('seconds_remaining'))},"
+              f" {_fmt_size(p.get('size_bytes'))},"
+              f" {p.get('file_count', '?')} files)")
+        print(f"  {p.get('url')}")
+
+
+def _print_preview(p: dict, title: str) -> None:
+    print(title)
+    for k in ("hash", "topic", "url", "status", "days", "size_bytes",
+              "file_count", "archived"):
+        if k in p:
+            print(f"  {k + ':':12} {p[k]}")
+    print(f"  expires:     {_fmt_ts(p.get('expires_at'))} "
+          f"({_fmt_remaining(p.get('seconds_remaining'))})")
+
+
+# ---- command ------------------------------------------------------------
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    if args.expiry and not args.action:
+        print(f"{PROG}: --expiry requires --action extend|expire|renew",
+              file=sys.stderr)
+        return 2
+    if args.action and not args.expiry:
+        print(f"{PROG}: --action requires --expiry HASH", file=sys.stderr)
+        return 2
+
+    cfg = resolve(base=args.base, key=args.key, config_path=args.config)
+
+    if args.save_config:
+        path = save_config(base=cfg["base"], key=cfg["key"],
+                           path=cfg["config_path"])
+        print(f"saved config to {path}")
+        return 0
+
+    client = PreviewClient(cfg["base"], api_key=cfg["key"])
+
+    try:
+        if args.health:
+            res = client.health()
+            if args.as_json:
+                _print_json(res)
+            else:
+                print(f"ok: {cfg['base']} is alive")
+            return 0
+
+        if args.list or args.list_all:
+            previews = client.list_previews(all=args.list_all)
+            if args.as_json:
+                _print_json({"previews": previews})
+            else:
+                _print_list(previews)
+            return 0
+
+        if args.info:
+            res = client.info(args.info)
+            if args.as_json:
+                _print_json(res)
+            else:
+                _print_preview(res.get("preview", {}), f"preview {args.info}")
+            return 0
+
+        if args.delete:
+            res = client.delete(args.delete)
+            if args.as_json:
+                _print_json(res)
+            else:
+                print(f"deleted {res.get('hash')} "
+                      f"(live copy reclaimed; git archive kept)")
+            return 0
+
+        if args.expiry:
+            res = client.expiry(args.expiry, args.action, days=args.days)
+            if args.as_json:
+                _print_json(res)
+            else:
+                _print_preview(res.get("preview", {}),
+                               f"{args.action}: preview {args.expiry}")
+            return 0
+
+        # default action: publish (or dry-run)
+        if not args.path:
+            print(f"{PROG}: a path is required to publish "
+                  f"(or use --list/--delete/--info/...)", file=sys.stderr)
+            return 2
+        path = Path(args.path)
+        if not path.exists():
+            print(f"{PROG}: no such file or directory: {path}", file=sys.stderr)
+            return 1
+
+        if args.dry_run:
+            res = client.publish(path, topic=args.topic, dry_run=True,
+                                 new=args.new)
+            if args.as_json:
+                _print_json(res)
+            else:
+                _print_check(res)
+            return 0
+
+        parse_expiry(args.expiry_spec)  # fail fast on a bad spec, before zipping
+        res = client.publish(path, topic=args.topic, expiry=args.expiry_spec,
+                             new=args.new)
+        if args.as_json:
+            _print_json(res)
+        else:
+            _print_publish(res)
+        if args.open and res.get("url"):
+            webbrowser.open(res["url"])
+        return 0
+
+    except PreviewError as e:
+        print(f"{PROG}: {e}", file=sys.stderr)
+        return 1
+    except ValueError as e:
+        print(f"{PROG}: {e}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        print(f"{PROG}: interrupted", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

html_previewer/client.py

@@ -0,0 +1,239 @@
+"""Client library for the html-previewer ephemeral preview hosting service.
+
+Stdlib-only, works on Linux, macOS and Windows. Talks to the service's
+``/_api/`` HTTP endpoints using the X-API-Key header.
+
+Typical use::
+
+    from html_previewer import PreviewClient
+
+    c = PreviewClient("https://preview.example.com", api_key="…")
+    result = c.publish("./site", topic="my-site", expiry="14")  # or "2m"
+    print(result["url"])
+"""
+from __future__ import annotations
+
+import io
+import json
+import os
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+import zipfile
+from pathlib import Path
+
+__all__ = [
+    "PreviewClient",
+    "PreviewError",
+    "build_zip",
+    "default_topic",
+    "parse_expiry",
+    "slugify_topic",
+]
+
+
+class PreviewError(Exception):
+    """A request to the preview service failed."""
+
+    def __init__(self, message: str, status: int | None = None):
+        super().__init__(message)
+        self.status = status
+
+
+# Mirrors slugify_topic() in server/preview_common.py so the client can reason
+# about the final topic segment (and print it) exactly like the server will.
+_TOPIC_RE = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def slugify_topic(raw: str) -> str:
+    raw = (raw or "").strip()
+    raw = _TOPIC_RE.sub("-", raw)
+    raw = raw.strip(".-_")
+    if not raw:
+        raw = "preview"
+    return raw[:64]
+
+
+_EXPIRY_RE = re.compile(r"^(\d+)([smhd]?)$", re.IGNORECASE)
+_UNIT_SECONDS = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+
+
+def parse_expiry(spec: str | None):
+    """Parse an expiry spec into publish parameters.
+
+    ``"14"``  -> 14 days (X-Days)
+    ``"2m"``  -> 2 minutes as seconds (X-TTL); also Ns / Nh / Nd
+    ``None``  -> server default (no header sent)
+    Returns ``{"days": n}``, ``{"ttl": seconds}`` or ``None``.
+    """
+    if spec is None or spec == "":
+        return None
+    m = _EXPIRY_RE.match(str(spec).strip())
+    if not m:
+        raise ValueError(f"bad expiry {spec!r}: use N for days, or Ns/Nm/Nh/Nd (e.g. 2m)")
+    n, unit = int(m.group(1)), m.group(2).lower()
+    if n < 1:
+        raise ValueError(f"bad expiry {spec!r}: must be at least 1")
+    if not unit:
+        return {"days": n}
+    return {"ttl": n * _UNIT_SECONDS[unit]}
+
+
+def default_topic(path: Path | str) -> str:
+    """Derive the default topic from a folder/file name (matches the shell client)."""
+    p = Path(path)
+    if p.is_dir():
+        return p.name
+    return p.stem or p.name
+
+
+def build_zip(folder: Path | str) -> bytes:
+    """Zip the *contents* of a folder so files sit at the archive root.
+
+    ``index.html`` lands directly at the zip root (and thus under
+    ``{hash}/{topic}/`` on the server). Arcnames always use forward slashes
+    so archives built on Windows unpack correctly on the server.
+    """
+    folder = Path(folder)
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        for root, _dirs, files in os.walk(folder):
+            for name in files:
+                full = os.path.join(root, name)
+                arcname = os.path.relpath(full, folder).replace(os.sep, "/")
+                zf.write(full, arcname)
+    return buf.getvalue()
+
+
+class PreviewClient:
+    """HTTP client for a html-previewer service."""
+
+    def __init__(self, base_url: str, api_key: str | None = None,
+                 timeout: float = 120.0):
+        self.base = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+    # -- transport ---------------------------------------------------------
+
+    def _url(self, path: str, params: dict | None = None) -> str:
+        url = f"{self.base}{path}"
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        return url
+
+    def _request(self, method: str, path: str, *, params: dict | None = None,
+                 headers: dict | None = None, data: bytes | None = None) -> dict:
+        req = urllib.request.Request(self._url(path, params), data=data,
+                                     method=method)
+        if self.api_key:
+            req.add_header("X-API-Key", self.api_key)
+        for k, v in (headers or {}).items():
+            req.add_header(k, v)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            detail = ""
+            try:
+                body = json.loads(e.read().decode("utf-8"))
+                detail = body.get("error", "")
+            except Exception:  # noqa: BLE001 - best-effort error decoration
+                pass
+            msg = f"HTTP {e.code} {e.reason}"
+            if detail:
+                msg = f"{msg}: {detail}"
+            raise PreviewError(msg, status=e.code) from None
+        except urllib.error.URLError as e:
+            raise PreviewError(f"cannot reach {self.base}: {e.reason}") from None
+
+    def _require_key(self) -> str:
+        if not self.api_key:
+            raise PreviewError(
+                "missing API key: set PREVIEW_API_KEY (env or config file), "
+                "pass --key, or run with --save-config"
+            )
+        return self.api_key
+
+    # -- API operations ----------------------------------------------------
+
+    def health(self) -> dict:
+        return self._request("GET", "/_api/health")
+
+    def check(self, topic: str, new: bool = False) -> dict:
+        """Dry-run: would publishing this topic update in place or create a new URL?"""
+        self._require_key()
+        topic = slugify_topic(topic)
+        params = {"topic": topic}
+        if new:
+            params["new"] = "1"
+        return self._request("GET", "/_api/check", params=params)
+
+    def publish(self, path: Path | str, topic: str | None = None,
+                expiry: str | None = None, new: bool = False,
+                dry_run: bool = False) -> dict:
+        """Publish a folder, a .zip, or a single .html file.
+
+        topic    URL label; defaults to the folder/file name
+        expiry   N days ("14") or N{s,m,h,d} ("2m"); None = server default
+        new      force a brand-new URL instead of a same-name in-place update
+        dry_run  only predict the outcome (no upload happens)
+        """
+        self._require_key()
+        p = Path(path)
+        if not p.exists():
+            raise PreviewError(f"no such file or directory: {p}")
+
+        if p.is_dir():
+            ptype = "zip"
+        elif p.suffix.lower() == ".zip":
+            ptype = "zip"
+        elif p.suffix.lower() in (".html", ".htm"):
+            ptype = "html"
+        else:
+            raise PreviewError(
+                f"unsupported type (use a folder, .zip, or .html): {p}"
+            )
+
+        topic = slugify_topic(topic if topic is not None else default_topic(p))
+
+        if dry_run:
+            return self.check(topic, new=new)
+
+        data = build_zip(p) if p.is_dir() else p.read_bytes()
+
+        headers = {"X-Topic": topic, "X-Type": ptype}
+
+        expiry_hdr = parse_expiry(expiry)
+        if expiry_hdr:
+            for k, v in expiry_hdr.items():
+                headers[f"X-{k.capitalize()}"] = str(v)
+        if new:
+            headers["X-New"] = "1"
+        return self._request("POST", "/_api/publish", headers=headers, data=data)
+
+    def list_previews(self, all: bool = False) -> list:
+        """List previews (live only by default; everything with all=True)."""
+        self._require_key()
+        params = {"all": "1"} if all else None
+        return self._request("GET", "/_api/list", params=params).get("previews", [])
+
+    def info(self, hash: str) -> dict:
+        self._require_key()
+        return self._request("GET", f"/_api/info/{hash}")
+
+    def delete(self, hash: str) -> dict:
+        """Reclaim a preview now (the git archive, if any, is kept)."""
+        self._require_key()
+        return self._request("DELETE", f"/_api/preview/{hash}")
+
+    def expiry(self, hash: str, action: str, days: int | None = None) -> dict:
+        """Admin expiry control: action = extend | expire | renew."""
+        self._require_key()
+        if action not in ("extend", "expire", "renew"):
+            raise PreviewError("action must be extend, expire, or renew")
+        params = {"action": action}
+        if days is not None:
+            params["days"] = str(days)
+        return self._request("POST", f"/_api/expiry/{hash}", params=params)

html_previewer/config.py

@@ -0,0 +1,117 @@
+"""Cross-platform config discovery for the html-previewer client.
+
+Precedence (highest first):
+  1. explicit values passed by the caller (CLI flags)
+  2. environment variables (PREVIEW_API_KEY / PREVIEW_API_BASE)
+  3. a key=value config file
+
+The config file uses plain ``KEY=VALUE`` lines (an optional ``export`` prefix
+and surrounding quotes are tolerated), so the same file works for both the
+classic ``preview-publish.sh`` client and this Python client. On Linux/macOS
+the default location matches the shell client: ``~/.config/preview/config``.
+On Windows it is ``%APPDATA%\\preview\\config``.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+ENV_KEY = "PREVIEW_API_KEY"
+ENV_BASE = "PREVIEW_API_BASE"
+ENV_CONFIG = "PREVIEW_CONFIG"
+DEFAULT_BASE = "https://preview.example.com"
+
+
+def default_config_path() -> Path:
+    if os.name == "nt":
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            return Path(appdata) / "preview" / "config"
+        return Path.home() / ".config" / "preview" / "config"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "preview" / "config"
+    return Path.home() / ".config" / "preview" / "config"
+
+
+def parse_config(text: str) -> dict:
+    cfg = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):].lstrip()
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key, value = key.strip(), value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        if key:
+            cfg[key] = value
+    return cfg
+
+
+def load_config(path: Path | str | None = None) -> dict:
+    path = Path(path) if path is not None else default_config_path()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    return parse_config(text)
+
+
+def save_config(base: str | None = None, key: str | None = None,
+                path: Path | str | None = None) -> Path:
+    """Write/update PREVIEW_API_BASE and PREVIEW_API_KEY in the config file.
+
+    Existing lines for these keys are replaced in place; unrelated lines are
+    preserved. The file is created (0600 where supported) if missing.
+    """
+    path = Path(path) if path is not None else default_config_path()
+    updates = {}
+    if base:
+        updates[ENV_BASE] = base
+    if key:
+        updates[ENV_KEY] = key
+    if not updates:
+        raise ValueError("nothing to save: pass base and/or key")
+
+    lines: list[str] = []
+    seen = set()
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        pass
+    out = []
+    for line in lines:
+        stripped = line.strip()
+        parsed = parse_config(stripped)
+        if len(parsed) == 1:
+            (name, _old), = parsed.items()
+            if name in updates:
+                out.append(f"{name}={updates[name]}")
+                seen.add(name)
+                continue
+        out.append(line)
+    for name, value in updates.items():
+        if name not in seen:
+            out.append(f"{name}={value}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(out) + "\n", encoding="utf-8")
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass  # Windows: ACLs already restrict to the user profile
+    return path
+
+
+def resolve(base: str | None = None, key: str | None = None,
+            config_path: Path | str | None = None) -> dict:
+    """Resolve (base_url, api_key, config_path_used) from flags/env/config."""
+    path = Path(config_path) if config_path is not None else default_config_path()
+    file_cfg = load_config(path)
+    base = base or os.environ.get(ENV_BASE) or file_cfg.get(ENV_BASE, DEFAULT_BASE)
+    key = key or os.environ.get(ENV_KEY) or file_cfg.get(ENV_KEY)
+    return {"base": base.rstrip("/"), "key": key, "config_path": path}

html_previewer-0.1.1.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: html-previewer
+Version: 0.1.1
+Summary: Cross-platform client (Windows/Linux/macOS) for html-previewer: publish short-lived HTML previews behind unguessable URLs
+Author: agony
+License: MIT
+Project-URL: Homepage, https://github.com/Agony5757/html-previewer
+Project-URL: Source, https://github.com/Agony5757/html-previewer
+Project-URL: Issues, https://github.com/Agony5757/html-previewer/issues
+Keywords: html,preview,publish,static-site,ephemeral,hosting
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# html-previewer (Python client)
+
+Cross-platform command-line client and library for
+[html-previewer](https://github.com/Agony5757/html-previewer) — a self-hosted
+service that publishes short-lived HTML previews behind **unguessable
+capability URLs**, with automatic expiry and disk reclaim.
+
+Works on **Linux, macOS and Windows**. Pure **stdlib** — zero runtime
+dependencies. It is a faithful, feature-complete port of the classic
+`preview-publish.sh`, so existing habits and scripts carry over.
+
+## Install
+
+```bash
+pip install html-previewer
+```
+
+This installs the `preview-publish` command (alias: `html-previewer`).
+
+## Configure
+
+Point the client at your server once:
+
+```bash
+preview-publish --base https://preview.example.com --key YOUR_API_KEY --save-config
+```
+
+Or just export the variables: `PREVIEW_API_BASE` and `PREVIEW_API_KEY`
+(equivalently, put `PREVIEW_API_KEY=…` lines in the config file —
+`~/.config/preview/config` on Linux/macOS, `%APPDATA%\preview\config` on
+Windows; the same shell-style file the bash client reads).
+
+## Use
+
+```bash
+preview-publish ./site/ my-site 14      # publish a folder, 14-day expiry
+preview-publish ./report.zip            # publish a zip (topic from filename)
+preview-publish ./page.html             # publish a single html page
+preview-publish ./site/ my-site 2m      # short-lived: 2 minutes
+preview-publish --dry-run ./site/ my    # predict: update in place, or new URL?
+preview-publish --new ./site/ my-site   # force a brand-new URL
+preview-publish --list                  # list live previews (--list-all: everything)
+preview-publish --info <hash>           # one preview's record
+preview-publish --delete <hash>         # reclaim now
+preview-publish --expiry <hash> --action extend --days 30
+preview-publish --open ./site/ my-site  # publish, then open in a browser
+preview-publish --health                # is the server alive?
+```
+
+Re-publishing under a `topic` that is still live **updates it in place and
+keeps the same URL** (expiry resets) — share a link once, keep refreshing the
+content. A topic whose preview already expired gets a brand-new URL. Add
+`--json` to any command for machine-readable output.
+
+## Library
+
+```python
+from html_previewer import PreviewClient
+
+c = PreviewClient("https://preview.example.com", api_key="…")
+res = c.publish("./site", topic="my-site", expiry="14")   # expiry: "14" or "2m"
+print(res["url"])
+
+for p in c.list_previews():
+    print(p["topic"], p["url"], p["seconds_remaining"])
+
+c.check("my-site")          # dry-run: update in place vs new URL
+c.info(res["hash"])
+c.expiry(res["hash"], "extend", days=30)   # extend | expire | renew
+c.delete(res["hash"])
+```
+
+## Development
+
+```bash
+cd client
+python -m pip install -e .[test]
+python -m pytest tests -v
+```
+
+The test suite includes an end-to-end test that boots the real server from
+the repository checkout; it is skipped automatically when the server sources
+are absent (e.g. in the sdist).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

html_previewer-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+html_previewer/__init__.py,sha256=TjM1LnW7wIAy2K0lx8BQeAcaZ1YjFYqZ3M-Ohq1MCmc,381
+html_previewer/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
+html_previewer/cli.py,sha256=2DWCNdlLtZxoE7yARLhKeQHMWgIbctsOC0ePtcTtBFs,10179
+html_previewer/client.py,sha256=OaXJmGzrc4P7QLJLMNMbMakuT-vURSglvmzTkvXcuPo,8367
+html_previewer/config.py,sha256=Cr7N9i0GuWyA9ScFk22uo25vjR3DMCJqWkHIOabqdVQ,4084
+html_previewer-0.1.1.dist-info/licenses/LICENSE,sha256=EuEvfowiJjYGQobNKS6hmfMdVTcTlkDma73goUJZPd8,1062
+html_previewer-0.1.1.dist-info/METADATA,sha256=RjPuX0fl0EMQL9m6fTI5SssggeMo6XzFTMhZLFFl6wQ,4366
+html_previewer-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+html_previewer-0.1.1.dist-info/entry_points.txt,sha256=vPY0GjfWCGPK__uR8g-Givt30zMH0InKcH7p5TbQwUo,101
+html_previewer-0.1.1.dist-info/top_level.txt,sha256=w39R9JmT5G12Ojiw8pwDvKbdgooxEWdutb9Q6M92K6U,15
+html_previewer-0.1.1.dist-info/RECORD,,

html_previewer-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

html_previewer-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+html-previewer = html_previewer.cli:main
+preview-publish = html_previewer.cli:main

html_previewer-0.1.1.dist-info/licenses/LICENSE

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

html_previewer-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+html_previewer