htmlship 0.1.0__py3-none-any.whl

htmlship/__init__.py

@@ -0,0 +1,101 @@
+"""HTMLShip — host and share HTML in one line.
+
+Quick start:
+
+    import htmlship
+    paste = htmlship.publish("<h1>Hello</h1>", expires_in=86400)
+    print(paste.url)
+    print(paste.owner_key)
+
+    paste.update("<h1>Hello, again</h1>")
+    paste.delete()
+
+Configuration via environment:
+    HTMLSHIP_API_URL   (default: https://api.htmlship.com)
+    HTMLSHIP_API_KEY   (optional; reserved for future use)
+"""
+from __future__ import annotations
+
+from ._version import __version__
+from .client import HTMLShipClient
+from .exceptions import (
+    APIError,
+    AuthError,
+    HTMLShipError,
+    NotFoundError,
+    RateLimitError,
+)
+from .models import Paste
+
+_default_client: HTMLShipClient | None = None
+
+
+def _get_default_client() -> HTMLShipClient:
+    global _default_client
+    if _default_client is None:
+        _default_client = HTMLShipClient()
+    return _default_client
+
+
+def configure(
+    *,
+    base_url: str | None = None,
+    api_key: str | None = None,
+) -> HTMLShipClient:
+    """Replace the module-level default client.
+
+    Useful when you want to point at a different API URL without setting env vars.
+    """
+    global _default_client
+    if _default_client is not None:
+        _default_client.close()
+    _default_client = HTMLShipClient(base_url=base_url, api_key=api_key)
+    return _default_client
+
+
+def publish(
+    html: str,
+    *,
+    title: str | None = None,
+    password: str | None = None,
+    expires_in: int | None = None,
+    parent_slug: str | None = None,
+    sandbox_mode: str = "strict",
+) -> Paste:
+    return _get_default_client().publish(
+        html,
+        title=title,
+        password=password,
+        expires_in=expires_in,
+        parent_slug=parent_slug,
+        sandbox_mode=sandbox_mode,
+    )
+
+
+def get(slug: str) -> Paste:
+    return _get_default_client().get(slug)
+
+
+def update(slug: str, html: str, *, owner_key: str, title: str | None = None) -> Paste:
+    return _get_default_client().update(slug, html, owner_key=owner_key, title=title)
+
+
+def delete(slug: str, *, owner_key: str) -> None:
+    return _get_default_client().delete(slug, owner_key=owner_key)
+
+
+__all__ = [
+    "__version__",
+    "HTMLShipClient",
+    "Paste",
+    "HTMLShipError",
+    "NotFoundError",
+    "AuthError",
+    "RateLimitError",
+    "APIError",
+    "configure",
+    "publish",
+    "get",
+    "update",
+    "delete",
+]

htmlship/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

