geodeploy 1.3.0__py3-none-any.whl

geodeploy/cli/output.py

@@ -0,0 +1,320 @@
+"""Printing, tables, progress and exit codes — the only module allowed to write to a terminal.
+
+Three rules:
+
+* **stdout is the answer, stderr is the commentary.** `geodeploy layers list --json | jq` must
+  receive JSON and nothing else, so progress, warnings and "publish to make this live" hints all go
+  to stderr. This is also why a progress bar can never appear on stdout.
+* **`--json` is a contract.** With it, stdout is exactly one JSON document — including for errors,
+  which come back as `{"ok": false, "error": …}` so a script can read the failure instead of
+  scraping it.
+* **The exit code is the other contract.** A CI job branches on it long before it parses anything.
+"""
+from __future__ import annotations
+
+import json as _json
+import os
+import shutil
+import sys
+import time
+from typing import Any, Dict, Iterable, List, Optional, Sequence
+
+# ── Exit codes ───────────────────────────────────────────────────────────────────────────────────
+# Same matrix the docs publish. Separating AUTH from USAGE from SERVER is what lets a nightly job
+# alert on "your token expired" without alerting on "the instance is restarting".
+EXIT_OK = 0
+EXIT_GENERIC = 1      # the operation failed (a 4xx that is not auth, a bad file, a failed job)
+EXIT_USAGE = 2        # the command line itself was wrong — argparse's own convention
+EXIT_AUTH = 3         # 401/403: no credential, expired token, missing scope, or too low a role
+EXIT_NETWORK = 4      # never got an answer: DNS, TLS, connection reset, timeout
+EXIT_SERVER = 5       # 5xx: the instance is up but broke
+
+
+def _supports_color(stream) -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("GEODEPLOY_FORCE_COLOR"):
+        return True
+    if not hasattr(stream, "isatty") or not stream.isatty():
+        return False
+    if sys.platform.startswith("win"):
+        # Windows 10+ terminals understand ANSI once VT processing is on; enabling it is cheap and
+        # failing to enable it just means no colour, never mojibake.
+        try:
+            import ctypes
+            kernel32 = ctypes.windll.kernel32
+            kernel32.SetConsoleMode(kernel32.GetStdHandle(-11), 7)
+        except Exception:
+            return False
+    return True
+
+
+#: Typographic characters, and what to write instead on a console that cannot encode them.
+#: A Windows console still running code page 437 raises UnicodeEncodeError on "✓" — which would
+#: turn a SUCCESSFUL command into a traceback. Degrading the glyph is the only acceptable failure.
+#: `–` (EN dash) is not the same character as `—` (EM dash) and both reach a console: the em dash
+#: from our own output, the en dash from the SERVER, inside graduated legend labels ("10 – 90").
+_FALLBACKS = {"✓": "OK", "→": "->", "—": "-", "–": "-", "…": "...", "·": "-",
+              "≥": ">=", "≤": "<="}
+
+
+def _encodable(stream) -> bool:
+    encoding = getattr(stream, "encoding", None) or "utf-8"
+    try:
+        "".join(_FALLBACKS).encode(encoding)
+        return True
+    except (UnicodeEncodeError, LookupError):
+        return False
+
+
+class Formatter(object):
+    """Writes everything the CLI shows, honouring --json / --quiet / --verbose / NO_COLOR."""
+
+    def __init__(self, json_mode: bool = False, quiet: bool = False, verbose: bool = False,
+                 stdout=None, stderr=None):
+        self.json_mode = json_mode
+        self.quiet = quiet
+        self.verbose = verbose
+        self.stdout = stdout or sys.stdout
+        self.stderr = stderr or sys.stderr
+        self._color = _supports_color(self.stdout) and not json_mode
+        self._color_err = _supports_color(self.stderr) and not json_mode
+        self._plain = not (_encodable(self.stdout) and _encodable(self.stderr))
+
+    def _text(self, text: str) -> str:
+        if not self._plain:
+            return text
+        for fancy, plain in _FALLBACKS.items():
+            text = text.replace(fancy, plain)
+        return text
+
+    # -- styling ---------------------------------------------------------------------------------
+
+    def paint(self, text: str, code: str, err: bool = False) -> str:
+        enabled = self._color_err if err else self._color
+        return "\033[{0}m{1}\033[0m".format(code, text) if enabled else text
+
+    def dim(self, text: str, err: bool = False) -> str:
+        return self.paint(text, "2", err)
+
+    def bold(self, text: str, err: bool = False) -> str:
+        return self.paint(text, "1", err)
+
+    def green(self, text: str, err: bool = False) -> str:
+        return self.paint(text, "32", err)
+
+    def red(self, text: str, err: bool = False) -> str:
+        return self.paint(text, "31", err)
+
+    def yellow(self, text: str, err: bool = False) -> str:
+        return self.paint(text, "33", err)
+
+    # -- messages --------------------------------------------------------------------------------
+
+    def out(self, text: str = "") -> None:
+        """A line of the ANSWER — the thing the command was asked for."""
+        self.stdout.write(self._text(text) + "\n")
+
+    def info(self, text: str) -> None:
+        """Commentary: what happened, what to do next. Silent under --json/--quiet."""
+        if self.json_mode or self.quiet:
+            return
+        self.stderr.write(self._text(text) + "\n")
+
+    def success(self, text: str) -> None:
+        if self.json_mode or self.quiet:
+            return
+        self.stderr.write(self._text(self.green("✓ ", err=True) + text) + "\n")
+
+    def warn(self, text: str) -> None:
+        if self.json_mode or self.quiet:
+            return
+        self.stderr.write(self._text(self.yellow("warning: ", err=True) + text) + "\n")
+
+    def error(self, text: str, hint: Optional[str] = None) -> None:
+        """Errors always print, even under --quiet — silence on failure is how a CI job lies."""
+        if self.json_mode:
+            payload = {"ok": False, "error": text}
+            if hint:
+                payload["hint"] = hint
+            self.stdout.write(_json.dumps(payload, indent=2) + "\n")
+            return
+        self.stderr.write(self._text(self.red("error: ", err=True) + text) + "\n")
+        if hint:
+            self.stderr.write(self._text(self.dim("  " + hint, err=True)) + "\n")
+
+    def debug(self, text: str) -> None:
+        if self.verbose and not self.json_mode:
+            self.stderr.write(self._text(self.dim("· " + text, err=True)) + "\n")
+
+    # -- structured output -----------------------------------------------------------------------
+
+    def json(self, payload: Any) -> None:
+        self.stdout.write(_json.dumps(payload, indent=2, default=str, ensure_ascii=False) + "\n")
+
+    def render(self, payload: Any, columns: Optional[Sequence[Any]] = None,
+               empty: str = "Nothing to show.") -> None:
+        """The default way a command answers: JSON under --json, otherwise a table or a record."""
+        if self.json_mode:
+            self.json(payload)
+            return
+        if isinstance(payload, list):
+            if not payload:
+                self.info(empty)
+                return
+            self.table(payload, columns)
+        elif isinstance(payload, dict):
+            self.record(payload, columns)
+        elif payload is not None:
+            self.out(str(payload))
+
+    def table(self, rows: List[Dict[str, Any]], columns: Optional[Sequence[Any]] = None) -> None:
+        """A plain aligned table. `columns` is a list of keys, or (key, heading) pairs."""
+        if not rows:
+            return
+        if columns:
+            cols = [(c, c.replace("_", " ")) if isinstance(c, str) else c for c in columns]
+        else:
+            keys = []  # type: List[str]
+            for row in rows:
+                for key in row:
+                    if key not in keys:
+                        keys.append(key)
+            cols = [(k, k.replace("_", " ")) for k in keys]
+
+        cells = [[_cell(row.get(key)) for key, _ in cols] for row in rows]
+        widths = [len(str(head)) for _, head in cols]
+        for line in cells:
+            for i, value in enumerate(line):
+                widths[i] = max(widths[i], len(value))
+        # Keep the table inside the terminal: trim the widest column rather than wrapping, since a
+        # wrapped table is unreadable and the full value is one --json away.
+        budget = (shutil.get_terminal_size((100, 24)).columns
+                  if hasattr(self.stdout, "isatty") and self.stdout.isatty() else 1000)
+        while sum(widths) + 2 * (len(widths) - 1) > budget and max(widths) > 8:
+            widths[widths.index(max(widths))] -= 1
+
+        self.out(self.dim("  ".join(
+            str(head).upper().ljust(widths[i]) for i, (_, head) in enumerate(cols))))
+        for line in cells:
+            self.out("  ".join(_fit(value, widths[i]) for i, value in enumerate(line)))
+
+    def record(self, row: Dict[str, Any], keys: Optional[Sequence[str]] = None) -> None:
+        """One object as `key: value` lines — a portal, a layer, a job."""
+        items = [(k, row.get(k)) for k in keys] if keys else list(row.items())
+        width = max((len(str(k)) for k, _ in items), default=0)
+        for key, value in items:
+            if value is None and keys is None:
+                continue
+            self.out("{0}  {1}".format(self.dim(str(key).ljust(width)), _cell(value, wide=True)))
+
+    def progress(self, label: str, total: Optional[int] = None) -> "Progress":
+        return Progress(self, label, total)
+
+
+class Progress(object):
+    """A one-line progress bar on stderr, and a no-op when nobody is watching.
+
+    Rate and remaining bytes are shown rather than a spinner because the question during a 4 GB
+    upload is always "will this finish before I have to leave", and only a rate answers it.
+    """
+
+    def __init__(self, fmt: Formatter, label: str, total: Optional[int] = None):
+        self._f = fmt
+        self.label = label
+        self.total = total
+        self._last = 0.0
+        self._started = time.time()
+        self._active = (not fmt.json_mode and not fmt.quiet
+                        and hasattr(fmt.stderr, "isatty") and fmt.stderr.isatty())
+        self._done = False
+
+    def update(self, done: int, total: Optional[int] = None) -> None:
+        if not self._active:
+            return
+        if total:
+            self.total = total
+        now = time.time()
+        complete = self.total and done >= self.total
+        if not complete and now - self._last < 0.1:   # ~10 fps is plenty and keeps the CPU idle
+            return
+        self._last = now
+        elapsed = max(now - self._started, 1e-6)
+        rate = done / elapsed
+        if self.total:
+            fraction = min(max(done / float(self.total), 0.0), 1.0)
+            filled = int(round(fraction * 24))
+            bar = "#" * filled + "-" * (24 - filled)
+            text = "{0} [{1}] {2:3.0f}%  {3} / {4}  {5}/s".format(
+                self.label, bar, fraction * 100, human_size(done), human_size(self.total),
+                human_size(rate))
+        else:
+            text = "{0}  {1}  {2}/s".format(self.label, human_size(done), human_size(rate))
+        self._f.stderr.write("\r\033[K" + text)
+        self._f.stderr.flush()
+
+    def finish(self, message: Optional[str] = None) -> None:
+        if self._done:
+            return
+        self._done = True
+        if self._active:
+            self._f.stderr.write("\r\033[K")
+            self._f.stderr.flush()
+        if message:
+            self._f.info(message)
+
+    def __enter__(self) -> "Progress":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.finish()
+
+
+# ── value formatting ─────────────────────────────────────────────────────────────────────────────
+
+def human_size(num: float) -> str:
+    """Bytes as something readable. Binary units, because storage tooling reports binary units."""
+    value = float(num or 0)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if value < 1024 or unit == "TB":
+            return "{0:.0f} {1}".format(value, unit) if unit == "B" else "{0:.1f} {1}".format(value, unit)
+        value /= 1024.0
+    return "{0:.1f} TB".format(value)  # pragma: no cover - unreachable, loop returns
+
+
+def human_count(num: Any) -> str:
+    try:
+        return "{0:,}".format(int(num))
+    except (TypeError, ValueError):
+        return "—"
+
+
+def _cell(value: Any, wide: bool = False) -> str:
+    if value is None:
+        return "—"
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    if isinstance(value, (list, tuple)):
+        if not value:
+            return "—"
+        if all(isinstance(v, (int, float)) for v in value):
+            return ", ".join("{0:g}".format(v) for v in value)
+        return _json.dumps(value) if wide else "{0} item{1}".format(
+            len(value), "" if len(value) == 1 else "s")
+    if isinstance(value, dict):
+        return _json.dumps(value) if wide else "{0} key{1}".format(
+            len(value), "" if len(value) == 1 else "s")
+    text = str(value)
+    if len(text) == 19 and text[4] == "-" and text[10] == "T":      # an ISO timestamp
+        return text.replace("T", " ")
+    return text
+
+
+def _fit(text: str, width: int) -> str:
+    if len(text) <= width:
+        return text.ljust(width)
+    return text[: max(1, width - 1)] + "…"
+
+
+def iter_rows(payload: Any) -> Iterable[Dict[str, Any]]:  # pragma: no cover - convenience
+    return payload if isinstance(payload, list) else [payload]

