osdu-python-client 0.4.1__py3-none-any.whl

osdu_python_client/__init__.py

@@ -0,0 +1,31 @@
+from osdu_python_client.async_client import AsyncOsduClient
+from osdu_python_client.auth import (
+    ClientCredentialsProvider,
+    MsalDeviceFlowProvider,
+    MsalInteractiveProvider,
+    TokenProvider,
+)
+from osdu_python_client.client import OsduClient
+from osdu_python_client.config import OsduConfig
+from osdu_python_client.errors import (
+    OsduAuthError,
+    OsduConfigError,
+    OsduError,
+    OsduRetryExhausted,
+)
+from osdu_python_client.logging_setup import enable_debug_logging
+
+__all__ = [
+    "AsyncOsduClient",
+    "ClientCredentialsProvider",
+    "MsalDeviceFlowProvider",
+    "MsalInteractiveProvider",
+    "OsduAuthError",
+    "OsduClient",
+    "OsduConfig",
+    "OsduConfigError",
+    "OsduError",
+    "OsduRetryExhausted",
+    "TokenProvider",
+    "enable_debug_logging",
+]

osdu_python_client/async_client.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator
+
+import httpx
+
+from osdu_python_client.auth import TokenProvider, provider_for
+from osdu_python_client.config import OsduConfig
+from osdu_python_client.hooks import async_partition_hook
+from osdu_python_client.services.facade import ServiceFacade
+from osdu_python_client.services.registry import (
+    SERVICE_BY_ATTR,
+    ServiceSpec,
+    load_authenticated_client,
+)
+from osdu_python_client.transport import AsyncRetryTransport
+
+
+class AsyncOsduClient:
+    def __init__(
+        self,
+        config: OsduConfig | None = None,
+        token_provider: TokenProvider | None = None,
+    ) -> None:
+        self._services: dict[str, ServiceFacade] = {}
+        self._httpx_clients: dict[str, httpx.AsyncClient] = {}
+        self.config = config or OsduConfig()
+        self._provider = token_provider or provider_for(self.config)
+        self._transport = AsyncRetryTransport(
+            self._provider,
+            max_attempts=self.config.retry_attempts,
+            base_delay=self.config.retry_base_delay,
+        )
+
+    def _build_service(self, spec: ServiceSpec) -> ServiceFacade:
+        auth_cls = load_authenticated_client(spec)
+        base_url = self.config.url_for(spec.attr)
+        timeout = httpx.Timeout(self.config.timeout_seconds)
+        httpx_client = httpx.AsyncClient(
+            base_url=base_url,
+            transport=self._transport,
+            timeout=timeout,
+            verify=self.config.verify_ssl,
+            event_hooks={
+                "request": [async_partition_hook(self.config.data_partition_id)]
+            },
+        )
+        self._httpx_clients[spec.attr] = httpx_client
+        auth_client = auth_cls(base_url=base_url, token="")
+        auth_client.set_async_httpx_client(httpx_client)
+        return ServiceFacade(
+            spec.module, auth_client, self.config.data_partition_id, is_async=True
+        )
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        spec = SERVICE_BY_ATTR.get(name)
+        if spec is None:
+            raise AttributeError(
+                f"{type(self).__name__!r} has no attribute {name!r}"
+            )
+        services = self.__dict__.get("_services")
+        if services is None:
+            raise AttributeError(name)
+        cached = services.get(name)
+        if cached is not None:
+            return cached
+        facade = self._build_service(spec)
+        services[name] = facade
+        return facade
+
+    def __dir__(self) -> list[str]:
+        return sorted({*super().__dir__(), *SERVICE_BY_ATTR})
+
+    @asynccontextmanager
+    async def with_headers(
+        self, *, service: str | None = None, **headers: str
+    ) -> AsyncIterator["AsyncOsduClient"]:
+        if service is not None:
+            getattr(self, service)
+            targets = [self._httpx_clients[service]]
+        else:
+            targets = list(self._httpx_clients.values())
+
+        saved = [(c, dict(c.headers)) for c in targets]
+        for c in targets:
+            c.headers.update(headers)
+        try:
+            yield self
+        finally:
+            for c, prev in saved:
+                c.headers.clear()
+                c.headers.update(prev)
+
+    async def aclose(self) -> None:
+        for c in self._httpx_clients.values():
+            await c.aclose()
+        self._httpx_clients.clear()
+        self._services.clear()
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> "AsyncOsduClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()

