docdrop 0.1.0__tar.gz

docdrop-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+.anvil/
+.devbuild/
+.devrun/
+.planning
+.stubs/
+.venv/
+environments.toml
+documents/
+.pytest_cache/

docdrop-0.1.0/LICENSE

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

docdrop-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: docdrop
+Version: 0.1.0
+Summary: Publish HTML and Markdown documents to DocDrop by unguessable link.
+Project-URL: Homepage, https://docdrop.anvil.app
+Project-URL: Repository, https://github.com/Empiria/docdrop
+Project-URL: Documentation, https://github.com/Empiria/docdrop#readme
+Author-email: Owen Campbell <directors@empiria.co.uk>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: markdown,publishing,sharing
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# docdrop
+
+`docdrop` is the command-line publisher for [docdrop][repo] — it uploads HTML
+and Markdown documents to a docdrop server and gives you back an unguessable
+link to share.
+
+```bash
+pip install docdrop
+```
+
+Full documentation — installation, CLI configuration and precedence, the
+complete command reference, and how the server side works — lives in the main
+README:
+
+**https://github.com/Empiria/docdrop#readme**
+
+[repo]: https://github.com/Empiria/docdrop

docdrop-0.1.0/README.md

@@ -0,0 +1,17 @@
+# docdrop
+
+`docdrop` is the command-line publisher for [docdrop][repo] — it uploads HTML
+and Markdown documents to a docdrop server and gives you back an unguessable
+link to share.
+
+```bash
+pip install docdrop
+```
+
+Full documentation — installation, CLI configuration and precedence, the
+complete command reference, and how the server side works — lives in the main
+README:
+
+**https://github.com/Empiria/docdrop#readme**
+
+[repo]: https://github.com/Empiria/docdrop