htmlship/cli.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import click
+
+from . import HTMLShipClient
+from ._version import __version__
+from .exceptions import HTMLShipError, NotFoundError
+
+KEYS_DIR = Path(os.environ.get("HTMLSHIP_KEYS_DIR", str(Path.home() / ".htmlship")))
+KEYS_FILE = KEYS_DIR / "keys.json"
+
+
+# --- key store ----------------------------------------------------------------
+
+
+def _load_keys() -> dict[str, dict[str, Any]]:
+    if not KEYS_FILE.exists():
+        return {}
+    try:
+        return json.loads(KEYS_FILE.read_text())
+    except Exception:
+        return {}
+
+
+def _save_keys(data: dict[str, dict[str, Any]]) -> None:
+    KEYS_DIR.mkdir(parents=True, exist_ok=True)
+    KEYS_FILE.write_text(json.dumps(data, indent=2, sort_keys=True))
+    try:
+        KEYS_FILE.chmod(0o600)
+    except OSError:
+        pass
+
+
+def _remember(slug: str, owner_key: str, url: str, title: str | None) -> None:
+    keys = _load_keys()
+    keys[slug] = {
+        "owner_key": owner_key,
+        "url": url,
+        "title": title,
+        "saved_at": datetime.now(UTC).isoformat(),
+    }
+    _save_keys(keys)
+
+
+def _forget(slug: str) -> None:
+    keys = _load_keys()
+    if slug in keys:
+        del keys[slug]
+        _save_keys(keys)
+
+
+def _lookup_owner_key(slug: str) -> str | None:
+    return _load_keys().get(slug, {}).get("owner_key")
+
+
+# --- helpers ------------------------------------------------------------------
+
+
+def _read_html(source: str | None, file: str | None) -> str:
+    """Resolve the HTML payload from --file, a positional path, or stdin."""
+    if file:
+        return Path(file).read_text(encoding="utf-8")
+    if source == "-" or source is None:
+        if sys.stdin.isatty() and source is None:
+            raise click.UsageError("Provide a file path or pipe HTML on stdin.")
+        return sys.stdin.read()
+    return Path(source).read_text(encoding="utf-8")
+
+
+def _try_clipboard(text: str) -> bool:
+    try:
+        import pyperclip  # type: ignore
+    except Exception:
+        return False
+    try:
+        pyperclip.copy(text)
+        return True
+    except Exception:
+        return False
+
+
+def _make_client(api_url: str | None) -> HTMLShipClient:
+    return HTMLShipClient(base_url=api_url)
+
+
+# --- CLI ----------------------------------------------------------------------
+
+
+@click.group(help="HTMLShip — host and share HTML in one line.")
+@click.version_option(__version__, prog_name="htmlship")
+@click.option(
+    "--api-url",
+    envvar="HTMLSHIP_API_URL",
+    default=None,
+    help="API base URL (default: https://api.htmlship.com).",
+)
+@click.pass_context
+def main(ctx: click.Context, api_url: str | None) -> None:
+    ctx.ensure_object(dict)
+    ctx.obj["api_url"] = api_url
+
+
+@main.command()
+@click.argument("source", required=False)
+@click.option("--file", "-f", "file_", type=click.Path(exists=True, dir_okay=False), help="HTML file path.")
+@click.option("--title", default=None, help="Optional title.")
+@click.option("--password", default=None, help="Password-protect the paste.")
+@click.option("--expires-in", type=int, default=None, help="Seconds until expiry.")
+@click.option("--no-clipboard", is_flag=True, help="Don't copy URL to clipboard.")
+@click.option("--quiet", "-q", is_flag=True, help="Print only the URL.")
+@click.pass_context
+def publish(
+    ctx: click.Context,
+    source: str | None,
+    file_: str | None,
+    title: str | None,
+    password: str | None,
+    expires_in: int | None,
+    no_clipboard: bool,
+    quiet: bool,
+) -> None:
+    """Publish HTML.
+
+    Examples:
+
+      htmlship publish report.html
+      cat report.html | htmlship publish -
+      htmlship publish --file report.html --title "Q4 Report"
+    """
+    html = _read_html(source, file_)
+    client = _make_client(ctx.obj["api_url"])
+    try:
+        paste = client.publish(
+            html,
+            title=title,
+            password=password,
+            expires_in=expires_in,
+        )
+    except HTMLShipError as exc:
+        raise click.ClickException(str(exc)) from exc
+    finally:
+        client.close()
+
+    _remember(paste.slug, paste.owner_key or "", paste.url, title)
+
+    if quiet:
+        click.echo(paste.url)
+        return
+
+    click.echo(paste.url)
+    click.echo(f"slug:      {paste.slug}", err=True)
+    click.echo(f"owner_key: {paste.owner_key}  (saved to {KEYS_FILE})", err=True)
+    if paste.expires_at:
+        click.echo(f"expires:   {paste.expires_at.isoformat()}", err=True)
+    if not no_clipboard and _try_clipboard(paste.url):
+        click.echo("(URL copied to clipboard)", err=True)
+
+
+@main.command()
+@click.argument("slug")
+@click.pass_context
+def get(ctx: click.Context, slug: str) -> None:
+    """Show metadata for a paste."""
+    client = _make_client(ctx.obj["api_url"])
+    try:
+        paste = client.get(slug)
+    except NotFoundError as exc:
+        raise click.ClickException(f"paste '{slug}' not found") from exc
+    except HTMLShipError as exc:
+        raise click.ClickException(str(exc)) from exc
+    finally:
+        client.close()
+
+    click.echo(json.dumps(
+        {
+            "slug": paste.slug,
+            "url": paste.url,
+            "title": paste.title,
+            "view_count": paste.view_count,
+            "size_bytes": paste.size_bytes,
+            "has_password": paste.has_password,
+            "parent_slug": paste.parent_slug,
+            "expires_at": paste.expires_at.isoformat() if paste.expires_at else None,
+            "created_at": paste.created_at.isoformat() if paste.created_at else None,
+            "updated_at": paste.updated_at.isoformat() if paste.updated_at else None,
+        },
+        indent=2,
+    ))
+
+
+@main.command()
+@click.argument("slug")
+@click.argument("source", required=False)
+@click.option("--file", "-f", "file_", type=click.Path(exists=True, dir_okay=False))
+@click.option("--title", default=None, help="Optional new title.")
+@click.option("--owner-key", default=None, help="Owner key (defaults to local store).")
+@click.pass_context
+def update(
+    ctx: click.Context,
+    slug: str,
+    source: str | None,
+    file_: str | None,
+    title: str | None,
+    owner_key: str | None,
+) -> None:
+    """Replace HTML for an existing paste."""
+    html = _read_html(source, file_)
+    key = owner_key or _lookup_owner_key(slug)
+    if not key:
+        raise click.ClickException(
+            f"no owner key for '{slug}' in {KEYS_FILE}; pass --owner-key explicitly"
+        )
+    client = _make_client(ctx.obj["api_url"])
+    try:
+        paste = client.update(slug, html, owner_key=key, title=title)
+    except HTMLShipError as exc:
+        raise click.ClickException(str(exc)) from exc
+    finally:
+        client.close()
+
+    click.echo(paste.url)
+
+
+@main.command()
+@click.argument("slug")
+@click.option("--owner-key", default=None, help="Owner key (defaults to local store).")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation.")
+@click.pass_context
+def delete(ctx: click.Context, slug: str, owner_key: str | None, yes: bool) -> None:
+    """Soft-delete a paste."""
+    key = owner_key or _lookup_owner_key(slug)
+    if not key:
+        raise click.ClickException(
+            f"no owner key for '{slug}' in {KEYS_FILE}; pass --owner-key explicitly"
+        )
+    if not yes:
+        click.confirm(f"Delete paste '{slug}'?", abort=True)
+    client = _make_client(ctx.obj["api_url"])
+    try:
+        client.delete(slug, owner_key=key)
+    except HTMLShipError as exc:
+        raise click.ClickException(str(exc)) from exc
+    finally:
+        client.close()
+    _forget(slug)
+    click.echo(f"deleted {slug}")
+
+
+@main.command("list-mine")
+@click.option("--limit", type=int, default=20, show_default=True)
+@click.pass_context
+def list_mine(ctx: click.Context, limit: int) -> None:
+    """List pastes whose owner keys are saved locally."""
+    keys = _load_keys()
+    if not keys:
+        click.echo(f"No saved pastes in {KEYS_FILE}.")
+        return
+    items = sorted(keys.items(), key=lambda kv: kv[1].get("saved_at", ""), reverse=True)[:limit]
+
+    client = _make_client(ctx.obj["api_url"])
+    try:
+        rows = []
+        for slug, info in items:
+            try:
+                paste = client.get(slug)
+                size = f"{paste.size_bytes}B"
+                views = paste.view_count
+                title = paste.title or info.get("title") or ""
+                status = "ok"
+            except NotFoundError:
+                paste = None
+                size = "—"
+                views = "—"
+                title = info.get("title") or ""
+                status = "gone"
+            rows.append(
+                {
+                    "slug": slug,
+                    "url": info.get("url"),
+                    "title": title,
+                    "size": size,
+                    "views": views,
+                    "status": status,
+                }
+            )
+    finally:
+        client.close()
+
+    width = max((len(r["slug"]) for r in rows), default=8)
+    for r in rows:
+        click.echo(
+            f"{r['slug']:<{width}}  {r['status']:<5}  {r['views']:>5} views  "
+            f"{r['size']:>8}  {r['title']}"
+        )
+        click.echo(f"  {r['url']}")