geodeploy/client.py

@@ -0,0 +1,327 @@
+"""The GeoDeploy API client.
+
+This is the piece the QGIS plugin imports. It is deliberately a *library*: it never prints, never
+reads the config file, never calls `sys.exit` — it takes a URL and a credential, makes requests, and
+raises the typed errors in `errors.py`. Everything user-facing lives in `geodeploy.cli`.
+
+    from geodeploy import Client
+    gd = Client("https://geodeploy.example.org", token="gdp_…")
+    gd.whoami()
+    gd.uploads.upload("roads.gpkg", wait=True)
+    gd.portals.publish(3)
+
+Grouping is by API area (`gd.vector`, `gd.portals`, `gd.admin`, …) so that discovering the client
+in an editor mirrors discovering the API in `/api/docs`.
+"""
+from __future__ import annotations
+
+import json as _json
+import os
+from typing import Any, Callable, Dict, Optional, Union
+from urllib.parse import quote, urlencode, urljoin
+
+from . import errors
+from .transport import Request, Response, UrllibTransport
+
+__all__ = ["Client"]
+
+#: Sent on every request. An instance's access log is where an operator works out that "the API is
+#: hammering us" is in fact someone's nightly CLI job, so it names the tool and its version.
+def _default_user_agent() -> str:
+    from . import __version__
+    return "geodeploy-cli/{0}".format(__version__)
+
+
+class Client(object):
+    """A connection to one GeoDeploy instance.
+
+    Args:
+        url: instance origin, e.g. ``https://geodeploy.example.org`` (with or without ``/api``).
+        token: a scoped API token (``gdp_…``) from Settings → API tokens.
+        jwt: a session JWT instead of a token — what ``geodeploy login --password`` obtains. Admin
+            routes (`/admin/*`, ownership transfer, token management) REJECT API tokens by design,
+            so anything under `gd.admin` needs this rather than a `gdp_` token.
+        transport: anything with ``send(Request) -> Response``. Swap in a Qt/QGIS network stack to
+            inherit the host's proxy and certificate configuration.
+        timeout: seconds for ordinary API calls.
+        upload_timeout: seconds for calls that move file bytes — a 5 GB PUT over a slow link is not
+            a hung request, and killing it at 120 s would make big uploads impossible.
+    """
+
+    def __init__(self, url: str, token: Optional[str] = None, jwt: Optional[str] = None,
+                 transport: Optional[Any] = None, timeout: float = 120.0,
+                 upload_timeout: float = 3600.0, user_agent: Optional[str] = None,
+                 verify_tls: bool = True, retries: int = 2,
+                 on_request: Optional[Callable[[str, str], None]] = None):
+        from .config import normalize_url
+        self.url = normalize_url(url)
+        self.token = token or None
+        self.jwt = jwt or None
+        self.timeout = timeout
+        self.upload_timeout = upload_timeout
+        self.user_agent = user_agent or _default_user_agent()
+        self.transport = transport or UrllibTransport(verify_tls=verify_tls, retries=retries)
+        #: Called with (method, url) before each request — the CLI's `-v` uses it, and a plugin can
+        #: route it to the QGIS message log without this module knowing what logging is.
+        self.on_request = on_request
+
+        # Namespaces. Imported here rather than at module scope because each one imports this
+        # module for typing; the cost is one attribute lookup at construction.
+        from .admin import Admin, Users
+        from .catalog import Catalog
+        from .imports import Imports
+        from .jobs import Jobs
+        from .layers import Layers, RasterLayers, VectorLayers
+        from .portals import Portals
+        from .sources import Sources
+        from .uploads import Uploads
+
+        self.vector = VectorLayers(self)
+        self.raster = RasterLayers(self)
+        #: Backend-agnostic helpers: resolve a layer by id/uid/name across both kinds.
+        self.layers = Layers(self)
+        self.portals = Portals(self)
+        self.sources = Sources(self)
+        self.imports = Imports(self)
+        self.jobs = Jobs(self)
+        self.uploads = Uploads(self)
+        self.admin = Admin(self)
+        self.users = Users(self)
+        self.catalog = Catalog(self)
+
+    # ── URLs ─────────────────────────────────────────────────────────────────────────────────────
+
+    def api_url(self, path: str, params: Optional[Dict[str, Any]] = None) -> str:
+        """Absolute URL for an API path. `path` is relative to `/api` unless it already starts there."""
+        if path.startswith("http://") or path.startswith("https://"):
+            base = path
+        else:
+            clean = path if path.startswith("/") else "/" + path
+            if not clean.startswith("/api"):
+                clean = "/api" + clean
+            base = self.url + clean
+        query = _query(params)
+        return base + (("&" if "?" in base else "?") + query if query else "")
+
+    def absolute(self, url_or_path: str) -> str:
+        """Resolve something the API handed back (`/s3/…?X-Amz-…`) against this instance.
+
+        Presigned upload URLs come back RELATIVE for a managed MinIO — nginx proxies `/s3/` with
+        the signed Host preserved — and absolute for an external S3 endpoint. Both must work, and
+        only the client knows the origin.
+        """
+        if url_or_path.startswith("http://") or url_or_path.startswith("https://"):
+            return url_or_path
+        return urljoin(self.url + "/", url_or_path.lstrip("/"))
+
+    # ── Requests ─────────────────────────────────────────────────────────────────────────────────
+
+    def request(self, method: str, path: str, params: Optional[Dict[str, Any]] = None,
+                json: Any = None, body: Any = None, headers: Optional[Dict[str, str]] = None,
+                timeout: Optional[float] = None, auth: bool = True,
+                parse: bool = True, content_type: Optional[str] = None) -> Any:
+        """One API call. Returns parsed JSON by default, or the raw `Response` when `parse=False`."""
+        url = self.api_url(path, params)
+        hdrs = {"Accept": "application/json", "User-Agent": self.user_agent}
+        if auth:
+            hdrs.update(self.auth_headers())
+        if headers:
+            hdrs.update(headers)
+
+        data = body
+        if json is not None:
+            data = _json.dumps(json).encode("utf-8")
+            hdrs.setdefault("Content-Type", "application/json")
+        if content_type:
+            hdrs["Content-Type"] = content_type
+
+        if self.on_request:
+            self.on_request(method.upper(), url)
+        response = self.transport.send(
+            Request(method, url, hdrs, data, timeout if timeout is not None else self.timeout))
+        return self._handle(response, parse)
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None, **kw: Any) -> Any:
+        return self.request("GET", path, params=params, **kw)
+
+    def post(self, path: str, json: Any = None, **kw: Any) -> Any:
+        return self.request("POST", path, json=json, **kw)
+
+    def put(self, path: str, json: Any = None, **kw: Any) -> Any:
+        return self.request("PUT", path, json=json, **kw)
+
+    def delete(self, path: str, **kw: Any) -> Any:
+        return self.request("DELETE", path, **kw)
+
+    def send_absolute(self, method: str, url: str, body: Any = None,
+                      headers: Optional[Dict[str, str]] = None,
+                      timeout: Optional[float] = None) -> Response:
+        """A request to a URL that is NOT the API — a presigned storage PUT.
+
+        Auth headers are deliberately absent: a presigned URL carries its own signature in the
+        query string, and an extra `Authorization` header makes S3 reject the request as
+        double-authenticated. (The UI's api client has the same note for the same reason.)
+        """
+        hdrs = {"User-Agent": self.user_agent}
+        hdrs.update(headers or {})
+        if self.on_request:
+            self.on_request(method.upper(), url)
+        return self.transport.send(
+            Request(method, self.absolute(url), hdrs, body,
+                    timeout if timeout is not None else self.upload_timeout))
+
+    def download(self, path: str, sink, params: Optional[Dict[str, Any]] = None,
+                 auth: bool = True, timeout: Optional[float] = None) -> Response:
+        """Stream a GET into a writable binary file object (COG, PMTiles, an export bundle)."""
+        url = self.api_url(path, params)
+        hdrs = {"User-Agent": self.user_agent}
+        if auth:
+            hdrs.update(self.auth_headers())
+        streamer = getattr(self.transport, "stream", None)
+        if streamer is None:  # a custom transport without streaming: fall back to buffered
+            response = self.transport.send(Request("GET", url, hdrs, None,
+                                                   timeout or self.upload_timeout))
+            self._handle(response, parse=False)
+            sink.write(response.content)
+            return response
+        response = streamer(Request("GET", url, hdrs, None, timeout or self.upload_timeout), sink)
+        return self._handle(response, parse=False)
+
+    def auth_headers(self) -> Dict[str, str]:
+        if self.token:
+            return {"Authorization": "Bearer " + self.token}
+        if self.jwt:
+            return {"Authorization": "Bearer " + self.jwt}
+        return {}
+
+    # ── Responses ────────────────────────────────────────────────────────────────────────────────
+
+    def _handle(self, response: Response, parse: bool = True) -> Any:
+        if response.status >= 400:
+            raise errors.from_status(response.status, _detail(response), response.url,
+                                     _safe_json(response))
+        if not parse:
+            return response
+        if response.status == 204 or not response.content:
+            return None
+        ctype = response.headers.get("content-type", "")
+        if "json" in ctype:
+            return response.json()
+        return response.text
+
+    # ── Identity ─────────────────────────────────────────────────────────────────────────────────
+
+    def whoami(self) -> Dict[str, Any]:
+        """The authenticated user (`GET /auth/me`). Works for both a token and a session JWT."""
+        return self.get("/auth/me")
+
+    def login(self, email: str, password: str) -> str:
+        """Exchange a password for a session JWT, store it on this client, and return it.
+
+        Needed for the routes that refuse API tokens on purpose (`/admin/*`, `/tokens`, ownership
+        transfer): a leaked token must not be able to reconfigure the instance or mint more tokens.
+        """
+        form = urlencode({"username": email, "password": password}).encode()
+        data = self.request("POST", "/auth/login", body=form, auth=False,
+                            content_type="application/x-www-form-urlencoded")
+        jwt = (data or {}).get("access_token")
+        if not jwt:
+            raise errors.AuthError(401, "Login did not return a token.", self.api_url("/auth/login"))
+        self.jwt = jwt
+        self.token = None  # a session supersedes any token on this client instance
+        return jwt
+
+    def setup_status(self) -> Dict[str, Any]:
+        """Public: whether the instance is set up, and which login methods it offers."""
+        return self.get("/setup/status", auth=False)
+
+    def tokens(self) -> Any:
+        """List the acting user's API tokens (session auth only — a token cannot list tokens)."""
+        return self.get("/tokens")
+
+    def create_token(self, name: str, scopes, expires_in_days: int = 90) -> Dict[str, Any]:
+        """Mint an API token. The raw `gdp_…` secret is in the response and never retrievable again."""
+        return self.post("/tokens", {"name": name, "scopes": list(scopes),
+                                     "expires_in_days": expires_in_days})
+
+    def revoke_token(self, token_id: int) -> Any:
+        return self.delete("/tokens/{0}".format(int(token_id)))
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        how = "token" if self.token else ("session" if self.jwt else "anonymous")
+        return "<geodeploy.Client {0} ({1})>".format(self.url, how)
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────────────────────────
+
+def _query(params: Optional[Dict[str, Any]]) -> str:
+    """Encode query params, dropping Nones and flattening lists — `?bbox=…&ids=a&ids=b`."""
+    if not params:
+        return ""
+    pairs = []
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            pairs.append((key, "true" if value else "false"))
+        elif isinstance(value, (list, tuple)):
+            for item in value:
+                if item is not None:
+                    pairs.append((key, str(item)))
+        else:
+            pairs.append((key, str(value)))
+    return urlencode(pairs)
+
+
+def _safe_json(response: Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+def _detail(response: Response) -> str:
+    """The most useful one-line message an error response contains.
+
+    FastAPI puts a string in `detail` for a raised HTTPException and a LIST of field errors there
+    for a validation failure; nginx returns HTML. All three have to become something a person can
+    read on one line, because that line is what the CLI prints.
+    """
+    payload = _safe_json(response)
+    if isinstance(payload, dict):
+        detail = payload.get("detail")
+        if isinstance(detail, str):
+            return detail
+        if isinstance(detail, list):
+            parts = []
+            for item in detail:
+                if isinstance(item, dict):
+                    loc = ".".join(str(x) for x in (item.get("loc") or [])[1:])
+                    parts.append("{0}: {1}".format(loc, item.get("msg")) if loc else str(item.get("msg")))
+                else:
+                    parts.append(str(item))
+            return "; ".join(parts)
+        if detail is not None:
+            return str(detail)
+        for key in ("message", "error"):
+            if payload.get(key):
+                return str(payload[key])
+    text = (response.text or "").strip()
+    if text.startswith("<"):  # an nginx/proxy HTML page — the status is the only real information
+        return {413: "Request body too large for the server or a proxy in front of it.",
+                502: "Bad gateway — the instance is up but the API did not answer.",
+                504: "Gateway timeout."}.get(response.status, "HTTP {0}".format(response.status))
+    return text[:500] or "HTTP {0}".format(response.status)
+
+
+def path_segment(value: Any) -> str:
+    """URL-quote one path segment (a slug, a uid, a storage key)."""
+    return quote(str(value), safe="")
+
+
+def env_client(**kw: Any) -> Client:
+    """A client from `GEODEPLOY_URL` / `GEODEPLOY_TOKEN` alone — for scripts and doctests."""
+    url = os.environ.get("GEODEPLOY_URL")
+    if not url:
+        raise errors.ConfigError("Set GEODEPLOY_URL (and usually GEODEPLOY_TOKEN).")
+    return Client(url, token=os.environ.get("GEODEPLOY_TOKEN"), **kw)