docdrop-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "docdrop"
+version = "0.1.0"
+description = "Publish HTML and Markdown documents to DocDrop by unguessable link."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Owen Campbell", email = "directors@empiria.co.uk" }]
+keywords = ["publishing", "markdown", "sharing"]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Utilities",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://docdrop.anvil.app"
+Repository = "https://github.com/Empiria/docdrop"
+Documentation = "https://github.com/Empiria/docdrop#readme"
+
+[project.scripts]
+docdrop = "docdrop.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docdrop"]
+
+[dependency-groups]
+dev = ["pytest>=8", "respx>=0.21", "ruff>=0.6"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I001", "SIM", "C4", "PERF", "RET", "UP", "C90"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["docdrop"]

docdrop-0.1.0/src/docdrop/__init__.py

@@ -0,0 +1,3 @@
+"""The docdrop CLI."""
+
+__version__ = "0.1.0"

docdrop-0.1.0/src/docdrop/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

docdrop-0.1.0/src/docdrop/cli.py

@@ -0,0 +1,288 @@
+"""docdrop — publish HTML and Markdown documents by unguessable link.
+
+Every command accepts a global [--server NAME] prefix to target a named
+server profile from your config (see 'docdrop servers').
+
+    docdrop [--server NAME] publish <file> [--slug SLUG] [--title TITLE]
+                            [--alias NAME | --clear-alias]
+    docdrop [--server NAME] list
+    docdrop [--server NAME] open <slug> [--token]
+    docdrop [--server NAME] alias <slug> [name] [--clear]
+    docdrop [--server NAME] grant <slug> [--label NAME] [--expires WHEN]
+    docdrop [--server NAME] revoke <slug> <handle>
+    docdrop [--server NAME] grants <slug>
+    docdrop [--server NAME] history <slug>
+    docdrop [--server NAME] diff <slug> [A B]
+    docdrop [--server NAME] rollback <slug> N
+    docdrop servers
+"""
+
+import argparse
+import sys
+import webbrowser
+from pathlib import Path
+
+from . import config as config_module
+from .client import Client, DocDropError
+from .config import ConfigError
+from .documents import UnsupportedFile, content_type_of, slug_of, title_of
+
+
+def publish(client: Client, args: argparse.Namespace) -> int:
+    path: Path = args.file
+    if not path.is_file():
+        raise DocDropError(f"No such file: {path}")
+
+    content_type = content_type_of(path)
+    content = path.read_text()
+    slug = args.slug or slug_of(path)
+    title = args.title or title_of(content, content_type) or slug
+
+    result = client.publish(
+        slug,
+        title,
+        content,
+        content_type,
+        alias=args.alias,
+        clear_alias=args.clear_alias,
+    )
+    print(f"{result['action']}: {result['title']} ({result['content_type']})")
+    if result.get("alias_url"):
+        print(result["alias_url"])
+    print(result["url"])
+    return 0
+
+
+def list_documents(client: Client, args: argparse.Namespace) -> int:
+    documents = client.documents()
+    if not documents:
+        print("No documents published yet.")
+        return 0
+    for doc in documents:
+        print(f"{doc['slug']:24} {doc['updated'][:16]:17} {doc['url']}")
+        print(f"{'':24} {doc['title']}")
+        if doc.get("alias_url"):
+            print(f"{'':24} {doc['alias_url']}")
+    return 0
+
+
+def open_document(client: Client, args: argparse.Namespace) -> int:
+    for doc in client.documents():
+        if doc["slug"] == args.slug:
+            url = (
+                doc["url"]
+                if args.token or not doc.get("alias_url")
+                else doc["alias_url"]
+            )
+            print(url)
+            webbrowser.open(url)
+            return 0
+    raise DocDropError(f"You have no document with the slug {args.slug!r}.")
+
+
+def alias_command(client: Client, args: argparse.Namespace) -> int:
+    result = client.alias(args.slug, args.name, args.clear)
+    if args.name:
+        print(result["alias_url"])
+        print(result["url"])
+    elif args.clear:
+        print(f"{args.slug}: alias cleared")
+    elif result.get("alias"):
+        print(result["alias_url"])
+    else:
+        print(f"no alias set for {args.slug}")
+    return 0
+
+
+def grant_command(client: Client, args: argparse.Namespace) -> int:
+    result = client.grant(args.slug, args.label, args.expires)
+    print(result["url"])
+    print(f"handle: {result['handle']}  label: {result['label']}")
+    return 0
+
+
+def revoke_command(client: Client, args: argparse.Namespace) -> int:
+    client.revoke(args.slug, args.handle)
+    print(f"{args.slug}: revoked {args.handle}")
+    return 0
+
+
+def grants_command(client: Client, args: argparse.Namespace) -> int:
+    grants = client.grants(args.slug)
+    if not grants:
+        print(f"No grants for {args.slug}.")
+        return 0
+    for grant in grants:
+        last_viewed = grant["last_viewed"][:16] if grant.get("last_viewed") else "never"
+        expires = grant["expires"][:16] if grant.get("expires") else "never"
+        marker = " (revoked)" if grant.get("revoked") else ""
+        print(
+            f"{grant['handle']:10} {grant.get('label', ''):14} "
+            f"views:{grant['view_count']:<4} last:{last_viewed:17}{marker}"
+        )
+        print(f"{'':10} created:{grant['created'][:16]:17} expires:{expires}")
+    return 0
+
+
+def history_command(client: Client, args: argparse.Namespace) -> int:
+    revisions = client.history(args.slug)
+    if not revisions:
+        print(f"No revisions for {args.slug}.")
+        return 0
+    for r in revisions:
+        marker = " (head)" if r.get("head") else ""
+        print(
+            f"{r['number']:<4} {r['published'][:16]:17} "
+            f"{r['content_type']:14}{marker}"
+        )
+    return 0
+
+
+def diff_command(client: Client, args: argparse.Namespace) -> int:
+    if args.revisions and len(args.revisions) != 2:
+        raise DocDropError("diff takes zero or two revision numbers.")
+    a, b = args.revisions if args.revisions else (None, None)
+    result = client.diff(args.slug, a, b)
+    print(result["diff"], end="")
+    return 0
+
+
+def rollback_command(client: Client, args: argparse.Namespace) -> int:
+    result = client.rollback(args.slug, args.number)
+    print(f"{args.slug}: rolled back to {args.number}, new head is {result['number']}")
+    print(result["url"])
+    return 0
+
+
+def servers_command(args: argparse.Namespace) -> int:
+    names, active = config_module.list_servers(server=args.server)
+    for name in names:
+        marker = "* " if name == active else "  "
+        print(f"{marker}{name}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="docdrop",
+        description="Publish HTML and Markdown documents by unguessable link.",
+    )
+    parser.add_argument("--server", help="named profile (see 'docdrop servers')")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    publish_cmd = commands.add_parser(
+        "publish", help="publish an HTML or Markdown file"
+    )
+    publish_cmd.add_argument("file", type=Path, help="the file to publish")
+    publish_cmd.add_argument(
+        "--slug", help="URL-stable document key (default: the file's name)"
+    )
+    publish_cmd.add_argument(
+        "--title", help="document title (default: the <title>, or the Markdown H1)"
+    )
+    alias_group = publish_cmd.add_mutually_exclusive_group()
+    alias_group.add_argument("--alias", help="set or edit the document's alias")
+    alias_group.add_argument(
+        "--clear-alias",
+        action="store_true",
+        help="remove the document's alias",
+    )
+    publish_cmd.set_defaults(run=publish)
+
+    list_cmd = commands.add_parser("list", help="list the documents you've published")
+    list_cmd.set_defaults(run=list_documents)
+
+    servers_cmd = commands.add_parser(
+        "servers", help="list your configured server profiles"
+    )
+    servers_cmd.set_defaults(run=servers_command)
+
+    open_cmd = commands.add_parser("open", help="open a document in your browser")
+    open_cmd.add_argument("slug", help="the document's slug")
+    open_cmd.add_argument(
+        "--token",
+        action="store_true",
+        help="open the token URL even when an alias exists",
+    )
+    open_cmd.set_defaults(run=open_document)
+
+    alias_cmd = commands.add_parser(
+        "alias", help="add, edit, clear, or show a document's alias"
+    )
+    alias_cmd.add_argument("slug", help="the document's slug")
+    alias_cmd.add_argument(
+        "name", nargs="?", help="the alias to set (omit to print the current alias)"
+    )
+    alias_cmd.add_argument("--clear", action="store_true", help="remove the alias")
+    alias_cmd.set_defaults(run=alias_command)
+
+    grant_cmd = commands.add_parser(
+        "grant", help="mint a new share link for a document"
+    )
+    grant_cmd.add_argument("slug", help="the document's slug")
+    grant_cmd.add_argument(
+        "--label", help="a name for this link (default: auto-assigned)"
+    )
+    grant_cmd.add_argument(
+        "--expires",
+        help=(
+            "when this link expires: a duration (7d, 24h) or an ISO date "
+            "(2026-08-01); omit for a link that never expires"
+        ),
+    )
+    grant_cmd.set_defaults(run=grant_command)
+
+    revoke_cmd = commands.add_parser("revoke", help="revoke a document's share link")
+    revoke_cmd.add_argument("slug", help="the document's slug")
+    revoke_cmd.add_argument(
+        "handle", help="the link's short handle, from `docdrop grants`"
+    )
+    revoke_cmd.set_defaults(run=revoke_command)
+
+    grants_cmd = commands.add_parser("grants", help="list a document's share links")
+    grants_cmd.add_argument("slug", help="the document's slug")
+    grants_cmd.set_defaults(run=grants_command)
+
+    history_cmd = commands.add_parser("history", help="list a document's revisions")
+    history_cmd.add_argument("slug", help="the document's slug")
+    history_cmd.set_defaults(run=history_command)
+
+    diff_cmd = commands.add_parser(
+        "diff", help="show what changed between two revisions"
+    )
+    diff_cmd.add_argument("slug", help="the document's slug")
+    diff_cmd.add_argument(
+        "revisions",
+        nargs="*",
+        type=int,
+        metavar="N",
+        help="two revision numbers to diff (default: previous vs. head)",
+    )
+    diff_cmd.set_defaults(run=diff_command)
+
+    rollback_cmd = commands.add_parser(
+        "rollback", help="make an old revision the new head"
+    )
+    rollback_cmd.add_argument("slug", help="the document's slug")
+    rollback_cmd.add_argument(
+        "number", type=int, help="the revision number to roll back to"
+    )
+    rollback_cmd.set_defaults(run=rollback_command)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "servers":
+            return args.run(args)
+        client = Client(config_module.load(server=args.server))
+        return args.run(client, args)
+    except (ConfigError, DocDropError, UnsupportedFile) as exc:
+        print(exc, file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

docdrop-0.1.0/src/docdrop/client.py

@@ -0,0 +1,104 @@
+"""The HTTP client for a DocDrop app."""
+
+import httpx
+
+from .config import Config
+
+TIMEOUT = httpx.Timeout(30.0, connect=10.0)
+
+
+class DocDropError(Exception):
+    """Something the user needs to read: a refusal, or an unreachable app."""
+
+
+class Client:
+    def __init__(self, config: Config):
+        self._config = config
+
+    def publish(
+        self,
+        slug: str,
+        title: str,
+        content: str,
+        content_type: str,
+        alias: str | None = None,
+        clear_alias: bool = False,
+    ) -> dict:
+        body = {
+            "slug": slug,
+            "title": title,
+            "content": content,
+            "content_type": content_type,
+        }
+        if clear_alias:
+            body["clear_alias"] = True
+        elif alias is not None:
+            body["alias"] = alias
+        return self._call("POST", "/api/publish", json=body)
+
+    def alias(self, slug: str, name: str | None = None, clear: bool = False) -> dict:
+        body = {"slug": slug}
+        if clear:
+            body["clear"] = True
+        elif name is not None:
+            body["name"] = name
+        return self._call("POST", "/api/alias", json=body)
+
+    def documents(self) -> list[dict]:
+        return self._call("GET", "/api/documents")["documents"]
+
+    def grant(
+        self, slug: str, label: str | None = None, expires: str | None = None
+    ) -> dict:
+        body = {"slug": slug}
+        if label is not None:
+            body["label"] = label
+        if expires is not None:
+            body["expires"] = expires
+        return self._call("POST", "/api/grant", json=body)
+
+    def revoke(self, slug: str, handle: str) -> dict:
+        return self._call(
+            "POST", "/api/revoke", json={"slug": slug, "handle": handle}
+        )
+
+    def grants(self, slug: str) -> list[dict]:
+        return self._call("GET", "/api/grants", params={"slug": slug})["grants"]
+
+    def history(self, slug: str) -> list[dict]:
+        return self._call("GET", "/api/history", params={"slug": slug})["revisions"]
+
+    def diff(self, slug: str, a: int | None = None, b: int | None = None) -> dict:
+        params = {"slug": slug}
+        if a is not None and b is not None:
+            params["a"] = a
+            params["b"] = b
+        return self._call("GET", "/api/diff", params=params)
+
+    def rollback(self, slug: str, number: int) -> dict:
+        return self._call(
+            "POST", "/api/rollback", json={"slug": slug, "number": number}
+        )
+
+    def _call(self, method: str, path: str, **kwargs) -> dict:
+        url = f"{self._config.url}{path}"
+        headers = {"Authorization": f"Bearer {self._config.api_key}"}
+        try:
+            response = httpx.request(
+                method, url, headers=headers, timeout=TIMEOUT, **kwargs
+            )
+        except httpx.RequestError as exc:
+            raise DocDropError(f"Could not reach {self._config.url}: {exc}") from None
+
+        if response.is_success:
+            return response.json()
+
+        # The API reports refusals as {"error": "..."}; anything else (a proxy
+        # error page, say) has no message worth relaying, so show the status.
+        try:
+            message = response.json().get("error")
+        except ValueError:
+            message = None
+        raise DocDropError(
+            message or f"{self._config.url} returned HTTP {response.status_code}."
+        )

docdrop-0.1.0/src/docdrop/config.py

@@ -0,0 +1,129 @@
+"""Where the API key and server URL live.
+
+Config is read from $DOCDROP_CONFIG, else $XDG_CONFIG_HOME/docdrop/config.toml,
+else ~/.config/docdrop/config.toml.
+
+With named `[servers.<name>]` profiles, pick one with `--server` (or omit it
+and let the sole profile auto-default, or the one marked `default = true`
+when there are several):
+
+    [servers.production]
+    url = "https://docdrop.anvil.app"
+    api_key = "..."
+
+    [servers.local]
+    url = "http://localhost:3030"
+    api_key = "..."
+    default = true
+
+With no `[servers.*]` tables, the flat top-level keys are used instead (and
+DOCDROP_API_KEY / DOCDROP_URL, if set, override them):
+
+    api_key = "..."
+    url = "https://docdrop.anvil.app"
+"""
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Config:
+    api_key: str
+    url: str
+
+
+def config_path() -> Path:
+    if override := os.environ.get("DOCDROP_CONFIG"):
+        return Path(override)
+    base = os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config"
+    return Path(base) / "docdrop" / "config.toml"
+
+
+def _read_stored(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    try:
+        return tomllib.loads(path.read_text())
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{path} is not valid TOML: {exc}") from None
+
+
+def _finalize(api_key: str | None, url: str | None, path: Path) -> Config:
+    if not api_key or not url:
+        raise ConfigError(
+            f"Incomplete config: both api_key and url are required (see {path})."
+        )
+    return Config(api_key=api_key, url=url.rstrip("/"))
+
+
+def _servers_or_raise(server: str, servers: dict, path: Path) -> dict:
+    """Look up a named profile table, raising ConfigError if not found."""
+    if not servers:
+        raise ConfigError(
+            f"No server profiles defined in {path}. Add a [servers.{server}] "
+            "table, or omit --server."
+        )
+    if server not in servers:
+        names = ", ".join(sorted(servers))
+        raise ConfigError(f"No profile '{server}' (have: {names}).")
+    return servers[server]
+
+
+def _default_name(servers: dict) -> str | None:
+    """Resolve the implicit default profile name, or None if ambiguous."""
+    if len(servers) == 1:
+        return next(iter(servers))
+    marked = [name for name, table in servers.items() if table.get("default") is True]
+    return marked[0] if len(marked) == 1 else None
+
+
+def _default_table(servers: dict, path: Path) -> dict:
+    name = _default_name(servers)
+    if name is None:
+        raise ConfigError(
+            f"{len(servers)} server profiles in {path} but the default is "
+            f"ambiguous (have: {', '.join(sorted(servers))}). Mark exactly "
+            "one default = true, or pass --server."
+        )
+    return servers[name]
+
+
+def load(server: str | None = None) -> Config:
+    path = config_path()
+    stored = _read_stored(path)
+    servers = stored.get("servers", {})
+
+    if server is not None:
+        table = _servers_or_raise(server, servers, path)
+        return _finalize(table.get("api_key"), table.get("url"), path)
+
+    if servers:
+        table = _default_table(servers, path)
+        return _finalize(table.get("api_key"), table.get("url"), path)
+
+    api_key = os.environ.get("DOCDROP_API_KEY") or stored.get("api_key")
+    url = os.environ.get("DOCDROP_URL") or stored.get("url")
+    return _finalize(api_key, url, path)
+
+
+def list_servers(server: str | None = None) -> tuple[list[str], str | None]:
+    """Return (profile names, active name) without ever touching an api_key."""
+    path = config_path()
+    stored = _read_stored(path)
+    servers = stored.get("servers", {})
+
+    if not servers and server is None:
+        return ["(default)"], "(default)"
+
+    if server is not None:
+        _servers_or_raise(server, servers, path)
+        return sorted(servers), server
+
+    return sorted(servers), _default_name(servers)