osdu_python_client/async_client.pyi

@@ -0,0 +1,57 @@
+# Auto-generated by stubgen.py — do not edit.
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator
+
+from osdu_python_client.auth import TokenProvider
+from osdu_python_client.config import OsduConfig
+from osdu_python_client.generated.search._facade import AsyncSearchFacade
+from osdu_python_client.generated.storage._facade import AsyncStorageFacade
+from osdu_python_client.generated.schema._facade import AsyncSchemaFacade
+from osdu_python_client.generated.entitlements._facade import AsyncEntitlementsFacade
+from osdu_python_client.generated.legal._facade import AsyncLegalFacade
+from osdu_python_client.generated.file._facade import AsyncFileFacade
+from osdu_python_client.generated.dataset._facade import AsyncDatasetFacade
+from osdu_python_client.generated.indexer._facade import AsyncIndexerFacade
+from osdu_python_client.generated.notification._facade import AsyncNotificationFacade
+from osdu_python_client.generated.partition._facade import AsyncPartitionFacade
+from osdu_python_client.generated.policy._facade import AsyncPolicyFacade
+from osdu_python_client.generated.register._facade import AsyncRegisterFacade
+from osdu_python_client.generated.unit._facade import AsyncUnitFacade
+from osdu_python_client.generated.crs_catalog._facade import AsyncCrsCatalogFacade
+from osdu_python_client.generated.crs_conversion._facade import AsyncCrsConversionFacade
+from osdu_python_client.generated.wellbore_ddms._facade import AsyncWellboreDdmsFacade
+from osdu_python_client.generated.seismic_ddms._facade import AsyncSeismicDdmsFacade
+
+class AsyncOsduClient:
+    config: OsduConfig
+    search: AsyncSearchFacade
+    storage: AsyncStorageFacade
+    schema: AsyncSchemaFacade
+    entitlements: AsyncEntitlementsFacade
+    legal: AsyncLegalFacade
+    file: AsyncFileFacade
+    dataset: AsyncDatasetFacade
+    indexer: AsyncIndexerFacade
+    notification: AsyncNotificationFacade
+    partition: AsyncPartitionFacade
+    policy: AsyncPolicyFacade
+    register: AsyncRegisterFacade
+    unit: AsyncUnitFacade
+    crs_catalog: AsyncCrsCatalogFacade
+    crs_conversion: AsyncCrsConversionFacade
+    wellbore_ddms: AsyncWellboreDdmsFacade
+    seismic_ddms: AsyncSeismicDdmsFacade
+    def __init__(
+        self,
+        config: OsduConfig | None = ...,
+        token_provider: TokenProvider | None = ...,
+    ) -> None: ...
+    def __getattr__(self, name: str) -> Any: ...
+    def __dir__(self) -> list[str]: ...
+    @asynccontextmanager
+    async def with_headers(
+        self, *, service: str | None = ..., **headers: str
+    ) -> AsyncIterator[AsyncOsduClient]: ...
+    async def aclose(self) -> None: ...
+    async def __aenter__(self) -> AsyncOsduClient: ...
+    async def __aexit__(self, *args: Any) -> None: ...

osdu_python_client/auth/__init__.py

