geodeploy 1.3.0__py3-none-any.whl

geodeploy/cli/commands/browse.py

@@ -0,0 +1,224 @@
+"""`geodeploy browse` — point at an instance and see what it offers.
+
+The one command that needs no account: give it a URL and it prints the public portals and the
+public layers, grouped by how they are stored, with the URL each one is best consumed by. With a
+token it also shows what that token can see — which is the same two-mode behaviour a desktop
+plugin needs, and the reason this exists in the client rather than only in a plugin.
+"""
+from __future__ import annotations
+
+from ...config import split_portal_url
+from ...errors import GeoDeployError, NotFoundError
+from ..main import add_command
+from ..output import EXIT_GENERIC, EXIT_OK
+
+KIND_LABEL = {"postgis": "Vector (PostGIS)", "geoparquet": "Vector (GeoParquet)",
+              "raster": "Raster (COG)"}
+
+
+def register(subparsers) -> None:
+    parser = add_command(
+        subparsers, "browse", cmd_browse,
+        "see what an instance publishes — no account needed",
+        epilog="""\
+examples:
+  geodeploy browse https://geodeploy.example.org      anyone can run this
+  geodeploy browse                                    the instance you are logged in to
+  geodeploy browse --portal field-sites-2026          what one portal contains
+  geodeploy browse https://gd.example.org/portals/5b5c627cfd/    a portal URL, pasted whole
+  geodeploy browse --json | jq '.layers.raster'       machine-readable
+
+With a token stored (or --token), it also reports what that token can see beyond the public
+surface, which is usually the point of having one.
+""")
+    parser.add_argument("instance", nargs="?",
+                        help="instance URL, or a published portal's URL "
+                             "(default: the active profile)")
+    parser.add_argument("--portal", metavar="SLUG_OR_URL",
+                        help="show one portal's layers, read from its published style")
+    parser.add_argument("--kind", choices=["raster", "postgis", "geoparquet"],
+                        help="only this kind of layer")
+    parser.add_argument("--links", action="store_true",
+                        help="print every access URL for each layer, not just a summary")
+
+
+def cmd_browse(ctx, args) -> int:
+    instance = args.instance
+    if instance and not args.portal and "/portals/" in instance:
+        # A portal's own URL, pasted whole. It names both the instance and the portal, so it does
+        # not need --portal and must not be read as an instance URL.
+        instance, args.portal = split_portal_url(instance)
+    elif args.portal:
+        origin, args.portal = split_portal_url(args.portal)
+        instance = instance or origin     # a full portal URL brings its instance with it
+    if instance:
+        args.url = instance               # the positional is just a friendlier --url
+        ctx._resolved = None              # re-resolve against it
+    client = ctx.client(auth_required=False)
+    out = ctx.out
+
+    if args.portal:
+        return _one_portal(ctx, client, args)
+
+    try:
+        index = client.catalog.public()
+    except NotFoundError:
+        out.error("{0} does not publish a public index.".format(client.url),
+                  hint="An admin can turn it on in Settings, or you can list what your token can "
+                       "see with `geodeploy layers list` and `geodeploy portals list`.")
+        return EXIT_GENERIC
+
+    if out.json_mode:
+        payload = dict(index)
+        private = _private_view(ctx)
+        if private:
+            payload["with_your_token"] = private
+        out.json(payload)
+        return EXIT_OK
+
+    counts = index.get("counts") or {}
+    out.out(out.bold("{0}".format(client.url)))
+    out.out(out.dim("{0} public portal(s), {1} public layer(s)".format(
+        counts.get("portals", 0),
+        sum(v for k, v in counts.items() if k != "portals"))))
+
+    portals = index.get("portals") or []
+    if portals:
+        out.out("")
+        out.out(out.bold("Portals"))
+        out.table([{"slug": p.get("slug"), "title": p.get("title"),
+                    "experience": p.get("experience"), "layers": p.get("layer_count"),
+                    "url": p.get("url")} for p in portals],
+                  ["slug", "title", "experience", "layers", "url"])
+
+    layers = index.get("layers") or {}
+    for kind in ("postgis", "geoparquet", "raster"):
+        rows = layers.get(kind) or []
+        if not rows or (args.kind and args.kind != kind):
+            continue
+        out.out("")
+        out.out(out.bold("{0} — {1}".format(KIND_LABEL[kind], len(rows))))
+        out.table([{"id": r.get("id"), "name": r.get("name"),
+                    "geometry": r.get("geometry_type") or ("{0} band(s)".format(r.get("band_count"))
+                                                           if r.get("band_count") else None),
+                    "features": r.get("feature_count"), "crs": r.get("crs"),
+                    "licence": r.get("license")} for r in rows],
+                  ["id", "name", "geometry", "features", "crs", "licence"])
+        if args.links:
+            for row in rows:
+                out.out("")
+                out.out("  " + out.bold(row.get("name") or "?"))
+                for link in row.get("links") or []:
+                    out.out("    {0}  {1}".format(link.get("label"), link.get("url")))
+
+    catalogs = index.get("catalogs") or {}
+    out.out("")
+    out.info("Standards: OGC API - Features {0} · STAC {1}".format(
+        catalogs.get("ogc_features"), catalogs.get("stac")))
+
+    private = _private_view(ctx)
+    if private:
+        out.info("With your token: {0} layer(s) and {1} portal(s) in total — "
+                 "`geodeploy layers list` shows them.".format(private["layers"], private["portals"]))
+    elif not ctx.resolved.token:
+        out.info("No token in use: this is the anonymous view. `geodeploy login <url> --token …` "
+                 "to see everything you have access to.")
+    return EXIT_OK
+
+
+def _private_view(ctx):
+    """What the caller's own credential can see, when there is one. Best-effort by design:
+    browsing must not fail because a token expired."""
+    if not (ctx.resolved.token or ctx.resolved.jwt):
+        return None
+    try:
+        client = ctx.client(auth_required=False)
+        return {"layers": len(client.layers.list()), "portals": len(client.portals.list())}
+    except GeoDeployError:
+        return None
+
+
+def _one_portal(ctx, client, args) -> int:
+    """Read a published portal's own style.json — the whole portal, anonymously."""
+    out = ctx.out
+    slug = args.portal
+    style_url = "{0}/portals/{1}/style.json".format(client.url, slug)
+    try:
+        style = client.catalog.portal_style(style_url)
+    except GeoDeployError as exc:
+        out.error("Could not read portal {0!r}: {1}".format(slug, exc),
+                  hint="Public portals only — a password or members-only portal will not open "
+                       "without a session.")
+        return EXIT_GENERIC
+
+    meta = style.get("geodeploy") or {}
+    if out.json_mode:
+        out.json(style)
+        return EXIT_OK
+
+    out.out(out.bold(meta.get("title") or slug))
+    out.out(out.dim("{0}/portals/{1}/".format(client.url, slug)))
+    out.out("")
+
+    sources = style.get("sources") or {}
+    rows, urls = [], {}
+    for layer in _data_layers(style):
+        lmeta = layer.get("metadata") or {}
+        source = layer.get("source")
+        row = {"name": lmeta.get("geodeploy:name") or layer.get("id"),
+               "kind": lmeta.get("geodeploy:geometry") or layer.get("type"),
+               "id": layer.get("id"),
+               "visible": "no" if _hidden(layer) else "yes"}
+        rows.append(row)
+        urls[row["id"]] = _source_url(sources.get(source) or {})
+    for deck in meta.get("deckLayers") or []:
+        ident = deck.get("id") or deck.get("name")
+        rows.append({"name": deck.get("name") or ident, "kind": "GeoParquet (deck.gl)",
+                     "id": ident, "visible": "no" if deck.get("visible") is False else "yes"})
+        urls[ident] = deck.get("url") or deck.get("manifest") or ""
+
+    columns = ["name", "kind", "id"]
+    if any(r["visible"] == "no" for r in rows):
+        columns.append("visible")       # only worth a column when something is actually off
+    out.table(rows, columns)
+
+    if args.links:
+        out.out("")
+        for row in rows:
+            if urls.get(row["id"]):
+                out.out("  {0}  {1}".format(out.bold(row["name"]), urls[row["id"]]))
+    if meta.get("bounds"):
+        out.info("Extent: {0}".format(meta["bounds"]))
+    if not args.links:
+        out.info("`--links` adds the data URL behind each layer.")
+    return EXIT_OK
+
+
+def _data_layers(style):
+    """The author's layers, without the basemap's and without counting one layer twice.
+
+    A layer can be drawn by several MapLibre layers (a fill plus its outline, a polygon plus its
+    3D pillars); the generator flags the extras `geodeploy:part` and puts the metadata on the
+    first, which is exactly the rule the portal's own layer switcher follows.
+    """
+    layers = style.get("layers") or []
+    tagged = [l for l in layers
+              if (l.get("metadata") or {}).get("geodeploy:layer_id") is not None
+              and not (l.get("metadata") or {}).get("geodeploy:part")]
+    if tagged:
+        return tagged
+    # An older bundle, published before the metadata existed: fall back to "not the basemap".
+    return [l for l in layers
+            if l.get("source") and l.get("source") not in ("basemap", "composite")]
+
+
+def _hidden(layer):
+    return ((layer.get("layout") or {}).get("visibility")) == "none"
+
+
+def _source_url(source):
+    """Where a MapLibre source actually reads from — a tile template, a TileJSON or inline data."""
+    tiles = source.get("tiles")
+    if tiles:
+        return tiles[0]
+    return source.get("url") or (source.get("data") if isinstance(source.get("data"), str) else "")

