geodeploy 1.3.0__tar.gz

geodeploy-1.3.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Koffi Dodji Noumonvi
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

geodeploy-1.3.0/MANIFEST.in

@@ -0,0 +1,6 @@
+# The sdist should be enough to run the tests from, so a packager or a distro can verify the
+# release rather than take the wheel on trust. LICENSE, NOTICE and PYPI.md come in automatically
+# from the metadata; the tests do not.
+recursive-include tests *.py
+include README.md
+global-exclude __pycache__/* *.py[cod]

geodeploy-1.3.0/NOTICE

@@ -0,0 +1,11 @@
+GeoDeploy
+Copyright 2026 Koffi Dodji Noumonvi
+
+This product includes software developed for the GeoDeploy project
+(https://github.com/bravemaster3/GeoDeploy).
+
+Licensed under the Apache License, Version 2.0. See LICENSE.
+
+GeoDeploy runs alongside third-party services (PostGIS, MinIO, Martin, TiTiler,
+Redis, nginx) and bundles third-party libraries, each under its own licence.
+Those services run as separate processes; their licences are unaffected by this one.

geodeploy-1.3.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: geodeploy
+Version: 1.3.0
+Summary: Command-line client and Python API for GeoDeploy — upload spatial data, build and publish portals.
+Author: Koffi Dodji Noumonvi
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/bravemaster3/GeoDeploy
+Project-URL: Documentation, https://docs-geodeploy.kndev.org/cli/
+Project-URL: Repository, https://github.com/bravemaster3/GeoDeploy
+Project-URL: Issues, https://github.com/bravemaster3/GeoDeploy/issues
+Project-URL: Changelog, https://github.com/bravemaster3/GeoDeploy/blob/main/CHANGELOG.md
+Keywords: gis,geospatial,postgis,geoparquet,cog,maplibre,qgis,stac,ogc-api-features,geodeploy
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# geodeploy
+
+**Command-line client and Python API for [GeoDeploy](https://github.com/bravemaster3/GeoDeploy)** —
+the self-hosted spatial data platform and geoportal builder.
+
+Upload data, style it, build a portal and publish it, without opening a browser:
+
+```bash
+pip install geodeploy
+
+geodeploy login https://geodeploy.example.org --token gdp_…
+geodeploy upload roads.gpkg sites.csv dem.tif --wait
+geodeploy portals create "Field sites 2026" --publish
+```
+
+**No dependencies. Python 3.9+.** Every request goes through the standard library, so installing
+this pulls in nothing else — and a QGIS plugin can vendor the same client without asking anyone to
+pip-install into QGIS.
+
+If your shell cannot find `geodeploy` after installing, pip's scripts directory is not on your
+`PATH` — `python -m geodeploy` works regardless, and `pipx install geodeploy` or a virtual
+environment avoids it.
+
+## What it covers
+
+- **Uploads** — shapefile, GeoPackage, GeoJSON, CSV (X/Y or WKT), GeoParquet, GeoTIFF. Many files
+  in one command; the route is chosen per file, and anything over 48 MB goes direct to object
+  storage in parallel presigned parts, so a multi-gigabyte upload survives a proxy that caps
+  request bodies.
+- **Layers** — list, inspect, rename, share (STAC / OGC API - Features opt-in), share links per
+  tool, download, delete, restart a stalled ingest.
+- **Symbology** — colour, opacity, outlines, dashes, markers, raster colormaps and stretches, plus
+  data-driven styling: `--color-field pop --classify jenks --classes 6 --ramp magma`, proportional
+  size, and attribute-driven 3D. Classification is computed by the instance, with the same code the
+  portal editor uses, so the CLI and the editor can never disagree about a class.
+- **Portals** — create (web map, story map or catalog), arrange and style layers, folders, About
+  page, assets, access tiers, publish, and a whole-configuration JSON round trip for version
+  control.
+- **Everything else** — external WMS/XYZ/WFS services, registering data already in PostGIS or the
+  bucket, the public STAC and OGC API - Features catalog, ingest jobs, users, and instance
+  administration (health, services, updates, backups, activity log).
+
+Every command takes `--json`, where stdout is exactly one JSON document, and exit codes distinguish
+authentication (3) from network (4) from server (5) so a scheduled job can alert on the right thing.
+
+## As a library
+
+```python
+from geodeploy import Client
+
+gd = Client("https://geodeploy.example.org", token="gdp_…")
+result = gd.uploads.upload("roads.gpkg", wait=True)
+portal = gd.portals.create("Roads")
+gd.portals.add_layer(portal["id"], result.layer_id, "vector", {"color": "#e11d48"})
+gd.portals.publish(portal["id"])
+```
+
+Typed exceptions (`AuthError`, `PermissionError_`, `NotFoundError`, `ValidationError`,
+`ServerError`, `TransportError`, `JobFailed`), progress callbacks and cancellation on uploads, and a
+swappable transport so a desktop application can route requests through its own network stack.
+
+## Documentation
+
+Full guide: **<https://docs-geodeploy.kndev.org/cli/>**
+
+Source and issues: **<https://github.com/bravemaster3/GeoDeploy>**
+
+Licensed under the Apache License 2.0.

geodeploy-1.3.0/PYPI.md

@@ -0,0 +1,68 @@
+# geodeploy
+
+**Command-line client and Python API for [GeoDeploy](https://github.com/bravemaster3/GeoDeploy)** —
+the self-hosted spatial data platform and geoportal builder.
+
+Upload data, style it, build a portal and publish it, without opening a browser:
+
+```bash
+pip install geodeploy
+
+geodeploy login https://geodeploy.example.org --token gdp_…
+geodeploy upload roads.gpkg sites.csv dem.tif --wait
+geodeploy portals create "Field sites 2026" --publish
+```
+
+**No dependencies. Python 3.9+.** Every request goes through the standard library, so installing
+this pulls in nothing else — and a QGIS plugin can vendor the same client without asking anyone to
+pip-install into QGIS.
+
+If your shell cannot find `geodeploy` after installing, pip's scripts directory is not on your
+`PATH` — `python -m geodeploy` works regardless, and `pipx install geodeploy` or a virtual
+environment avoids it.
+
+## What it covers
+
+- **Uploads** — shapefile, GeoPackage, GeoJSON, CSV (X/Y or WKT), GeoParquet, GeoTIFF. Many files
+  in one command; the route is chosen per file, and anything over 48 MB goes direct to object
+  storage in parallel presigned parts, so a multi-gigabyte upload survives a proxy that caps
+  request bodies.
+- **Layers** — list, inspect, rename, share (STAC / OGC API - Features opt-in), share links per
+  tool, download, delete, restart a stalled ingest.
+- **Symbology** — colour, opacity, outlines, dashes, markers, raster colormaps and stretches, plus
+  data-driven styling: `--color-field pop --classify jenks --classes 6 --ramp magma`, proportional
+  size, and attribute-driven 3D. Classification is computed by the instance, with the same code the
+  portal editor uses, so the CLI and the editor can never disagree about a class.
+- **Portals** — create (web map, story map or catalog), arrange and style layers, folders, About
+  page, assets, access tiers, publish, and a whole-configuration JSON round trip for version
+  control.
+- **Everything else** — external WMS/XYZ/WFS services, registering data already in PostGIS or the
+  bucket, the public STAC and OGC API - Features catalog, ingest jobs, users, and instance
+  administration (health, services, updates, backups, activity log).
+
+Every command takes `--json`, where stdout is exactly one JSON document, and exit codes distinguish
+authentication (3) from network (4) from server (5) so a scheduled job can alert on the right thing.
+
+## As a library
+
+```python
+from geodeploy import Client
+
+gd = Client("https://geodeploy.example.org", token="gdp_…")
+result = gd.uploads.upload("roads.gpkg", wait=True)
+portal = gd.portals.create("Roads")
+gd.portals.add_layer(portal["id"], result.layer_id, "vector", {"color": "#e11d48"})
+gd.portals.publish(portal["id"])
+```
+
+Typed exceptions (`AuthError`, `PermissionError_`, `NotFoundError`, `ValidationError`,
+`ServerError`, `TransportError`, `JobFailed`), progress callbacks and cancellation on uploads, and a
+swappable transport so a desktop application can route requests through its own network stack.
+
+## Documentation
+
+Full guide: **<https://docs-geodeploy.kndev.org/cli/>**
+
+Source and issues: **<https://github.com/bravemaster3/GeoDeploy>**
+
+Licensed under the Apache License 2.0.

geodeploy-1.3.0/README.md

@@ -0,0 +1,196 @@
+# cli/
+
+## Purpose
+The packaged **`geodeploy`** command-line client **and** the Python API client it is built on — the
+headless half of the product (roadmap v1.3). Two audiences, one package: a person or CI job at a
+shell, and the **QGIS plugin** (`E-05`), which imports `geodeploy.client` directly rather than
+re-implementing HTTP against the same endpoints.
+
+User documentation is `docs/cli.md`; this file is the technical note.
+
+## Contents
+
+**The library** (`geodeploy/`) — never prints, never exits, raises typed errors:
+- `client.py` — `Client`: URL/auth resolution, request plumbing, error mapping, and the namespaces
+  (`gd.vector`, `gd.raster`, `gd.layers`, `gd.portals`, `gd.sources`, `gd.imports`, `gd.jobs`,
+  `gd.uploads`, `gd.admin`, `gd.users`, `gd.catalog`). `absolute()` resolves the **relative
+  `/s3/…` presigned URLs** a managed MinIO returns.
+- `transport.py` — stdlib HTTP. `UrllibTransport` (retries only connection failures and 502/503/504,
+  and **never** a streamed body — the file object is already partly consumed), `MultipartBody`
+  (form-data streamed from disk with a real Content-Length), `ProgressReader`. Anything with
+  `send(Request) -> Response` can replace it; that seam is for QGIS's `QgsNetworkAccessManager`.
+- `config.py` — profiles + credentials. **Tokens never enter `config.json`**: OS keyring when there
+  is one, else `credentials.json` at 0600 in a 0700 directory, written atomically. `normalize_url`
+  collapses `…/api`, trailing slashes and a bare host to one origin, so a credential saved under one
+  spelling is found under another. `split_portal_url` does the same job for a published portal's
+  URL → `(origin, slug)`, so a link copied out of the address bar is a valid portal reference
+  anywhere a slug is (`browse --portal`, and `Portals.get`, which every portal command goes
+  through). `resolve()` = flag → env → profile, for URL and token separately.
+- `uploads.py` — the routing table (below) plus both transports: multipart-through-the-API, and
+  presign/chunked direct-to-storage with per-part retry and abort-on-failure.
+- `layers.py` — the two layer kinds, and `Layers.resolve` (id | uid | `vector-3` | name; ambiguity
+  raises rather than guessing — including a **bare integer that exists in both kinds**, since
+  vector and raster ids are separate sequences and "1" is routinely two different layers).
+  `download_dataset()` pulls a prepared GeoParquet layer's manifest + every partition straight from
+  storage: complete, lossless and **not subject to the export row cap**, which is why
+  `layers download` prefers it over queueing an export for those layers.
+- `portals.py` — portal CRUD and `layer_configs` surgery. `layer_configs[0]` = top of the list =
+  drawn on top. `editable_config()` drops server-owned fields before a round-trip PUT.
+- `styles.py` — the style vocabulary of `api/geodeploy/services/symbology.py`, in both directions.
+  `build_style()` **assembles** it from plain arguments; `parse()`/`Style` **reads** one back
+  (mode, field, classes, categories, size, extrusion, rescale) so a consumer — the QGIS plugin —
+  does not re-decide what `color_mode: "graduated"` implies. `Style` is a reader, not a schema: it
+  never rejects and keeps `.raw`, and `to_dict()` makes build → parse → build lossless.
+  **Classification maths is NOT reimplemented**: `classify()` reads
+  `GET /data/vector/{ref}/field-stats`, so the CLI cannot disagree with the editor about which class
+  a feature is in. Same rule for legends — `vector.legend()` asks the instance, and
+  `Style.legend()` is the local twin for a style that has no URL yet (an unsaved edit), pinned
+  against the server's exact labels in `test_styles_jobs`.
+- `catalog.py` — the public surfaces, including `public()` (the instance index behind
+  `geodeploy browse`) and `portal_style()`, which reads a published portal's own `style.json`.
+- `jobs.py`, `sources.py`, `imports.py`, `admin.py`, `errors.py`.
+
+`Layers.resolve_public()` is the anonymous twin of `resolve()`: with no credential a layer is looked
+up in the public index, so `geodeploy --url … layers download roads` works by NAME for someone with
+no account. `_LayerBase.export_to_file()` drives the queue-poll-download of a built export.
+
+**The CLI** (`geodeploy/cli/`) — the only part allowed to print:
+- `main.py` — argparse root, `Context` (formatter + lazy client), and the single place exceptions
+  become exit codes.
+- `output.py` — `Formatter` (stdout = the answer, stderr = commentary, `--json` = one document),
+  tables, progress bar, `EXIT_*` constants.
+- `commands/` — one module per group (`auth`, `upload`, `layers`, `portals`, `sources`, `imports`,
+  `jobs`, `catalog`, `admin`, `browse`), each with `register(subparsers)`. `_common.py` holds the
+  styling flags, shared by the three commands that take them, and `resolve_layer(..., public_ok=)`
+  which decides between the authenticated list and the public index.
+
+`tests/` — 317 tests against a real HTTP server (`conftest.FakeInstance`) that records what arrived
+on the wire. `pyproject.toml` — packaging; console script `geodeploy`.
+
+## Dependencies / relationships
+- **Zero runtime dependencies, Python 3.9+.** Both constraints exist for the QGIS plugin, which
+  vendors this package and cannot pip-install anything on a user's machine. The floor is set by the
+  **oldest QGIS anyone still runs**, not the current one — institutions pin a release for years —
+  so it reaches back through several LTR lines rather than tracking today's. Current QGIS ships a
+  much newer Python; that is not the constraint. Do not add a dependency here without moving it
+  into an extra.
+- Consumes `api/geodeploy/routers/` — see that folder's README for the permission model. Nothing in
+  the API imports this.
+- **GeoLibre does not use this package**: its plugin is browser TypeScript
+  (`integrations/geolibre-plugin/`) hitting `/api/interop/geolibre/*`. What the two share is the
+  HTTP contract and the style vocabulary, not code.
+- Parity to keep: the upload routing mirrors `ui/src/composables/useUpload.js`, and the style keys
+  mirror `services/symbology.py` + `ui/src/lib/symbology.js`.
+
+## The upload routing table (and why 48 MB)
+`.gpkg/.geojson/.json/.zip` < 48 MB → `POST /data/vector/upload`; `.csv` < 48 MB → `/upload-csv`
+(PostGIS); either at/over 48 MB → presigned direct-to-storage → `/large/complete` (converted to
+GeoParquet); `.parquet` at any size → `/geoparquet/{presign,complete}`; `.tif` small/large →
+`/data/raster/upload` or chunked → `/data/raster/large/complete`. Over 48 MB the upload is chunked
+into 48 MB presigned parts, four in parallel.
+
+**48 MB is not the API's 2 GB cap.** The binding limit is the request-body cap of whatever proxy
+sits in front of the instance (Cloudflare's free tier: 100 MB), and exceeding it produces *no server
+log at all* — the request never arrives. `LARGE_UPLOAD_THRESHOLD` must stay equal to the UI's.
+
+## Packaging and release
+
+`pyproject.toml` follows PEP 639: `license = "Apache-2.0"` as an SPDX expression plus
+`license-files`, and **no `License ::` classifier** — setuptools ≥ 77 refuses a build that declares
+both. The version is single-sourced from `geodeploy/__init__.py` (`dynamic = ["version"]`), so
+`--version`, the user agent and the package metadata cannot disagree.
+
+**`PYPI.md`, not `README.md`, is the project page.** This file is the folder's technical note (the
+repo convention in CLAUDE.md), which is not what someone landing on PyPI wants to read; `PYPI.md` is
+the user-facing front page. Keep both current.
+
+The name `geodeploy` was unregistered on PyPI as of 2026-08-13 (re-check immediately before the
+first upload — anyone can claim it).
+
+**Releases go through `.github/workflows/publish-cli.yml`, not from a laptop.** It uses PyPI's
+Trusted Publishing: no API token exists to leak or rotate, and the workflow gates the upload on the
+test suite, on `twine check`, on a clean `--no-deps` install, and on the **tag matching the packaged
+version**. Cutting a release is therefore:
+
+```bash
+# 1. bump the one line in geodeploy/__init__.py, commit, merge
+# 2. tag it — the prefix is `cli-v`, not the platform's `v1.3`
+git tag cli-v1.3.0b1 && git push origin cli-v1.3.0b1
+```
+
+Use the workflow's manual run (`Actions → Publish CLI → Run workflow → testpypi`) to rehearse
+against TestPyPI first. Building by hand is still the way to CHECK a change without releasing it:
+
+```bash
+cd cli
+python -m build                     # sdist + wheel into dist/
+python -m twine check dist/*        # must pass before anything is uploaded
+```
+
+`dist/` and `build/` are git-ignored. The sdist carries the tests, so the release can be verified
+from source rather than trusted.
+
+**Versioning.** The CLI's number tracks the GeoDeploy release it ships with, so it must not claim a
+release that has not happened. `1.3.0b1` went up first for exactly that reason — a version on PyPI
+can never be re-uploaded, and deleting it does not free the number, so a pre-release is the only way
+to test the real index without spending the one that matters. `1.3.0` followed when v1.3 tagged.
+Do the same next time: `1.4.0bN` while v1.4 is unreleased, then the final.
+
+## The row cap, and the two ways around it
+
+A **built** export (`gpkg`/`csv`/`geojson`, or anything clipped) stops at `FULL_EXPORT_CAP`
+(1,000,000 features, env-tunable) for a whole layer and `FEATURE_CAP` (50,000) for a bbox clip,
+because the worker assembles the archive in memory. The failure mode this creates is not the cap —
+it is that a truncated export has the same names and formats as a complete one. So:
+
+- the task records the row count of every file it writes, marks the ones that reached the cap in
+  `MANIFEST.txt` (with the uncapped alternatives spelled out), and writes `{job_id}.json` beside
+  the zip;
+- `GET …/export-status/{job_id}` reports `truncated: [{file, rows, cap}]` from that file;
+- `layers download` prints `INCOMPLETE`, names the alternative, and **exits non-zero**.
+
+The uncapped paths, which the CLI prefers automatically where it can: a prepared **GeoParquet**
+layer's own partition files (`download_dataset`, no worker involved), and **OGC API - Features**
+paging for PostGIS (`ogr2ogr -f GPKG out.gpkg "OAPIF:<instance>/api/ogc" <layer>` — not wrapped by
+the CLI yet; see below).
+
+## Current status & known issues
+- `geodeploy browse` and `layers download` depend on API endpoints added in the same branch
+  (`/api/public`, `/data/{kind}/{ref}/export`). An older instance answers 404 for both; the browse
+  command says so, but `layers download` for a built format will simply fail against one.
+- Built 2026-08-12 on branch `feat/cli`; **not yet exercised against a live instance** — every test
+  runs against the in-repo fake. First real run should be `upload --dry-run`, then a small upload,
+  then a portal round trip.
+- Not published to PyPI yet. `pip install -e cli/` is the current install.
+- `geodeploy admin update --watch` polls through the API restart the update itself causes; a failed
+  poll is treated as progress, which is right but means a genuinely dead instance looks like a slow
+  update until the poll loop is interrupted.
+- No declarative `apply` (a manifest describing layers + portal, applied idempotently). The
+  `portals export/import` round trip is the seam it would build on. Deliberately deferred.
+- No shell completion.
+- The QGIS plugin does not exist yet; the seams it needs (pluggable transport, progress callbacks,
+  `cancel`, typed errors, no printing, and `styles.Style` for reading a style back) are in place and
+  tested.
+  **Which URL it should hand QGIS is two questions, not one.** For DISPLAY of a heavy layer,
+  **PMTiles** is the fastest thing we serve — pre-tiled, range-requested, no per-pan query — and it
+  is what `layers links` should offer first for a big GeoParquet layer. But PMTiles is a *rendering*
+  format: generalised geometry, tile-clipped features, attributes trimmed to what the tiles carry.
+  For DATA — full attributes, exact geometry, analysis, editing — the answer is OGC API - Features,
+  the GeoParquet partitions, or a built export. A plugin that offers only one of the two will be
+  wrong half the time, so the layer-add dialog needs both, labelled for what they are.
+  Caveat: reading PMTiles needs a GDAL with the support (3.8+), which rules out the oldest QGIS the
+  Python floor above deliberately still supports — so the display path must degrade to OAPIF rather
+  than assume it.
+  **Measured on the maintainer's two installs (2026-08-13)**, which is why this is a rule and not a
+  worry: one reports Python **3.9.5** / GDAL **3.7.2** (no PMTiles — and the exact Python the floor
+  above exists for), the other Python **3.12.12** / GDAL **3.12.1** (PMTiles fine). Both are in
+  daily use. So `metadata.txt` should say `qgisMinimumVersion=3.28` (the oldest QGIS whose Python
+  is ≥ 3.9) and the plugin should branch on `gdal.VersionInfo()` at RUNTIME rather than refusing to
+  install — blocking the old one would lock out precisely the pinned installs this package's
+  constraints were chosen to serve.
+  Develop and demo on the NEWEST QGIS; that is a different decision from what the plugin refuses to
+  run on, and only the second one is visible to a user with an old install.
+
+## Last updated
+2026-08-12 (created — packaged CLI + Python client, replacing `examples/geodeploy_cli.py`; then
+`browse` + anonymous layer download on top of the new `/api/public` and per-layer export endpoints)

geodeploy-1.3.0/geodeploy/__init__.py

@@ -0,0 +1,52 @@
+"""GeoDeploy — command-line client and Python API.
+
+    from geodeploy import Client
+    gd = Client("https://geodeploy.example.org", token="gdp_…")
+    layer = gd.uploads.upload("roads.gpkg", wait=True)
+    portal = gd.portals.create("Roads")
+    gd.portals.add_layer(portal["id"], layer.layer_id, "vector", {"color": "#e11d48"})
+    gd.portals.publish(portal["id"])
+
+Zero runtime dependencies, Python 3.9+, so the QGIS plugin can vendor this package as-is.
+"""
+from __future__ import annotations
+
+# The CLI's version tracks the GeoDeploy release it ships with. A PyPI version can never be
+# re-uploaded, so a number is only spent once the release it names exists: 1.3.0b1 proved the
+# packaging against the real index, and this is the release it was rehearsing for.
+__version__ = "1.3.0"
+
+from .client import Client  # noqa: E402  (after __version__ — the user agent reads it)
+from .errors import (  # noqa: E402
+    APIError,
+    AuthError,
+    ConfigError,
+    ConflictError,
+    GeoDeployError,
+    NotFoundError,
+    PermissionError_,
+    ServerError,
+    TransportError,
+    ValidationError,
+)
+from .jobs import JobFailed, JobTimeout  # noqa: E402
+from .styles import Style, parse_style  # noqa: E402
+
+__all__ = [
+    "Client",
+    "Style",
+    "parse_style",
+    "GeoDeployError",
+    "APIError",
+    "AuthError",
+    "ConfigError",
+    "ConflictError",
+    "NotFoundError",
+    "PermissionError_",
+    "ServerError",
+    "TransportError",
+    "ValidationError",
+    "JobFailed",
+    "JobTimeout",
+    "__version__",
+]

geodeploy-1.3.0/geodeploy/__main__.py

@@ -0,0 +1,13 @@
+"""`python -m geodeploy` — the same entry point as the `geodeploy` console script.
+
+Worth having: inside QGIS's bundled Python, or a virtualenv whose `Scripts/` is not on PATH, the
+module form is the one that works.
+"""
+from __future__ import annotations
+
+import sys
+
+from .cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())