cuiman 0.2.1.dev1__tar.gz → 0.3.0__tar.gz

{cuiman-0.2.1.dev1 → cuiman-0.3.0}/.gitignore

@@ -1,9 +1,10 @@
 # Testing
 *.zarr/
 .cov-report
+notebooks/auth-test.ipynb
 
-# Documentation generation
-docs/notebooks/*.ipynb
+# Legacy generated documentation (excluded from the site)
+docs/notebooks/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -202,3 +203,6 @@ cython_debug/
 #  refer to https://docs.cursor.com/context/ignore-files
 .cursorignore
 .cursorindexingignore
+
+# Downloaded font assets
+docs/assets/fonts/*.ttf

{cuiman-0.2.1.dev1 → cuiman-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cuiman
-Version: 0.2.1.dev1
+Version: 0.3.0
 Summary: Provides a client Python API, GUI, and CLI for servers compliant with OGC API - Processes
 Project-URL: Documentation, https://eo-tools.github.io/eozilla
 Project-URL: Repository, https://github.com/eo-tools/eozilla
@@ -27,11 +27,14 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: gavicore>=0.2.1.dev1
-Requires-Dist: httpx
+Requires-Dist: authlib<1.9,>=1.8
+Requires-Dist: gavicore>=0.3.0
+Requires-Dist: httpx2
 Requires-Dist: ipython
-Requires-Dist: pydantic
-Requires-Dist: pydantic-settings
+Requires-Dist: joserfc<2,>=1.6
+Requires-Dist: keyring
+Requires-Dist: pydantic-settings>=2.14.2
+Requires-Dist: pydantic>=2.12
 Requires-Dist: pyyaml
 Requires-Dist: remotestate<1,>=0.3.4
 Requires-Dist: typer<1,>=0.26.0

cuiman-0.3.0/cuiman/__init__.py

@@ -0,0 +1,42 @@
+#  Copyright (c) 2025-2026 by the Eozilla team and contributors
+#  Permissions are hereby granted under the terms of the Apache 2.0 License:
+#  https://opensource.org/license/apache-2-0.
+
+from importlib.metadata import version
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .api.async_client import AsyncClient as AsyncClient
+    from .api.client import Client as Client
+    from .api.config import ClientConfig as ClientConfig
+    from .api.exceptions import ClientError as ClientError
+    from .api.jobs import JobMonitor as JobMonitor
+    from .api.jobs import JobOptions as JobOptions
+
+__version__ = version("cuiman")
+
+__all__ = [
+    "AsyncClient",
+    "Client",
+    "ClientConfig",
+    "ClientError",
+    "JobMonitor",
+    "JobOptions",
+    "__version__",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Load public API exports only when requested, keeping CLI startup light."""
+    if name not in __all__:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    value = getattr(import_module(".api", __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Include lazy public API exports in interactive discovery."""
+    return sorted(set(globals()) | set(__all__))

{cuiman-0.2.1.dev1 → cuiman-0.3.0}/cuiman/api/async_client.py

@@ -1,6 +1,6 @@
 # generated by gen_client.py:
 #   filename:  async_client.py:
-#   timestamp: 2026-07-15T17:16:03.217600
+#   timestamp: 2026-09-14T06:56:16.079586
 
 
 from typing import Any, Optional
@@ -22,7 +22,6 @@ from .client_app_mixin import ClientAppMixin
 from .config import ClientConfig
 from .ishell import has_ishell as _  # noqa F401
 from .transport import AsyncTransport, TransportArgs
-from .transport.httpx import HttpxTransport
 
 
 class AsyncClient(ClientAppMixin, AsyncClientMixin):
@@ -30,10 +29,18 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
     The client API for the web service (asynchronous mode).
 
     Args:
-      config: Optional client configuration object. If given,
-        other configuration arguments are ignored.
+      config: Optional configuration object. Explicit keyword settings override
+        its values.
+      config_type: Optional application configuration class. It owns the
+        settings schema, defaults, environment namespace, and profile path.
+        When omitted, a supplied ``config`` object's concrete type is used.
       config_path: Optional path of the configuration file to be loaded
-      config_kwargs: Configuration settings as keyword arguments.
+      config_kwargs (Any): Configuration overrides, including ``auth``. An auth model
+        or a dictionary containing ``auth_type`` replaces previous auth settings,
+        even when the type is unchanged. A dictionary without ``auth_type``
+        merges into the selected auth configuration, including nested mappings.
+        If credentials are still missing, a matching profile's keyring entry may
+        supply them; explicitly supplied credentials take precedence.
       api_url: The service URL of the OGC API - Processes.
     """
 
@@ -41,6 +48,7 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
         self,
         *,
         config: Optional[ClientConfig] = None,
+        config_type: type[ClientConfig] | None = None,
         config_path: Optional[str] = None,
         api_url: Optional[str] = None,
         _debug: bool = False,
@@ -49,23 +57,16 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
     ):
         self._config = ClientConfig.create(
             config=config,
+            config_type=config_type,
             config_path=config_path,
             api_url=api_url,
             **config_kwargs,
         )
         if not self._config.api_url:
             raise ValueError("Required setting 'api_url' not configured")
-        self._transport = (
-            HttpxTransport(
-                api_url=f"{self._config.api_url.rstrip('/')}/",
-                headers=self._config.auth_headers,
-                return_type_map=self._config.return_type_map,
-                async_token_refresher=self._config._make_async_token_refresher(),
-                debug=_debug,
-            )
-            if _transport is None
-            else _transport
-        )
+        self._transport = _transport
+        self._debug = _debug
+        self._init_client_runtime()
 
     @property
     def config(self) -> ClientConfig:
@@ -100,7 +101,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
 
             - `500`: A server error occurred.
         """
-        return await self._transport.async_call(
+        transport = self._get_transport()
+        return await transport.async_call(
             TransportArgs(
                 path="/",
                 method="get",
@@ -127,8 +129,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
         |Dismiss|http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/dismiss|
 
         For more information, see [OGC API — Processes — Part 1
-        Section 7.4](https://docs.ogc.org/is/18-062r2/18-
-        062r2.html#sc_conformance_classes).
+        Section
+        7.4](https://docs.ogc.org/is/18-062r2/18-062r2.html#sc_conformance_classes).
 
 
         Returns:
@@ -144,7 +146,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
 
             - `500`: A server error occurred.
         """
-        return await self._transport.async_call(
+        transport = self._get_transport()
+        return await transport.async_call(
             TransportArgs(
                 path="/conformance",
                 method="get",
@@ -172,7 +175,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
           ClientError: If the call to the web service fails
             with a status code != `2xx`.
         """
-        return await self._transport.async_call(
+        transport = self._get_transport()
+        return await transport.async_call(
             TransportArgs(
                 path="/processes",
                 method="get",
@@ -193,8 +197,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
         description.
 
         For more information, see [OGC API — Processes — Part 1
-        Section 7.10](https://docs.ogc.org/is/18-062r2/18-
-        062r2.html#sc_process_description).
+        Section
+        7.10](https://docs.ogc.org/is/18-062r2/18-062r2.html#sc_process_description).
 
         Args:
           process_id:
@@ -210,7 +214,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
 
             - `404`: The requested URI was not found.
         """
-        return await self._transport.async_call(
+        transport = self._get_transport()
+        return await transport.async_call(
             TransportArgs(
                 path="/processes/{processID}",
                 method="get",
@@ -247,7 +252,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
             - `404`: The requested URI was not found.
             - `500`: A server error occurred.
         """
-        return await self._transport.async_call(
+        transport = self._get_transport()
+        return await transport.async_call(
             TransportArgs(
                 path="/processes/{processID}/execution",
                 method="post",
@@ -276,7 +282,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
 
             - `404`: The requested URI was not found.
         """
-        return await self._transport.async_call(
+        transport = self._get_transport()
+        return await transport.async_call(
             TransportArgs(
                 path="/jobs",
                 method="get",
@@ -291,8 +298,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
         Show the status of a job.
 
         For more information, see [OGC API — Processes — Part 1
-        Section 7.12](https://docs.ogc.org/is/18-062r2/18-
-        062r2.html#sc_retrieve_status_info).
+        Section
+        7.12](https://docs.ogc.org/is/18-062r2/18-062r2.html#sc_retrieve_status_info).
 
         Args:
           job_id: Local identifier of a job
@@ -309,7 +316,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
             - `404`: The requested URI was not found.
             - `500`: A server error occurred.
         """
-        return await self._transport.async_call(
+        transport = self._get_transport()
+        return await transport.async_call(
             TransportArgs(
                 path="/jobs/{jobId}",
                 method="get",
@@ -342,7 +350,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
             - `404`: The requested URI was not found.
             - `500`: A server error occurred.
         """
-        return await self._transport.async_call(
+        transport = self._get_transport()
+        return await transport.async_call(
             TransportArgs(
                 path="/jobs/{jobId}",
                 method="delete",
@@ -359,8 +368,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
         instead.
 
         For more information, see [OGC API — Processes — Part 1
-        Section 7.13](https://docs.ogc.org/is/18-062r2/18-
-        062r2.html#sc_retrieve_job_results).
+        Section
+        7.13](https://docs.ogc.org/is/18-062r2/18-062r2.html#sc_retrieve_job_results).
 
         Args:
           job_id: Local identifier of a job
@@ -377,7 +386,8 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
             - `404`: The requested URI was not found.
             - `500`: A server error occurred.
         """
-        return await self._transport.async_call(
+        transport = self._get_transport()
+        return await transport.async_call(
             TransportArgs(
                 path="/jobs/{jobId}/results",
                 method="get",
@@ -387,8 +397,3 @@ class AsyncClient(ClientAppMixin, AsyncClientMixin):
                 extra_kwargs=kwargs,
             )
         )
-
-    async def close(self):
-        """Close this client."""
-        if self._transport is not None:
-            await self._transport.async_close()

cuiman-0.3.0/cuiman/api/async_client_mixin.py

@@ -0,0 +1,319 @@
+#  Copyright (c) 2026 by the Eozilla team and contributors
+#  Permissions are hereby granted under the terms of the Apache 2.0 License:
+#  https://opensource.org/license/apache-2-0.
+
+import asyncio
+import threading
+import warnings
+from abc import abstractmethod
+from typing import Any
+
+import httpx2
+from authlib.integrations.httpx_client import AsyncOAuth2Client
+
+from gavicore.models import JobInfo, JobResults, JobStatus, ProcessDescription
+from gavicore.util.request import ExecutionRequest
+
+from .auth.config import OidcAuthConfig
+from .auth.interactive import authorize
+from .auth.oidc import LoopbackCallbackServer
+from .client_mixin_base import ClientMixinBase
+from .defaults import (
+    DEFAULT_OPEN_JOB_JOB_POLL_INTERVAL,
+    DEFAULT_OPEN_JOB_RESULT_TIMEOUT,
+)
+from .exceptions import ClientError, ClientWarning
+from .opener import JobResultOpenContext, JobResultStatusError
+from .opener.opener import open_job_result
+from .transport import AsyncTransport
+
+# -----------------------------------------------------
+# IMPORTANT: Sync changes here with ClientMixin!
+# -----------------------------------------------------
+
+
+# noinspection PyShadowingBuiltins
+class AsyncClientMixin(ClientMixinBase[httpx2.AsyncClient]):
+    """
+    Extra methods for the API client (asynchronous mode).
+    """
+
+    _async_mode = True
+    _transport: AsyncTransport | None
+
+    def _init_client_runtime(self) -> None:
+        super()._init_client_runtime()
+        self._runtime_lock = asyncio.Lock()
+        self._owner_loop: asyncio.AbstractEventLoop | None = None
+
+    def _bind_loop(self) -> asyncio.AbstractEventLoop:
+        loop = asyncio.get_running_loop()
+        if self._owner_loop is not None and self._owner_loop is not loop:
+            raise RuntimeError("AsyncClient must be used on its owning event loop.")
+        self._owner_loop = loop
+        return loop
+
+    async def close(self) -> None:
+        """Close owned connections. A closed client cannot be used again."""
+        self._bind_loop()
+        async with self._runtime_lock:
+            await self._close()
+
+    async def _close(self) -> None:
+        """Close connections while the caller holds the owner lock."""
+        self._closed = True
+        transport, self._transport = self._transport, None
+        try:
+            if transport is not None:
+                await transport.async_close()
+        finally:
+            if self._http_client is not None:
+                await self._http_client.aclose()
+            self._http_client = None
+
+    async def login(
+        self,
+        *,
+        interactive: bool = True,
+        no_browser: bool = False,
+        force: bool = False,
+        save: bool = False,
+    ) -> None:
+        """Prepare authentication using the client's persistent HTTP session.
+
+        Use force to acquire a fresh token. Requests never prompt or open a
+        browser. With save=True, failure to save credentials raises an error.
+        """
+        self._bind_loop()
+        async with self._runtime_lock:
+            await self._login(
+                interactive=interactive, no_browser=no_browser, force=force, save=save
+            )
+
+    async def _login(
+        self,
+        *,
+        interactive: bool = False,
+        no_browser: bool = False,
+        force: bool = False,
+        save: bool = False,
+    ) -> None:
+        self._require_open()
+        auth = (
+            await asyncio.to_thread(self._credentials, interactive=True, force=force)
+            if interactive
+            else self._credentials(interactive=False, force=force)
+        )
+        self._configure_http_client(auth, self._updated_token)
+        await self._discover()
+        client = self._http_client
+        response = None
+        if isinstance(client, AsyncOAuth2Client) and client.token and not force:
+            await client.ensure_active_token(client.token)
+        elif isinstance(auth, OidcAuthConfig):
+            assert isinstance(client, AsyncOAuth2Client)
+            with LoopbackCallbackServer() as server:
+                url, state, verifier = self._authorization(client, server)
+                cancelled = threading.Event()
+                try:
+                    code = await asyncio.to_thread(
+                        authorize,
+                        server,
+                        url,
+                        state,
+                        no_browser=no_browser,
+                        cancelled=cancelled,
+                    )
+                except asyncio.CancelledError:
+                    cancelled.set()
+                    raise
+                response = await client.fetch_token(code=code, code_verifier=verifier)
+                await self._validate_oidc_token(required=True)
+        elif request := self._login_request(force=force):
+            response = await request()
+        self._accept_login(response, force=force, save=save)
+
+    async def _discover(self) -> None:
+        if url := self._discovery_url:
+            assert self._http_client is not None
+            self._accept_discovery(
+                await self._http_client.request("GET", url, auth=None)
+            )
+
+    async def _validate_oidc_token(self, *, required: bool = False) -> None:
+        with self._oidc_validation(required=required) as url:
+            if url:
+                assert self._http_client is not None
+                response = await self._http_client.request("GET", url, auth=None)
+                self._validate_id_token(response, required=required)
+
+    async def _updated_token(self, _token: dict[str, Any], **_previous: Any) -> None:
+        await self._validate_oidc_token()
+        self._save_credentials()
+
+    async def logout(self) -> None:
+        """Revoke an OIDC token when supported, remove local secrets, and close."""
+        self._bind_loop()
+        async with self._runtime_lock:
+            self._require_open()
+            try:
+                if self._can_revoke:
+                    self._configure_http_client(self.config.auth, self._updated_token)
+                    await self._discover()
+                    if options := self._revocation():
+                        assert isinstance(self._http_client, AsyncOAuth2Client)
+                        response = await self._http_client.revoke_token(**options)
+                        response.raise_for_status()
+            finally:
+                self._closed = True
+                try:
+                    self._forget_credentials()
+                finally:
+                    await self._close()
+
+    async def _request(self, method: str, url: str, **kwargs: Any) -> httpx2.Response:
+        self._bind_loop()
+        async with self._runtime_lock:
+            await self._login()
+            assert self._http_client is not None
+            return await self._http_client.request(
+                method, url, **self._request_options(kwargs)
+            )
+
+    def _app_callbacks(self) -> dict[str, Any]:
+        self._require_open()
+        loop = self._bind_loop()
+
+        def require_running_owner() -> None:
+            self._require_open()
+            if not loop.is_running():
+                raise RuntimeError("The AsyncClient owning event loop is not running.")
+
+        async def prepare() -> None:
+            require_running_owner()
+            await asyncio.wrap_future(
+                asyncio.run_coroutine_threadsafe(self.login(interactive=False), loop)
+            )
+
+        async def request(method: str, url: str, **kwargs: Any) -> httpx2.Response:
+            require_running_owner()
+            return await asyncio.wrap_future(
+                asyncio.run_coroutine_threadsafe(
+                    self._request(method, url, **kwargs), loop
+                )
+            )
+
+        return dict(prepare=prepare, request=request)
+
+    @abstractmethod
+    async def get_process(self, process_id: str, **kwargs: Any) -> ProcessDescription:
+        """Will be overridden by the actual client class."""
+
+    @abstractmethod
+    async def get_job(self, job_id: str, **kwargs: Any) -> JobInfo:
+        """Will be overridden by the actual client class."""
+
+    @abstractmethod
+    async def get_job_results(self, job_id: str, **kwargs: Any) -> JobResults:
+        """Will be overridden by the actual client class."""
+
+    async def create_execution_request(
+        self,
+        process_id: str,
+        dotpath: bool = False,
+    ) -> ExecutionRequest:
+        """
+        Create a template for an execution request
+        generated from the process description of the
+        given process identifier.
+
+        Args:
+            process_id: The process identifier
+            dotpath: Whether to create dot-separated input
+                names for nested object values
+
+        Returns:
+            The execution request template.
+
+        Raises:
+            ClientError: if an error occurs
+        """
+        process_description = await self.get_process(process_id)
+        return ExecutionRequest.from_process_description(
+            process_description, dotpath=dotpath
+        )
+
+    async def open_job_result(
+        self,
+        job_id: str,
+        output_name: str | None = None,
+        data_type: type | None = None,
+        media_type: str | None = None,
+        poll_interval: float = DEFAULT_OPEN_JOB_JOB_POLL_INTERVAL,
+        timeout: float = DEFAULT_OPEN_JOB_RESULT_TIMEOUT,
+        **options: Any,
+    ) -> Any:
+        """Open the results of the job given by its ID.
+
+        Args:
+            job_id: the job ID
+            output_name: the name of the output to be opened.
+            data_type: the expected/desired data type to be returned.
+                If provided, the return value will be of that type.
+                If not provided, the return value will be the type
+                decided by the opener.
+            media_type: the media type of the output produced.
+                Only needed, if the output does not provide its
+                media type or if its media type should be overridden.
+            poll_interval: interval in seconds between job status polls.
+                Applies while job status is still "accepted" or "running".
+            timeout: maximum time in seconds to wait for job completion.
+            options: additional opener-specific options.
+
+        Returns:
+            The job result value.
+
+        Raises:
+            ClientError: if an API error occurs
+            JobResultOpenError: if an opener error occurs
+            JobResultStatusError: if the job failed or was canceled
+            TimeoutError: if the job does not finish within the timeout
+        """
+        deadline = asyncio.get_running_loop().time() + timeout
+        while True:
+            job_info = await self.get_job(job_id)
+            if job_info.status not in (JobStatus.accepted, JobStatus.running):
+                break
+            if asyncio.get_running_loop().time() >= deadline:
+                raise TimeoutError(
+                    f"Cannot open result of job #{job_id}; "
+                    f"it did not finish within {timeout} seconds"
+                )
+            await asyncio.sleep(poll_interval)
+        if job_info.status != JobStatus.successful:
+            raise JobResultStatusError(job_info)
+        job_results = await self.get_job_results(job_id)
+        process_id = job_info.processID
+        process_description: ProcessDescription | None = None
+        if process_id:
+            try:
+                process_description = await self.get_process(process_id)
+            except ClientError:
+                warnings.warn(
+                    "An error occurred while getting process "
+                    f"description for process ID {process_id!r}",
+                    category=ClientWarning,
+                    stacklevel=2,
+                )
+        ctx = JobResultOpenContext(
+            config=self.config,
+            job_id=job_id,
+            job_results=job_results,
+            process_description=process_description,
+            output_name=output_name,
+            data_type=data_type,
+            _media_type=media_type,
+            options=options,
+        )
+        opener_registry = self.config.get_job_result_opener_registry()
+        return await open_job_result(ctx, *opener_registry.opener_types)

cuiman-0.3.0/cuiman/api/auth/__init__.py

@@ -0,0 +1,35 @@
+#  Copyright (c) 2025-2026 by the Eozilla team and contributors
+#  Permissions are hereby granted under the terms of the Apache 2.0 License:
+#  https://opensource.org/license/apache-2.0.
+
+from .config import (
+    ApiKeyAuthConfig,
+    AuthConfig,
+    AuthConfigBase,
+    AuthType,
+    BasicAuthConfig,
+    LoginAuthConfig,
+    NoAuthConfig,
+    OAuth2AuthConfig,
+    OAuth2GrantType,
+    OidcAuthConfig,
+    SecretFields,
+    TokenAuthConfig,
+)
+from .oauth2_client import LoginRequiredError
+
+__all__ = [
+    "ApiKeyAuthConfig",
+    "AuthConfig",
+    "AuthConfigBase",
+    "AuthType",
+    "BasicAuthConfig",
+    "LoginAuthConfig",
+    "NoAuthConfig",
+    "OAuth2AuthConfig",
+    "OAuth2GrantType",
+    "OidcAuthConfig",
+    "SecretFields",
+    "TokenAuthConfig",
+    "LoginRequiredError",
+]