htmlship/client.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import os
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+from ._version import __version__
+from .exceptions import APIError, AuthError, HTMLShipError, NotFoundError, RateLimitError
+from .models import Paste
+
+DEFAULT_API_URL = "https://api.htmlship.com"
+DEFAULT_TIMEOUT = 30.0
+
+
+def _parse_dt(v: str | None) -> datetime | None:
+    if v is None:
+        return None
+    return datetime.fromisoformat(v.replace("Z", "+00:00"))
+
+
+class HTMLShipClient:
+    """Synchronous HTTP client for the HTMLShip API.
+
+    Reads `HTMLSHIP_API_URL` and `HTMLSHIP_API_KEY` from the environment by default.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        self.base_url = (base_url or os.getenv("HTMLSHIP_API_URL") or DEFAULT_API_URL).rstrip("/")
+        self.api_key = api_key or os.getenv("HTMLSHIP_API_KEY")
+        headers = {"User-Agent": f"htmlship-python/{__version__}"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "HTMLShipClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # --- public API ---------------------------------------------------------
+
+    def publish(
+        self,
+        html: str,
+        *,
+        title: str | None = None,
+        password: str | None = None,
+        expires_in: int | None = None,
+        parent_slug: str | None = None,
+        sandbox_mode: str = "strict",
+    ) -> Paste:
+        """Create a paste. Returns a Paste with owner_key set."""
+        body: dict[str, Any] = {"html": html, "sandbox_mode": sandbox_mode}
+        if title is not None:
+            body["title"] = title
+        if password is not None:
+            body["password"] = password
+        if expires_in is not None:
+            body["expires_in"] = expires_in
+        if parent_slug is not None:
+            body["parent_slug"] = parent_slug
+        r = self._http.post("/api/v1/pastes", json=body)
+        data = self._handle(r)
+        return Paste(
+            slug=data["slug"],
+            url=data["url"],
+            owner_key=data["owner_key"],
+            expires_at=_parse_dt(data.get("expires_at")),
+            created_at=_parse_dt(data.get("created_at")),
+            _client=self,
+        )
+
+    def get(self, slug: str) -> Paste:
+        """Fetch metadata for a paste. owner_key is None on the returned object."""
+        r = self._http.get(f"/api/v1/pastes/{slug}")
+        data = self._handle(r)
+        return Paste(
+            slug=data["slug"],
+            url=data["url"],
+            owner_key=None,
+            title=data.get("title"),
+            expires_at=_parse_dt(data.get("expires_at")),
+            created_at=_parse_dt(data.get("created_at")),
+            updated_at=_parse_dt(data.get("updated_at")),
+            view_count=data.get("view_count", 0),
+            size_bytes=data.get("size_bytes", 0),
+            has_password=data.get("has_password", False),
+            parent_slug=data.get("parent_slug"),
+            _client=self,
+        )
+
+    def update(
+        self,
+        slug: str,
+        html: str,
+        *,
+        owner_key: str,
+        title: str | None = None,
+    ) -> Paste:
+        body: dict[str, Any] = {"html": html}
+        if title is not None:
+            body["title"] = title
+        r = self._http.patch(
+            f"/api/v1/pastes/{slug}",
+            json=body,
+            headers={"X-Owner-Key": owner_key},
+        )
+        data = self._handle(r)
+        return Paste(
+            slug=data["slug"],
+            url=data["url"],
+            owner_key=owner_key,
+            expires_at=_parse_dt(data.get("expires_at")),
+            updated_at=_parse_dt(data.get("updated_at")),
+            _client=self,
+        )
+
+    def delete(self, slug: str, *, owner_key: str) -> None:
+        r = self._http.delete(
+            f"/api/v1/pastes/{slug}",
+            headers={"X-Owner-Key": owner_key},
+        )
+        self._handle(r, expect_no_body=True)
+
+    def create_version(
+        self,
+        parent_slug: str,
+        html: str,
+        *,
+        title: str | None = None,
+        password: str | None = None,
+        expires_in: int | None = None,
+    ) -> Paste:
+        body: dict[str, Any] = {"html": html, "sandbox_mode": "strict"}
+        if title is not None:
+            body["title"] = title
+        if password is not None:
+            body["password"] = password
+        if expires_in is not None:
+            body["expires_in"] = expires_in
+        r = self._http.post(f"/api/v1/pastes/{parent_slug}/version", json=body)
+        data = self._handle(r)
+        return Paste(
+            slug=data["slug"],
+            url=data["url"],
+            owner_key=data["owner_key"],
+            expires_at=_parse_dt(data.get("expires_at")),
+            created_at=_parse_dt(data.get("created_at")),
+            _client=self,
+        )
+
+    # --- error mapping ------------------------------------------------------
+
+    def _handle(self, r: httpx.Response, *, expect_no_body: bool = False) -> dict[str, Any]:
+        if 200 <= r.status_code < 300:
+            if expect_no_body or not r.content:
+                return {}
+            return r.json()
+
+        detail = self._error_detail(r)
+
+        if r.status_code == 404:
+            raise NotFoundError(detail)
+        if r.status_code in (401, 403):
+            raise AuthError(detail)
+        if r.status_code == 429:
+            retry = r.headers.get("Retry-After")
+            try:
+                retry_after = float(retry) if retry else None
+            except ValueError:
+                retry_after = None
+            raise RateLimitError(detail, retry_after=retry_after)
+        raise APIError(detail, status_code=r.status_code)
+
+    @staticmethod
+    def _error_detail(r: httpx.Response) -> str:
+        try:
+            data = r.json()
+            if isinstance(data, dict):
+                if "detail" in data:
+                    return str(data["detail"])
+                return str(data)
+            return str(data)
+        except Exception:
+            return r.text or f"HTTP {r.status_code}"
+
+
+__all__ = [
+    "HTMLShipClient",
+    "HTMLShipError",
+    "NotFoundError",
+    "AuthError",
+    "RateLimitError",
+    "APIError",
+]

htmlship/exceptions.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+
+class HTMLShipError(Exception):
+    """Base class for all HTMLShip client errors."""
+
+
+class NotFoundError(HTMLShipError):
+    """Returned when a paste does not exist or has expired."""
+
+
+class AuthError(HTMLShipError):
+    """Owner key missing or invalid."""
+
+
+class RateLimitError(HTMLShipError):
+    """Server returned 429."""
+
+    def __init__(self, message: str, retry_after: float | None = None):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class APIError(HTMLShipError):
+    """Server returned a non-2xx response that doesn't fit a more specific class."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code