@@ -0,0 +1,69 @@
+"""Pluggable auth subsystem.
+
+The core extension point is the :class:`TokenProvider` Protocol. CSP-specific
+providers self-register on import. Built-in registry entries:
+
+- ``community`` — OSDU Community / baremetal via Keycloak client credentials (id_token).
+- ``azure_msal`` — Azure / Entra ID via MSAL (interactive, device flow, client credentials, workload identity).
+- ``aws_cognito`` — AWS via OAuth2 client credentials against a Cognito/custom token endpoint.
+- ``gcp_iam``    — GCP via google-auth (service account JSON or Application Default Credentials).
+- ``ibm_iam``    — IBM via Keycloak OIDC (resource owner password).
+
+For unsupported CSPs, pass your own ``TokenProvider`` to ``OsduClient`` and
+ignore this whole machinery.
+"""
+
+from osdu_python_client.auth._base import (
+    TokenProvider,
+    TokenProviderFactory,
+    provider_for,
+    register_provider,
+    registered_providers,
+)
+
+# Eager imports trigger registry side effects. Each module's CSP-specific SDK
+# is imported lazily (only when a provider is instantiated), so importing these
+# modules is always safe regardless of which optional extras are installed.
+from osdu_python_client.auth import ci as _ci  # noqa: F401
+from osdu_python_client.auth import aws as _aws  # noqa: F401
+from osdu_python_client.auth import azure as _azure  # noqa: F401
+from osdu_python_client.auth import gcp as _gcp  # noqa: F401
+from osdu_python_client.auth import ibm as _ibm  # noqa: F401
+from osdu_python_client.auth.aws import AwsClientCredentialsProvider, AwsConfig
+from osdu_python_client.auth.azure import (
+    AzureMsalConfig,
+    ClientCredentialsProvider,
+    MsalDeviceFlowProvider,
+    MsalInteractiveProvider,
+    WorkloadIdentityProvider,
+)
+from osdu_python_client.auth.ci import CiConfig, CiKeycloakProvider
+from osdu_python_client.auth.gcp import GcpConfig, GcpTokenProvider
+from osdu_python_client.auth.ibm import IbmConfig, IbmKeycloakProvider
+
+__all__ = [
+    # Community / baremetal
+    "CiConfig",
+    "CiKeycloakProvider",
+    # Azure
+    "AzureMsalConfig",
+    "ClientCredentialsProvider",
+    "MsalDeviceFlowProvider",
+    "MsalInteractiveProvider",
+    "WorkloadIdentityProvider",
+    # AWS
+    "AwsConfig",
+    "AwsClientCredentialsProvider",
+    # GCP
+    "GcpConfig",
+    "GcpTokenProvider",
+    # IBM
+    "IbmConfig",
+    "IbmKeycloakProvider",
+    # Base
+    "TokenProvider",
+    "TokenProviderFactory",
+    "provider_for",
+    "register_provider",
+    "registered_providers",
+]

osdu_python_client/auth/_base.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Callable, Protocol, runtime_checkable
+
+from osdu_python_client.errors import OsduConfigError
+
+if TYPE_CHECKING:
+    from osdu_python_client.config import OsduConfig
+
+log = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class TokenProvider(Protocol):
+    """The single auth extension point.
+
+    Implementations must return a non-empty bearer token string. ``force_refresh``
+    is a hint: the transport sets it to ``True`` after a 401 to force a fresh
+    fetch rather than reuse a cached token.
+    """
+
+    def get_token(self, force_refresh: bool = False) -> str: ...
+
+
+TokenProviderFactory = Callable[["OsduConfig"], TokenProvider]
+
+_REGISTRY: dict[str, TokenProviderFactory] = {}
+
+
+def register_provider(name: str, factory: TokenProviderFactory) -> None:
+    """Register a CSP-specific token provider factory under ``name``.
+
+    Calling ``register_provider("azure_msal", factory)`` lets users select it
+    via ``OsduConfig.auth_provider = "azure_msal"``. Built-in providers live
+    in ``osdu_python_client.auth.<csp>`` and self-register on import.
+    """
+    if name in _REGISTRY:
+        log.debug("re-registering auth provider %r", name)
+    _REGISTRY[name] = factory
+
+
+def registered_providers() -> list[str]:
+    return sorted(_REGISTRY)
+
+
+def provider_for(config: "OsduConfig") -> TokenProvider:
+    """Build the provider selected by ``config.auth_provider``.
+
+    Callers that want full control should bypass this and pass their own
+    ``TokenProvider`` to ``OsduClient(token_provider=...)``.
+    """
+    factory = _REGISTRY.get(config.auth_provider)
+    if factory is None:
+        raise OsduConfigError(
+            f"auth_provider={config.auth_provider!r} is not registered. "
+            f"Available providers: {registered_providers()}. "
+            f"For unsupported CSPs, pass token_provider=... to OsduClient directly."
+        )
+    return factory(config)