geodeploy/cli/commands/catalog.py

@@ -0,0 +1,107 @@
+"""`geodeploy catalog …` — the public surfaces: OGC API - Features, STAC, templates, basemaps.
+
+These need no credentials, which makes this group the honest way to check what you have actually
+published: if a layer is not listed here, nobody outside your organisation can see it either.
+"""
+from __future__ import annotations
+
+import json
+
+from ..main import add_command, group_parser
+from ..output import EXIT_OK
+
+
+def register(subparsers) -> None:
+    group = group_parser(subparsers, "catalog",
+                         "what this instance publishes: OGC API - Features, STAC, templates")
+
+    add_command(group, "collections", cmd_collections,
+                "OGC API - Features collections (one per public vector layer)")
+
+    items = add_command(group, "items", cmd_items, "features from a collection")
+    items.add_argument("collection", help="collection id, e.g. vector-a1b2c3d4e5f6")
+    items.add_argument("--bbox", help="minx,miny,maxx,maxy")
+    items.add_argument("--limit", type=int, default=10)
+    items.add_argument("--offset", type=int, default=0)
+
+    add_command(group, "conformance", cmd_conformance,
+                "what the OGC endpoint claims to support")
+
+    stac = add_command(group, "stac", cmd_stac, "the STAC catalog root and its collections")
+    stac.add_argument("--collection", help="list items in this collection (vectors | rasters)")
+    stac.add_argument("--limit", type=int, default=20)
+
+    search = add_command(group, "search", cmd_search, "STAC search across public layers")
+    search.add_argument("--bbox")
+    search.add_argument("--collections")
+    search.add_argument("--datetime", dest="datetime_", help="instant or start/end (.. is open)")
+    search.add_argument("--ids")
+    search.add_argument("--limit", type=int, default=20)
+
+    add_command(group, "templates", cmd_templates, "portal templates and the experiences they suit")
+    add_command(group, "basemaps", cmd_basemaps, "basemaps available to portals")
+
+
+def _client(ctx):
+    # Public endpoints: a URL is enough, no credential required.
+    return ctx.client(auth_required=False)
+
+
+def cmd_collections(ctx, args) -> int:
+    rows = _client(ctx).catalog.collections()
+    ctx.out.render([{"id": c.get("id"), "title": c.get("title"),
+                     "extent": ((c.get("extent") or {}).get("spatial") or {}).get("bbox")}
+                    for c in rows], ["id", "title", "extent"],
+                   empty="No public collections — share a vector layer publicly to add one.")
+    return EXIT_OK
+
+
+def cmd_items(ctx, args) -> int:
+    data = _client(ctx).catalog.items(args.collection, bbox=args.bbox, limit=args.limit,
+                                      offset=args.offset)
+    if ctx.out.json_mode:
+        ctx.out.json(data)
+        return EXIT_OK
+    ctx.out.info("{0} returned, {1} matched.".format(data.get("numberReturned"),
+                                                     data.get("numberMatched", "unknown")))
+    ctx.out.out(json.dumps(data, indent=2, ensure_ascii=False)[:20000])
+    return EXIT_OK
+
+
+def cmd_conformance(ctx, args) -> int:
+    ctx.out.render((_client(ctx).catalog.conformance() or {}).get("conformsTo") or [])
+    return EXIT_OK
+
+
+def cmd_stac(ctx, args) -> int:
+    catalog = _client(ctx).catalog
+    if args.collection:
+        ctx.out.render(catalog.stac_items(args.collection, limit=args.limit))
+        return EXIT_OK
+    ctx.out.render([{"id": c.get("id"), "title": c.get("title"), "description": c.get("description")}
+                    for c in catalog.stac_collections()], ["id", "title", "description"])
+    return EXIT_OK
+
+
+def cmd_search(ctx, args) -> int:
+    data = _client(ctx).catalog.search(bbox=args.bbox, collections=args.collections,
+                                       datetime=args.datetime_, ids=args.ids, limit=args.limit)
+    if ctx.out.json_mode:
+        ctx.out.json(data)
+        return EXIT_OK
+    features = data.get("features") or []
+    ctx.out.table([{"id": f.get("id"), "collection": f.get("collection"),
+                    "assets": ", ".join(sorted((f.get("assets") or {}).keys()))}
+                   for f in features], ["id", "collection", "assets"])
+    return EXIT_OK
+
+
+def cmd_templates(ctx, args) -> int:
+    ctx.out.render(_client(ctx).catalog.templates(),
+                   ["id", "name", "archetypes", "archetype", "tags", "is_official", "version"])
+    return EXIT_OK
+
+
+def cmd_basemaps(ctx, args) -> int:
+    ctx.out.render(_client(ctx).catalog.basemaps(), ["id", "name", "type", "attribution"])
+    return EXIT_OK

