html-previewer 0.1.1__tar.gz

html_previewer-0.1.1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,87 @@
+# 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/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "html-previewer"
+description = "Cross-platform client (Windows/Linux/macOS) for html-previewer: publish short-lived HTML previews behind unguessable URLs"
+readme = "README.md"
+requires-python = ">=3.9"
+dynamic = ["version"]
+license = { text = "MIT" }
+authors = [{ name = "agony" }]
+keywords = ["html", "preview", "publish", "static-site", "ephemeral", "hosting"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Site Management",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.scripts]
+preview-publish = "html_previewer.cli:main"
+html-previewer = "html_previewer.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Agony5757/html-previewer"
+Source = "https://github.com/Agony5757/html-previewer"
+Issues = "https://github.com/Agony5757/html-previewer/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "html_previewer.__version__" }

html_previewer-0.1.1/setup.cfg

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

html_previewer-0.1.1/src/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-0.1.1/src/html_previewer/__main__.py

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

html_previewer-0.1.1/src/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())