osdu_python_client/auth/aws.py

@@ -0,0 +1,101 @@
+"""AWS auth provider — OAuth2 client credentials flow.
+
+OSDU-on-AWS deployments authenticate via an OAuth2 client credentials endpoint
+(typically backed by AWS Cognito). No boto3 or AWS SDK is required — the flow
+is a standard Basic-auth POST to a token endpoint.
+
+Required environment variables (or .env entries):
+
+    AWS_TOKEN_ENDPOINT  — full URL of the OAuth2 token endpoint
+    AWS_CLIENT_ID       — OAuth2 client ID
+    AWS_CLIENT_SECRET   — OAuth2 client secret
+    AWS_SCOPES          — space-separated scopes (optional)
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import threading
+import time
+from typing import TYPE_CHECKING
+
+import httpx
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from osdu_python_client.auth._base import TokenProvider, register_provider
+from osdu_python_client.errors import OsduAuthError
+
+if TYPE_CHECKING:
+    from osdu_python_client.config import OsduConfig
+
+log = logging.getLogger(__name__)
+
+
+class AwsConfig(BaseSettings):
+    """AWS OAuth2 auth settings, loaded from the same ``.env`` as OsduConfig."""
+
+    aws_token_endpoint: str
+    aws_client_id: str
+    aws_client_secret: str
+    aws_scopes: str = ""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    @property
+    def scopes_list(self) -> list[str]:
+        return self.aws_scopes.split() if self.aws_scopes.strip() else []
+
+
+class AwsClientCredentialsProvider:
+    """Token provider for OSDU-on-AWS using OAuth2 client credentials."""
+
+    def __init__(self, config: AwsConfig) -> None:
+        self._config = config
+        self._lock = threading.Lock()
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+
+    def get_token(self, force_refresh: bool = False) -> str:
+        with self._lock:
+            if force_refresh or self._token is None or time.monotonic() >= self._expires_at:
+                self._fetch()
+            return self._token  # type: ignore[return-value]
+
+    def _fetch(self) -> None:
+        cfg = self._config
+        encoded = base64.b64encode(f"{cfg.aws_client_id}:{cfg.aws_client_secret}".encode()).decode()
+        headers = {
+            "Authorization": f"Basic {encoded}",
+            "Content-Type": "application/x-www-form-urlencoded",
+        }
+        data: dict[str, str] = {"grant_type": "client_credentials"}
+        if cfg.scopes_list:
+            data["scope"] = " ".join(cfg.scopes_list)
+
+        log.debug("acquiring AWS token from %s", cfg.aws_token_endpoint)
+        response = httpx.post(cfg.aws_token_endpoint, headers=headers, data=data, timeout=30)
+        if response.status_code != 200:
+            raise OsduAuthError(
+                f"AWS token request failed [{response.status_code}]: {response.text}"
+            )
+        payload = response.json()
+        token = payload.get("access_token")
+        if not token:
+            raise OsduAuthError(f"AWS token response missing access_token: {payload}")
+
+        expires_in = int(payload.get("expires_in", 3600))
+        self._token = token
+        self._expires_at = time.monotonic() + expires_in - 60  # 60s early-refresh buffer
+        log.debug("AWS token acquired, expires in %ds", expires_in)
+
+
+def _factory(_config: "OsduConfig") -> TokenProvider:
+    return AwsClientCredentialsProvider(AwsConfig())
+
+
+register_provider("aws_cognito", _factory)