geodeploy/cli/commands/imports.py

@@ -0,0 +1,125 @@
+"""`geodeploy import …` — register data that is already in the database or the bucket.
+
+Nothing is copied and nothing is moved: a PostGIS table is introspected and registered where it
+stands, and an object in storage is attached by key. This is how you point a fresh instance at
+data that is already on the server, without a round trip through your laptop.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from ..main import add_command, group_parser
+from ..output import EXIT_GENERIC, EXIT_OK
+
+
+def register(subparsers) -> None:
+    group = group_parser(subparsers, "import", "register existing PostGIS tables or storage objects",
+                         aliases=["discover"])
+
+    db_list = add_command(group, "db-list", cmd_db_list,
+                          "spatial tables in the database, and whether they are registered")
+    db_list.add_argument("--all", action="store_true", help="include already-imported tables")
+
+    db_add = add_command(group, "db-add", cmd_db_add, "register PostGIS tables as layers",
+                         epilog="examples:\n  geodeploy import db-add public.roads public.sites\n")
+    db_add.add_argument("tables", nargs="+", help="schema.table (as listed by db-list)")
+    db_add.add_argument("--name", help="display name (single table only)")
+
+    st_list = add_command(group, "storage-list", cmd_storage_list,
+                          "GeoTIFF / GeoParquet / CSV objects in the bucket")
+    st_list.add_argument("--kind", choices=["raster", "geoparquet", "csv"])
+
+    st_add = add_command(group, "storage-add", cmd_storage_add,
+                         "attach storage objects as layers (GeoParquet is inspected + prepared)")
+    st_add.add_argument("keys", nargs="+", help="object keys as listed by storage-list")
+    st_add.add_argument("--name", help="display name (single object only)")
+    st_add.add_argument("--wait", action="store_true", help="wait for any queued jobs")
+
+    csv_cols = add_command(group, "csv-columns", cmd_csv_columns, "header of a CSV in the bucket")
+    csv_cols.add_argument("key")
+    csv_cols.add_argument("--delimiter", default="comma",
+                          choices=["comma", "semicolon", "tab", "pipe", "space"])
+
+    csv_add = add_command(group, "csv", cmd_csv, "build a PostGIS layer from a CSV in the bucket")
+    csv_add.add_argument("key")
+    csv_add.add_argument("--name")
+    csv_add.add_argument("--x", dest="x_column")
+    csv_add.add_argument("--y", dest="y_column")
+    csv_add.add_argument("--wkt", dest="wkt_column")
+    csv_add.add_argument("--srid", type=int, default=4326)
+    csv_add.add_argument("--delimiter", default="comma",
+                         choices=["comma", "semicolon", "tab", "pipe", "space"])
+    csv_add.add_argument("--wait", action="store_true")
+
+
+def cmd_db_list(ctx, args) -> int:
+    rows = ctx.client().imports.database_tables()
+    if not args.all:
+        rows = [r for r in rows if not r.get("imported")]
+    ctx.out.render(rows, ["schema_name", "table_name", "geometry_column", "geometry_type", "srid",
+                          "imported"],
+                   empty="No spatial tables found (or all of them are already registered).")
+    return EXIT_OK
+
+
+def cmd_db_add(ctx, args) -> int:
+    available = {"{0}.{1}".format(r.get("schema_name"), r.get("table_name")): r
+                 for r in ctx.client().imports.database_tables()}
+    tables = []  # type: List[Dict[str, Any]]
+    for ref in args.tables:
+        found = available.get(ref)
+        if not found:
+            ctx.out.error("No spatial table {0!r}. `geodeploy import db-list` shows what there is."
+                          .format(ref))
+            return EXIT_GENERIC
+        entry = {"schema_name": found["schema_name"], "table_name": found["table_name"],
+                 "geometry_column": found.get("geometry_column"),
+                 "srid": found.get("srid") or 0,
+                 "geometry_type": found.get("geometry_type")}
+        if args.name and len(args.tables) == 1:
+            entry["name"] = args.name
+        tables.append(entry)
+    result = ctx.client().imports.database(tables)
+    ctx.out.render(result)
+    if not ctx.out.json_mode:
+        ctx.out.success("Registered {0} table(s).".format(len(tables)))
+    return EXIT_OK
+
+
+def cmd_storage_list(ctx, args) -> int:
+    ctx.out.render(ctx.client().imports.storage_objects(args.kind),
+                   ["key", "kind", "size", "imported"], empty="Nothing importable in the bucket.")
+    return EXIT_OK
+
+
+def cmd_storage_add(ctx, args) -> int:
+    items = [{"key": key} for key in args.keys]
+    if args.name and len(items) == 1:
+        items[0]["name"] = args.name
+    result = ctx.client().imports.storage(items)
+    jobs = (result or {}).get("jobs") or []
+    ctx.out.render(result)
+    if args.wait and jobs:
+        for job in jobs:
+            ctx.client().jobs.wait(job.get("id"), "vector",
+                                   on_progress=lambda st: ctx.out.info("  {0:3d}%  {1}".format(
+                                       st.get("progress") or 0, st.get("current_step") or "")))
+        ctx.out.success("All queued imports finished.")
+    return EXIT_OK
+
+
+def cmd_csv_columns(ctx, args) -> int:
+    ctx.out.render(ctx.client().imports.csv_columns(args.key, args.delimiter))
+    return EXIT_OK
+
+
+def cmd_csv(ctx, args) -> int:
+    job = ctx.client().imports.csv(args.key, name=args.name, x_column=args.x_column,
+                                   y_column=args.y_column, wkt_column=args.wkt_column,
+                                   srid=args.srid, delimiter=args.delimiter)
+    if args.wait and job.get("id"):
+        job = ctx.client().jobs.wait(job["id"], "vector",
+                                     on_progress=lambda st: ctx.out.info("  {0:3d}%  {1}".format(
+                                         st.get("progress") or 0, st.get("current_step") or "")))
+    ctx.out.render(job)
+    return EXIT_OK

geodeploy/cli/commands/jobs.py

@@ -0,0 +1,38 @@
+"""`geodeploy jobs …` — ingest jobs, and waiting for one."""
+from __future__ import annotations
+
+from ..main import add_command, group_parser
+from ..output import EXIT_OK
+
+
+def register(subparsers) -> None:
+    group = group_parser(subparsers, "jobs", "ingest job status")
+
+    show = add_command(group, "show", cmd_show, "the current state of a job")
+    show.add_argument("job_id")
+    show.add_argument("--type", dest="layer_type", choices=["vector", "raster"], default="vector")
+
+    watch = add_command(group, "watch", cmd_watch, "follow a job until it finishes")
+    watch.add_argument("job_id")
+    watch.add_argument("--type", dest="layer_type", choices=["vector", "raster"], default="vector")
+    watch.add_argument("--interval", type=float, default=2.0)
+    watch.add_argument("--max-wait", dest="max_wait", type=float, default=3600.0,
+                       help="give up after this many seconds (the job keeps running server-side)")
+
+
+def cmd_show(ctx, args) -> int:
+    ctx.out.render(ctx.client().jobs.get(args.job_id, args.layer_type),
+                   ["id", "layer_id", "layer_type", "status", "progress", "current_step",
+                    "error_message"])
+    return EXIT_OK
+
+
+def cmd_watch(ctx, args) -> int:
+    final = ctx.client().jobs.wait(
+        args.job_id, args.layer_type, interval=args.interval, timeout=args.max_wait,
+        on_progress=lambda st: ctx.out.info("  {0:3d}%  {1}".format(
+            st.get("progress") or 0, st.get("current_step") or st.get("status") or "")))
+    ctx.out.render(final, ["id", "layer_id", "layer_type", "status", "progress", "current_step"])
+    if not ctx.out.json_mode:
+        ctx.out.success("Job {0} finished.".format(args.job_id))
+    return EXIT_OK