htmlship/models.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .client import HTMLShipClient
+
+
+@dataclass
+class Paste:
+    """A paste created via the HTMLShip API.
+
+    The `owner_key` is set on creation and is the only credential to mutate or
+    delete the paste. It is None for pastes loaded via `get()` since the server
+    does not return it after creation.
+    """
+
+    slug: str
+    url: str
+    owner_key: str | None = None
+    expires_at: datetime | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    title: str | None = None
+    view_count: int = 0
+    size_bytes: int = 0
+    has_password: bool = False
+    parent_slug: str | None = None
+
+    _client: "HTMLShipClient | None" = field(default=None, repr=False, compare=False)
+
+    def update(self, html: str, *, title: str | None = None) -> "Paste":
+        """Replace this paste's HTML. Requires owner_key."""
+        if self._client is None:
+            raise RuntimeError("Paste is detached from a client; reattach to mutate")
+        if not self.owner_key:
+            raise RuntimeError(
+                "owner_key is required to update; load via get() first or pass owner_key explicitly"
+            )
+        return self._client.update(self.slug, html, owner_key=self.owner_key, title=title)
+
+    def delete(self) -> None:
+        """Soft-delete this paste. Requires owner_key."""
+        if self._client is None:
+            raise RuntimeError("Paste is detached from a client; reattach to delete")
+        if not self.owner_key:
+            raise RuntimeError(
+                "owner_key is required to delete; load via get() first or pass owner_key explicitly"
+            )
+        self._client.delete(self.slug, owner_key=self.owner_key)
+
+    def fetch_metadata(self) -> "Paste":
+        """Refresh metadata from the server."""
+        if self._client is None:
+            raise RuntimeError("Paste is detached from a client; reattach to fetch metadata")
+        fresh = self._client.get(self.slug)
+        # Preserve owner_key (server doesn't return it).
+        fresh.owner_key = self.owner_key
+        return fresh