Repository navigation
CLI - Implement MVP #11
Description
Activity
Note from @james-hinton during Technical Progress Review: The Canadian steering group member also gathered use cases for this client library – joint review with @pantierra to be organised by @james-hinton.
I checked the Canadian input and the demo notebooks and wrote up the following proposal:
EOEPCA+ Python Client Library and CLI proposal
Single, installable Python package,
eoepca-client(PyPI name), that exposes the EOEPCA+ platform as:- A Python library (
import eoepca_client) usable from notebooks, pipelines, and downstream apps. - A CLI (
eoepca …) built directly on top of the library with Typer, for scripting and interactive terminal use.
Both interfaces integrate with EOEPCA+'s public APIs:
- Hide token management (Keycloak OIDC: device, password, refresh, client-credentials).
- Provide a consistent, object-oriented surface over the heterogeneous EOEPCA+ building-block APIs (REST, OGC API, STAC, S3, BPMN).
- Behave the same way whether called from Python or the shell (same models, same error handling, same config).
Reuse community libraries where they already exist (no rewrite of STAC/OWS/openEO clients), where a mature library exists the client configures and returns it rather than wrapping it. Where no client exists (Workspace API, Registration API, Harvester engine), we may ship a small first-class wrapper.
Note: this is not a replacement for
kubectl, ArgoCD, or Helm. It does not talk to Kubernetes. It talks to the public APIs that EOEPCA+ building blocks expose to authenticated end users.Out-of-scope
Being explicit avoids scope creep and clarifies the boundary with other tools:
- No admin. Administration tasks on EOEPCA. Deferred to a separate package.
- No Kubernetes / ArgoCD / Helm. Installing, upgrading, or configuring building blocks stays with
helm,argocd, and the EOEPCAdeployment-guide. The client assumes BBs are already running. - No workflow authoring UI or CWL editor. It deploys and runs CWL / BPMN, but does not generate them. Same stance as the UI proposal (
csa_requirements_ui.md§2.7 Development Environment Access). - No heavy data analytics. Downloads, simple subsetting, and conversion are in scope; xarray/dask pipelines are user code. The library can be used inside such pipelines.
- Limited offline behaviour. Capability discovery and most commands require the platform to be reachable. We will not maintain a stale local cache of catalogue contents.
- Notifications / pub-sub, MLflow. deferred to later milestones; surfaces designed but not implemented in v1.
Proposed design choices:
- Layered.
auth,platform discovery, and the shared HTTPX client are foundational and used by every other module. The each BB module is independent. - CLI = thin shell over the library. With subcommands that call library methods and render the result.
- Typer for the CLI. Type hints become argument parsing for free, which keeps subcommand modules small and consistent with the library's typed signatures.
- HTTPX behind a synchronous façade. So if needed async surface can be added later without an entire rewrite.
Scope of MVP
- Hardcoded platform information (local config file)
- Ship
pip install eoepca-clientsuch that a new user can, in under a minute, run:
eoepca login eoepca stac search --collection <id> --bbox -10,40,5,55 --limit 5 eoepca stac item add <collection> ./item.geojson eoepca stac item rm <collection> <item-id>
- A Python library (
And while doing a discovery I think, if there haven't been plans, already, it would be worth considering to add some platform discovery capabilities to EOEPCA. Like
.well-known/eoepca.json. To avoid hard-coding of URLs of the endpoints of services deployed. The file ideally should be dynamically generated at deploy time from the active Helm/ArgoCD values (so it always reflects what is actually installed) and is overwritable by the operator for edge cases (custom hostnames, externally hosted BBs, disabled services).eoepca platform info <domain>fetches and prints this.I probably would go with something defined already, maybe https://datatracker.ietf.org/doc/rfc9727/
Came up with a first draft proposal for an
api-catalogdiscovery: #16This is relying on RFC9727 (
api-catalog), RFC9264 (linkset) and JSON format, proposing some flexiblerelstructure to fit EOEPCA. You may want to directly check on the example file.You can find
eoepcacli/client here: https://github.com/EOEPCA/user-client/tree/main/eoepca-clientMVP delivered — acceptance criteria for this issue are met.
Priority features (MVP)
- Auth with transparent token handling (
login/logout/whoami) - STAC discovery and search
- STAC item create/delete (transactions)
- Platform config via local config + API catalog discovery
Implementation
Shipped in
eoepca-client/(merged via #20):eoepca login eoepca stac search --collection <id> --bbox -10,40,5,55 --limit 5 eoepca stac item add <collection> ./item.geojson eoepca stac item rm <collection> <item-id>
Also available as a Python library (
from eoepca_client import Client). Platform discovery via RFC 9727 api-catalog landed in #16.Docs & demo
- Package README with quickstart and library usage:
eoepca-client/README.md - Building-block docs (design, api-catalog, getting started) under
docs/
Follow-ups (broader BB coverage beyond STAC, packaging to PyPI, notebooks) will be tracked in seperate issues.
- Auth with transparent token handling (
In our CCN1 proposal, we described the need for a CLI / Python client library:
In the last quarter, we refined the use cases further, informed by the user needs on DLR's terrabyte platform:
Acceptance criteria