datacosmos 0.0.12__py3-none-any.whl → 0.0.13__py3-none-any.whl

datacosmos/auth/__init__.py

@@ -0,0 +1 @@
+"""Handles authentication related things."""

datacosmos/auth/local_token_fetcher.py

@@ -0,0 +1,156 @@
+"""Opens a browser for the user to log in (Authorization Code), caches token to a file, and refreshes when expired."""
+
+from __future__ import annotations
+
+import http.server
+import json
+import socketserver
+import time
+import urllib.parse
+import webbrowser
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import requests
+
+from datacosmos.auth.token import Token
+
+
+@dataclass
+class LocalTokenFetcher:
+    """Opens a browser for the user to log in (Authorization Code), caches token to a file, and refreshes when expired."""
+
+    client_id: str
+    authorization_endpoint: str
+    token_endpoint: str
+    redirect_port: int
+    audience: str
+    scopes: str
+    token_file: Path
+
+    def get_token(self) -> Token:
+        """Return a valid token from cache, or refresh / interact as needed."""
+        tok = self.__load()
+        if not tok:
+            return self.__interactive_login()
+
+        if tok.is_expired():
+            # Try to refresh; if that fails for any reason, fall back to interactive login.
+            try:
+                return self.__refresh(tok)
+            except (requests.HTTPError, RuntimeError):
+                return self.__interactive_login()
+
+        return tok
+
+    def __save(self, token: Token) -> None:
+        self.token_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.token_file, "w") as f:
+            json.dump(
+                {
+                    "access_token": token.access_token,
+                    "refresh_token": token.refresh_token,
+                    "expires_at": token.expires_at,
+                },
+                f,
+            )
+
+    def __load(self) -> Optional[Token]:
+        if not self.token_file.exists():
+            return None
+        with open(self.token_file, "r") as f:
+            data = json.load(f)
+        return Token(
+            access_token=data["access_token"],
+            refresh_token=data.get("refresh_token"),
+            expires_at=int(data["expires_at"]),
+        )
+
+    def __exchange_code(self, code: str) -> Token:
+        data = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": f"http://localhost:{self.redirect_port}/oauth/callback",
+            "client_id": self.client_id,
+            "audience": self.audience,
+        }
+        resp = requests.post(self.token_endpoint, data=data, timeout=30)
+        resp.raise_for_status()
+        return Token.from_json_response(resp.json())
+
+    def __refresh(self, token: Token) -> Token:
+        """Refresh the token, persist it on success, and return it.
+
+        Raises:
+            RuntimeError: if no refresh_token is available.
+            requests.HTTPError: if the token endpoint returns an error.
+        """
+        if not token.refresh_token:
+            raise RuntimeError("No refresh_token available for local auth refresh")
+
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": token.refresh_token,
+            "client_id": self.client_id,
+            "audience": self.audience,
+        }
+        resp = requests.post(self.token_endpoint, data=data, timeout=30)
+        resp.raise_for_status()  # will raise requests.HTTPError on non-2xx
+
+        payload = resp.json()
+        refreshed = Token(
+            access_token=payload["access_token"],
+            refresh_token=token.refresh_token,
+            expires_at=time.time() + int(payload.get("expires_in", 3600)),
+        )
+        self.__save(refreshed)
+        return refreshed
+
+    def __interactive_login(self) -> Token:
+        params = {
+            "client_id": self.client_id,
+            "response_type": "code",
+            "redirect_uri": f"http://localhost:{self.redirect_port}/oauth/callback",
+            "audience": self.audience,
+            "scope": self.scopes,
+        }
+        url = f"{self.authorization_endpoint}?{urllib.parse.urlencode(params)}"
+
+        with suppress(Exception):
+            webbrowser.open(url, new=1, autoraise=True)
+
+        class Handler(http.server.BaseHTTPRequestHandler):
+            code: Optional[str] = None
+
+            def do_GET(self):  # noqa: N802
+                qs = urllib.parse.urlparse(self.path).query
+                data = urllib.parse.parse_qs(qs)
+                if "code" in data:
+                    Handler.code = data["code"][0]
+                    self.send_response(200)
+                    self.end_headers()
+                    self.wfile.write(b"Login complete. You can close this window.")
+                else:
+                    self.send_response(400)
+                    self.end_headers()
+                    self.wfile.write(b"No authorization code found.")
+
+            def log_message(self, *_args, **_kwargs) -> None:
+                return
+
+        with socketserver.TCPServer(
+            ("localhost", int(self.redirect_port)), Handler
+        ) as httpd:
+            httpd.timeout = 300  # 5 minutes
+            httpd.handle_request()
+
+        if not Handler.code:
+            raise RuntimeError(
+                f"Login timed out. If your browser did not open, visit:\n{url}"
+            )
+
+        token = self.__exchange_code(Handler.code)
+        self.__save(token)
+        return token

datacosmos/auth/token.py

@@ -0,0 +1,82 @@
+"""Authentication Token class."""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+DEFAULT_TOKEN_TTL_FALLBACK = 300  # seconds
+
+
+@dataclass
+class Token:
+    """Authentication token class."""
+
+    access_token: str
+    refresh_token: Optional[str]
+    expires_at: int  # unix epoch seconds
+
+    @classmethod
+    def from_json_response(cls, data: dict) -> Token:
+        """Build a Token from an OAuth2 response.
+
+        Prefer `expires_at` (absolute epoch seconds), then `expires_in`
+        (relative per RFC 6749). If both are missing, try to derive `exp`
+        from a JWT access token; otherwise fall back to a short TTL.
+        """
+        exp: Optional[int] = None
+
+        if data.get("expires_at") is not None:
+            try:
+                exp = int(float(data["expires_at"]))
+            except (TypeError, ValueError):
+                exp = None
+
+        if exp is None and data.get("expires_in") is not None:
+            try:
+                exp = int(time.time()) + int(data["expires_in"])
+            except (TypeError, ValueError, OverflowError):
+                exp = None
+
+        if exp is None:
+            exp = cls.__jwt_exp(data.get("access_token", ""))
+
+        if exp is None:
+            exp = int(time.time()) + DEFAULT_TOKEN_TTL_FALLBACK
+
+        return cls(
+            access_token=data["access_token"],
+            refresh_token=data.get("refresh_token"),
+            expires_at=exp,
+        )
+
+    def is_expired(self, skew_seconds: int = 30) -> bool:
+        """Treat the token as expired slightly early to account for clock skew."""
+        return time.time() >= (self.expires_at - skew_seconds)
+
+    @staticmethod
+    def __jwt_exp(access_token: str) -> Optional[int]:
+        """Best-effort extract of `exp` (epoch seconds) from a JWT access token.
+
+        We do NOT validate the signature here; this is only used as a heuristic
+        when the IdP omits both `expires_at` and `expires_in`.
+        """
+        if not access_token:
+            return None
+        try:
+            parts = access_token.split(".")
+            if len(parts) != 3:
+                return None
+            payload_b64 = parts[1]
+            padding = "=" * (-len(payload_b64) % 4)
+            payload = json.loads(
+                base64.urlsafe_b64decode(payload_b64 + padding).decode()
+            )
+            if "exp" in payload:
+                return int(payload["exp"])
+        except Exception:
+            return None
+        return None

datacosmos/config/auth/__init__.py

@@ -0,0 +1 @@
+"""Configuration authentication related things."""

datacosmos/config/auth/factory.py

@@ -0,0 +1,157 @@
+"""Config authentication factory.
+
+This module normalizes the `authentication` config into a concrete model:
+- `parse_auth_config` converts raw dicts (e.g., from YAML/env) into a model instance.
+- `apply_auth_defaults` fills sensible defaults per auth type without inventing secrets.
+- `check_required_auth_fields` enforces the minimum required inputs.
+- `normalize_authentication` runs the whole pipeline.
+
+Design notes:
+- Auth models accept partial data (fields are Optional with None defaults).
+- We DO NOT pass `None` explicitly when constructing models here.
+- Required-ness is enforced centrally by `check_required_auth_fields`, not by model init.
+"""
+
+from typing import Optional, Union, cast
+
+from datacosmos.config.constants import (
+    DEFAULT_AUTH_AUDIENCE,
+    DEFAULT_AUTH_TOKEN_URL,
+    DEFAULT_AUTH_TYPE,
+    DEFAULT_LOCAL_AUTHORIZATION_ENDPOINT,
+    DEFAULT_LOCAL_CACHE_FILE,
+    DEFAULT_LOCAL_REDIRECT_PORT,
+    DEFAULT_LOCAL_SCOPES,
+    DEFAULT_LOCAL_TOKEN_ENDPOINT,
+)
+from datacosmos.config.models.local_user_account_authentication_config import (
+    LocalUserAccountAuthenticationConfig,
+)
+from datacosmos.config.models.m2m_authentication_config import M2MAuthenticationConfig
+
+AuthModel = Union[M2MAuthenticationConfig, LocalUserAccountAuthenticationConfig]
+
+
+def parse_auth_config(raw: dict | AuthModel | None) -> Optional[AuthModel]:
+    """Turn a raw dict (e.g., from YAML) into a concrete auth model.
+
+    - If `raw` is already an auth model (M2M or local), return it unchanged.
+    - If `raw` is a dict, choose/validate the type using `raw['type']`
+      (or DEFAULT_AUTH_TYPE), then construct the corresponding model.
+      For missing fields we *may* apply non-secret defaults (endpoints, etc.).
+    """
+    if raw is None or isinstance(
+        raw, (M2MAuthenticationConfig, LocalUserAccountAuthenticationConfig)
+    ):
+        return cast(Optional[AuthModel], raw)
+
+    auth_type = _normalize_auth_type(raw.get("type") or DEFAULT_AUTH_TYPE)
+
+    if auth_type == "local":
+        return LocalUserAccountAuthenticationConfig(
+            type="local",
+            client_id=raw.get("client_id"),
+            authorization_endpoint=raw.get(
+                "authorization_endpoint", DEFAULT_LOCAL_AUTHORIZATION_ENDPOINT
+            ),
+            token_endpoint=raw.get("token_endpoint", DEFAULT_LOCAL_TOKEN_ENDPOINT),
+            redirect_port=raw.get("redirect_port", DEFAULT_LOCAL_REDIRECT_PORT),
+            scopes=raw.get("scopes", DEFAULT_LOCAL_SCOPES),
+            audience=raw.get("audience", DEFAULT_AUTH_AUDIENCE),
+            cache_file=raw.get("cache_file", DEFAULT_LOCAL_CACHE_FILE),
+        )
+
+    return M2MAuthenticationConfig(
+        type="m2m",
+        token_url=raw.get("token_url", DEFAULT_AUTH_TOKEN_URL),
+        audience=raw.get("audience", DEFAULT_AUTH_AUDIENCE),
+        client_id=raw.get("client_id"),
+        client_secret=raw.get("client_secret"),
+    )
+
+
+def apply_auth_defaults(auth: AuthModel | None) -> AuthModel:
+    """Fill in any missing defaults by type (non-secret values only).
+
+    If `auth` is None, construct a default "shell" based on DEFAULT_AUTH_TYPE,
+    without passing None for unknown credentials.
+    """
+    if auth is None:
+        default_type = _normalize_auth_type(DEFAULT_AUTH_TYPE)
+        if default_type == "local":
+            auth = LocalUserAccountAuthenticationConfig(
+                type="local",
+                authorization_endpoint=DEFAULT_LOCAL_AUTHORIZATION_ENDPOINT,
+                token_endpoint=DEFAULT_LOCAL_TOKEN_ENDPOINT,
+                redirect_port=DEFAULT_LOCAL_REDIRECT_PORT,
+                scopes=DEFAULT_LOCAL_SCOPES,
+                audience=DEFAULT_AUTH_AUDIENCE,
+                cache_file=DEFAULT_LOCAL_CACHE_FILE,
+            )
+        else:  # "m2m"
+            auth = M2MAuthenticationConfig(
+                type="m2m",
+                token_url=DEFAULT_AUTH_TOKEN_URL,
+                audience=DEFAULT_AUTH_AUDIENCE,
+            )
+
+    if isinstance(auth, M2MAuthenticationConfig):
+        auth.type = auth.type or "m2m"
+        auth.token_url = auth.token_url or DEFAULT_AUTH_TOKEN_URL
+        auth.audience = auth.audience or DEFAULT_AUTH_AUDIENCE
+        return auth
+
+    # Local defaults (Pydantic already coerces types; only set when missing)
+    auth.type = auth.type or "local"
+    auth.authorization_endpoint = (
+        auth.authorization_endpoint or DEFAULT_LOCAL_AUTHORIZATION_ENDPOINT
+    )
+    auth.token_endpoint = auth.token_endpoint or DEFAULT_LOCAL_TOKEN_ENDPOINT
+    if auth.redirect_port is None:
+        auth.redirect_port = DEFAULT_LOCAL_REDIRECT_PORT
+    auth.scopes = auth.scopes or DEFAULT_LOCAL_SCOPES
+    auth.audience = auth.audience or DEFAULT_AUTH_AUDIENCE
+    auth.cache_file = auth.cache_file or DEFAULT_LOCAL_CACHE_FILE
+    return auth
+
+
+def check_required_auth_fields(auth: AuthModel) -> None:
+    """Enforce required fields per auth type.
+
+    - m2m requires client_id and client_secret.
+    - local requires client_id.
+    """
+    if isinstance(auth, M2MAuthenticationConfig):
+        missing = [f for f in ("client_id", "client_secret") if not getattr(auth, f)]
+        if missing:
+            raise ValueError(
+                f"Missing required authentication fields for m2m: {', '.join(missing)}"
+            )
+        return
+
+    if isinstance(auth, LocalUserAccountAuthenticationConfig):
+        if not auth.client_id:
+            raise ValueError(
+                "Missing required authentication field for local: client_id"
+            )
+        return
+
+    raise ValueError(f"Unsupported authentication model: {type(auth).__name__}")
+
+
+def normalize_authentication(raw: dict | AuthModel | None) -> AuthModel:
+    """End-to-end auth normalization: parse -> apply defaults -> required-field checks."""
+    model = parse_auth_config(raw)
+    model = apply_auth_defaults(model)
+    check_required_auth_fields(model)
+    return model
+
+
+def _normalize_auth_type(value: str) -> str:
+    """Return a normalized auth type or raise for unsupported values."""
+    v = (value or "").strip().lower()
+    if v in {"m2m", "local"}:
+        return v
+    raise ValueError(
+        f"Unsupported authentication type: {value!r}. Expected 'm2m' or 'local'."
+    )

datacosmos/config/config.py

@@ -5,15 +5,19 @@ It loads default values, allows overrides via YAML configuration files,
 and supports environment variable-based overrides.
 """
 
-import os
-from typing import ClassVar, Optional
+from typing import Optional
 
-import yaml
 from pydantic import field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+from datacosmos.config.auth.factory import normalize_authentication, parse_auth_config
+from datacosmos.config.constants import (
+    DEFAULT_CONFIG_YAML,
+    DEFAULT_STAC,
+    DEFAULT_STORAGE,
+)
+from datacosmos.config.loaders.yaml_source import yaml_settings_source
 from datacosmos.config.models.authentication_config import AuthenticationConfig
-from datacosmos.config.models.m2m_authentication_config import M2MAuthenticationConfig
 from datacosmos.config.models.url import URL
 
 
@@ -27,196 +31,71 @@ class Config(BaseSettings):
     )
 
     authentication: Optional[AuthenticationConfig] = None
-    stac: Optional[URL] = None
-    datacosmos_cloud_storage: Optional[URL] = None
-    datacosmos_public_cloud_storage: Optional[URL] = None
-
-    DEFAULT_AUTH_TYPE: ClassVar[str] = "m2m"
-    DEFAULT_AUTH_TOKEN_URL: ClassVar[str] = "https://login.open-cosmos.com/oauth/token"
-    DEFAULT_AUTH_AUDIENCE: ClassVar[str] = "https://beeapp.open-cosmos.com"
-
-    @classmethod
-    def from_yaml(cls, file_path: str = "config/config.yaml") -> "Config":
-        """Load configuration from a YAML file and override defaults.
-
-        Args:
-            file_path (str): The path to the YAML configuration file.
-
-        Returns:
-            Config: An instance of the Config class with loaded settings.
-        """
-        config_data: dict = {}
-        if os.path.exists(file_path):
-            with open(file_path, "r") as f:
-                yaml_data = yaml.safe_load(f) or {}
-                # Remove empty values from YAML to avoid overwriting with `None`
-                config_data = {
-                    key: value
-                    for key, value in yaml_data.items()
-                    if value not in [None, ""]
-                }
-
-        return cls(**config_data)
+    stac: URL | None = None
+    datacosmos_cloud_storage: URL | None = None
+    datacosmos_public_cloud_storage: URL | None = None
 
     @classmethod
-    def from_env(cls) -> "Config":
-        """Load configuration from environment variables.
-
-        Returns:
-            Config: An instance of the Config class with settings loaded from environment variables.
-        """
-        authentication_config = M2MAuthenticationConfig(
-            type=os.getenv("OC_AUTH_TYPE", cls.DEFAULT_AUTH_TYPE),
-            client_id=os.getenv("OC_AUTH_CLIENT_ID"),
-            client_secret=os.getenv("OC_AUTH_CLIENT_SECRET"),
-            token_url=os.getenv("OC_AUTH_TOKEN_URL", cls.DEFAULT_AUTH_TOKEN_URL),
-            audience=os.getenv("OC_AUTH_AUDIENCE", cls.DEFAULT_AUTH_AUDIENCE),
-        )
-
-        stac_config = URL(
-            protocol=os.getenv("OC_STAC_PROTOCOL", "https"),
-            host=os.getenv("OC_STAC_HOST", "app.open-cosmos.com"),
-            port=int(os.getenv("OC_STAC_PORT", "443")),
-            path=os.getenv("OC_STAC_PATH", "/api/data/v0/stac"),
+    def settings_customise_sources(cls, *args, **kwargs):
+        """Sets customised sources."""
+        init_settings = kwargs.get("init_settings") or (
+            args[1] if len(args) > 1 else None
         )
-
-        datacosmos_cloud_storage_config = URL(
-            protocol=os.getenv("DC_CLOUD_STORAGE_PROTOCOL", "https"),
-            host=os.getenv("DC_CLOUD_STORAGE_HOST", "app.open-cosmos.com"),
-            port=int(os.getenv("DC_CLOUD_STORAGE_PORT", "443")),
-            path=os.getenv("DC_CLOUD_STORAGE_PATH", "/api/data/v0/storage"),
+        env_settings = kwargs.get("env_settings") or (
+            args[2] if len(args) > 2 else None
         )
-
-        datacosmos_public_cloud_storage_config = URL(
-            protocol=os.getenv("DC_PUBLIC_CLOUD_STORAGE_PROTOCOL", "https"),
-            host=os.getenv("DC_PUBLIC_CLOUD_STORAGE_HOST", "app.open-cosmos.com"),
-            port=int(os.getenv("DC_PUBLIC_CLOUD_STORAGE_PORT", "443")),
-            path=os.getenv("DC_PUBLIC_CLOUD_STORAGE_PATH", "/api/data/v0/storage"),
+        dotenv_settings = kwargs.get("dotenv_settings") or (
+            args[3] if len(args) > 3 else None
         )
-
-        return cls(
-            authentication=authentication_config,
-            stac=stac_config,
-            datacosmos_cloud_storage=datacosmos_cloud_storage_config,
-            datacosmos_public_cloud_storage=datacosmos_public_cloud_storage_config,
+        file_secret_settings = kwargs.get("file_secret_settings") or (
+            args[4] if len(args) > 4 else None
         )
 
-    @field_validator("authentication", mode="after")
-    @classmethod
-    def validate_authentication(
-        cls, auth: Optional[M2MAuthenticationConfig]
-    ) -> M2MAuthenticationConfig:
-        """Ensure authentication is provided and apply defaults.
-
-        Args:
-            auth (Optional[M2MAuthenticationConfig]): The authentication config.
-
-        Returns:
-            M2MAuthenticationConfig: The validated authentication configuration.
-
-        Raises:
-            ValueError: If authentication is missing or required fields are not set.
-        """
-        if auth is None:
-            auth = cls.apply_auth_defaults(M2MAuthenticationConfig())
-        else:
-            auth = cls.apply_auth_defaults(auth)
-
-        cls.check_required_auth_fields(auth)
-        return auth
-
-    @staticmethod
-    def apply_auth_defaults(auth: M2MAuthenticationConfig) -> M2MAuthenticationConfig:
-        """Apply default authentication values if they are missing."""
-        auth.type = auth.type or Config.DEFAULT_AUTH_TYPE
-        auth.token_url = auth.token_url or Config.DEFAULT_AUTH_TOKEN_URL
-        auth.audience = auth.audience or Config.DEFAULT_AUTH_AUDIENCE
-        return auth
+        sources = [
+            init_settings,
+            yaml_settings_source(DEFAULT_CONFIG_YAML),
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+        ]
+        return tuple(s for s in sources if s is not None)
 
+    @field_validator("authentication", mode="before")
     @classmethod
-    def parse_auth_config(cls, auth_data: dict) -> M2MAuthenticationConfig:
-        """Parse authentication config from a dictionary."""
-        return M2MAuthenticationConfig(
-            type=auth_data.get("type", cls.DEFAULT_AUTH_TYPE),
-            token_url=auth_data.get("token_url", cls.DEFAULT_AUTH_TOKEN_URL),
-            audience=auth_data.get("audience", cls.DEFAULT_AUTH_AUDIENCE),
-            client_id=auth_data.get("client_id"),
-            client_secret=auth_data.get("client_secret"),
+    def _parse_authentication(cls, raw):
+        if raw is None:
+            return None
+        from datacosmos.config.models.local_user_account_authentication_config import (
+            LocalUserAccountAuthenticationConfig,
+        )
+        from datacosmos.config.models.m2m_authentication_config import (
+            M2MAuthenticationConfig,
         )
 
-    @staticmethod
-    def check_required_auth_fields(auth: M2MAuthenticationConfig):
-        """Ensure required fields (client_id, client_secret) are provided."""
-        missing_fields = [
-            field
-            for field in ("client_id", "client_secret")
-            if not getattr(auth, field)
-        ]
-        if missing_fields:
-            raise ValueError(
-                f"Missing required authentication fields: {', '.join(missing_fields)}"
-            )
+        if isinstance(
+            raw, (M2MAuthenticationConfig, LocalUserAccountAuthenticationConfig)
+        ):
+            return raw
+        if isinstance(raw, dict):
+            return parse_auth_config(raw)
+        return raw
+
+    @field_validator("authentication", mode="after")
+    @classmethod
+    def _validate_authentication(cls, auth: Optional[AuthenticationConfig]):
+        return normalize_authentication(auth)
 
     @field_validator("stac", mode="before")
     @classmethod
-    def validate_stac(cls, stac_config: Optional[URL]) -> URL:
-        """Ensure STAC configuration has a default if not explicitly set.
-
-        Args:
-            stac_config (Optional[URL]): The STAC config to validate.
-
-        Returns:
-            URL: The validated STAC configuration.
-        """
-        if stac_config is None:
-            return URL(
-                protocol="https",
-                host="app.open-cosmos.com",
-                port=443,
-                path="/api/data/v0/stac",
-            )
-        return stac_config
+    def _default_stac(cls, value: URL | None) -> URL:
+        return value or URL(**DEFAULT_STAC)
 
     @field_validator("datacosmos_cloud_storage", mode="before")
     @classmethod
-    def validate_datacosmos_cloud_storage(
-        cls, datacosmos_cloud_storage_config: Optional[URL]
-    ) -> URL:
-        """Ensure datacosmos cloud storage configuration has a default if not explicitly set.
-
-        Args:
-            datacosmos_cloud_storage_config (Optional[URL]): The datacosmos cloud storage config to validate.
-
-        Returns:
-            URL: The validated datacosmos cloud storage configuration.
-        """
-        if datacosmos_cloud_storage_config is None:
-            return URL(
-                protocol="https",
-                host="app.open-cosmos.com",
-                port=443,
-                path="/api/data/v0/storage",
-            )
-        return datacosmos_cloud_storage_config
+    def _default_cloud_storage(cls, value: URL | None) -> URL:
+        return value or URL(**DEFAULT_STORAGE)
 
     @field_validator("datacosmos_public_cloud_storage", mode="before")
     @classmethod
-    def validate_datacosmos_public_cloud_storage(
-        cls, datacosmos_public_cloud_storage_config: Optional[URL]
-    ) -> URL:
-        """Ensure datacosmos cloud storage configuration has a default if not explicitly set.
-
-        Args:
-            datacosmos_public_cloud_storage_config (Optional[URL]): The datacosmos public cloud storage config to validate.
-
-        Returns:
-            URL: The validated datacosmos public cloud storage configuration.
-        """
-        if datacosmos_public_cloud_storage_config is None:
-            return URL(
-                protocol="https",
-                host="app.open-cosmos.com",
-                port=443,
-                path="/api/data/v0/storage",
-            )
-        return datacosmos_public_cloud_storage_config
+    def _default_public_cloud_storage(cls, value: URL | None) -> URL:
+        return value or URL(**DEFAULT_STORAGE)

datacosmos/config/constants.py

@@ -0,0 +1,26 @@
+"""Config constants."""
+
+# ---- Authentication defaults ----
+DEFAULT_AUTH_TYPE = "m2m"
+
+# M2M
+DEFAULT_AUTH_TOKEN_URL = "https://login.open-cosmos.com/oauth/token"
+DEFAULT_AUTH_AUDIENCE = "https://beeapp.open-cosmos.com"
+
+# Local (interactive)
+DEFAULT_LOCAL_AUTHORIZATION_ENDPOINT = "https://login.open-cosmos.com/authorize"
+DEFAULT_LOCAL_TOKEN_ENDPOINT = DEFAULT_AUTH_TOKEN_URL
+DEFAULT_LOCAL_REDIRECT_PORT = 8765
+DEFAULT_LOCAL_SCOPES = "openid profile email offline_access"
+DEFAULT_LOCAL_CACHE_FILE = "~/.datacosmos/token_cache.json"
+
+# ---- Service URLs ----
+DEFAULT_STAC = dict(
+    protocol="https", host="app.open-cosmos.com", port=443, path="/api/data/v0/stac"
+)
+DEFAULT_STORAGE = dict(
+    protocol="https", host="app.open-cosmos.com", port=443, path="/api/data/v0/storage"
+)
+
+# ---- Config file path ----
+DEFAULT_CONFIG_YAML = "config/config.yaml"

datacosmos/config/loaders/yaml_source.py

@@ -0,0 +1,62 @@
+"""YAML settings source for pydantic-settings.
+
+This module provides a tiny helper to inject a YAML file as a configuration
+source for `pydantic-settings` (v2.x). It returns a callable compatible with
+`BaseSettings.settings_customise_sources`, placed wherever you want in the
+precedence chain.
+
+- If the file is missing, the source returns an empty dict.
+- Empty-ish values (`None`, empty string, empty list) are dropped so they don't
+  overwrite values coming from later sources (e.g., environment variables).
+- The returned callable accepts `*args, **kwargs` to be version-agnostic across
+  pydantic-settings minor releases (some pass positional args, others keywords).
+"""
+
+from typing import Any, Callable, Dict
+
+# A callable that returns a mapping of settings values when invoked by pydantic-settings.
+SettingsSourceCallable = Callable[..., Dict[str, Any]]
+
+
+def yaml_settings_source(file_path: str) -> SettingsSourceCallable:
+    """Create a pydantic-settings-compatible source that reads from a YAML file.
+
+    Parameters
+    ----------
+    file_path : str
+        Absolute or relative path to the YAML file to load.
+
+    Returns
+    -------
+    SettingsSourceCallable
+        A callable that, when invoked by pydantic-settings, returns a dict
+        of settings loaded from the YAML file. If the file does not exist,
+        an empty dict is returned. Keys with empty/None values are omitted
+        so later sources (e.g., env vars) can provide effective overrides.
+
+    Notes
+    -----
+    The returned callable accepts arbitrary `*args` and `**kwargs` to stay
+    compatible with different pydantic-settings 2.x calling conventions.
+    """
+
+    def _source(*_args: Any, **_kwargs: Any) -> Dict[str, Any]:
+        """Load and sanitize YAML content for use as a settings source.
+
+        Returns
+        -------
+        dict
+            A dictionary of settings. If the YAML file is missing, `{}`.
+            Values that are `None`, empty strings, or empty lists are dropped.
+        """
+        import os
+
+        import yaml
+
+        if not os.path.exists(file_path):
+            return {}
+        with open(file_path, "r") as f:
+            data = yaml.safe_load(f) or {}
+        return {k: v for k, v in data.items() if v not in (None, "", [])}
+
+    return _source

datacosmos/config/models/local_user_account_authentication_config.py

@@ -4,23 +4,25 @@ When this is chosen, the user will be prompted to log in using their OPS credent
 This will be used for running scripts locally.
 """
 
-from typing import Literal
+from typing import Literal, Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 
 
 class LocalUserAccountAuthenticationConfig(BaseModel):
     """Configuration for local user account authentication.
 
     When this is chosen, the user will be prompted to log in using their OPS credentials.
-    This will be used for running scripts locally.
+    This will be used for running scripts locally. Required fields are enforced by `normalize_authentication` after merge.
     """
 
-    type: Literal["local"]
-    client_id: str
-    authorization_endpoint: str
-    token_endpoint: str
-    redirect_port: int
-    scopes: str
-    audience: str
-    cache_file: str
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["local"] = "local"
+    client_id: Optional[str] = None
+    authorization_endpoint: Optional[str] = None
+    token_endpoint: Optional[str] = None
+    redirect_port: Optional[int] = None
+    scopes: Optional[str] = None
+    audience: Optional[str] = None
+    cache_file: Optional[str] = None

datacosmos/config/models/m2m_authentication_config.py

@@ -4,24 +4,22 @@ Used when running scripts in the cluster that require automated authentication
 without user interaction.
 """
 
-from typing import Literal
+from typing import Literal, Optional
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict
 
 
 class M2MAuthenticationConfig(BaseModel):
     """Configuration for machine-to-machine authentication.
 
     This is used when running scripts in the cluster that require authentication
-    with client credentials.
+    with client credentials. Required fields are enforced by `normalize_authentication` after merge.
     """
 
-    DEFAULT_TYPE: Literal["m2m"] = "m2m"
-    DEFAULT_TOKEN_URL: str = "https://login.open-cosmos.com/oauth/token"
-    DEFAULT_AUDIENCE: str = "https://beeapp.open-cosmos.com"
+    model_config = ConfigDict(extra="forbid")
 
-    type: Literal["m2m"] = Field(default=DEFAULT_TYPE)
-    client_id: str
-    token_url: str = Field(default=DEFAULT_TOKEN_URL)
-    audience: str = Field(default=DEFAULT_AUDIENCE)
-    client_secret: str
+    type: Literal["m2m"] = "m2m"
+    client_id: Optional[str] = None
+    client_secret: Optional[str] = None
+    token_url: Optional[str] = None
+    audience: Optional[str] = None

datacosmos/datacosmos_client.py

@@ -1,6 +1,7 @@
 """Client to interact with the Datacosmos API with authentication and request handling."""
 
 from datetime import datetime, timedelta, timezone
+from pathlib import Path
 from typing import Any, Optional
 
 import requests
@@ -23,86 +24,183 @@ class DatacosmosClient:
         """Initialize the DatacosmosClient.
 
         Args:
-            config (Optional[Config]): Configuration object (only needed when SDK creates its own session).
-            http_session (Optional[requests.Session]): Pre-authenticated session.
+            config: SDK configuration (if omitted, Config() loads YAML + env).
+            http_session: Pre-authenticated session (OAuth2Session or requests.Session
+                          with 'Authorization: Bearer ...').
         """
+        self.config = self._coerce_config(config)
+        self.token: Optional[str] = None
+        self.token_expiry: Optional[datetime] = None
+
         if http_session is not None:
-            self._http_client = http_session
-            self._owns_session = False
-            if isinstance(http_session, OAuth2Session):
-                token_data = http_session.token
-            elif isinstance(http_session, requests.Session):
-                auth_header = http_session.headers.get("Authorization", "")
-                if not auth_header.startswith("Bearer "):
-                    raise DatacosmosException(
-                        "Injected requests.Session must include a 'Bearer' token in its headers"
-                    )
-                token_data = {"access_token": auth_header.split(" ", 1)[1]}
-            else:
+            self._init_with_injected_session(http_session)
+            return
+
+        self._owns_session = True
+        self._http_client = self._authenticate_and_initialize_client()
+
+    # --------------------------- init helpers ---------------------------
+
+    def _coerce_config(self, cfg: Optional[Config | Any]) -> Config:
+        """Normalize various config inputs into a Config instance."""
+        if cfg is None:
+            return Config()
+        if isinstance(cfg, Config):
+            return cfg
+        if isinstance(cfg, dict):
+            return Config(**cfg)
+        try:
+            return Config.model_validate(cfg)  # pydantic v2
+        except Exception as e:
+            raise DatacosmosException(
+                "Invalid config provided to DatacosmosClient"
+            ) from e
+
+    def _init_with_injected_session(
+        self, http_session: requests.Session | OAuth2Session
+    ) -> None:
+        """Adopt a caller-provided session and extract token/expiry."""
+        self._http_client = http_session
+        self._owns_session = False
+
+        token_data = self._extract_token_data(http_session)
+        self.token = token_data.get("access_token")
+        if not self.token:
+            raise DatacosmosException(
+                "Failed to extract access token from injected session"
+            )
+
+        self.token_expiry = self._compute_expiry(
+            token_data.get("expires_at"),
+            token_data.get("expires_in"),
+        )
+
+    def _extract_token_data(
+        self, http_session: requests.Session | OAuth2Session
+    ) -> dict:
+        """Return {'access_token', 'expires_at'?, 'expires_in'?} from the session."""
+        if isinstance(http_session, OAuth2Session):
+            return getattr(http_session, "token", {}) or {}
+
+        if isinstance(http_session, requests.Session):
+            auth_header = http_session.headers.get("Authorization", "")
+            if not auth_header.startswith("Bearer "):
                 raise DatacosmosException(
-                    f"Unsupported session type: {type(http_session)}"
+                    "Injected requests.Session must include a 'Bearer' token in its headers"
                 )
+            return {"access_token": auth_header.split(" ", 1)[1]}
+
+        raise DatacosmosException(f"Unsupported session type: {type(http_session)}")
+
+    def _compute_expiry(
+        self,
+        expires_at: Optional[datetime | int | float],
+        expires_in: Optional[int | float],
+    ) -> Optional[datetime]:
+        """Normalize expiry inputs to an absolute UTC datetime (or None)."""
+        if isinstance(expires_at, datetime):
+            return expires_at
+        if isinstance(expires_at, (int, float)):
+            return datetime.fromtimestamp(expires_at, tz=timezone.utc)
+        if expires_in is not None:
             try:
-                self.token = token_data.get("access_token")
-                self.token_expiry = token_data.get("expires_at") or token_data.get(
-                    "expires_in"
-                )
-            except Exception:
-                raise DatacosmosException(
-                    "Failed to extract token from injected session"
-                )
+                return datetime.now(timezone.utc) + timedelta(seconds=int(expires_in))
+            except (TypeError, ValueError):
+                return None
+        return None
 
-            self.config = config
-        else:
-            if config:
-                self.config = config
-            else:
-                try:
-                    self.config = Config.from_yaml()
-                except ValueError:
-                    self.config = Config.from_env()
-
-            self._owns_session = True
-            self.token = None
-            self.token_expiry = None
-            self._http_client = self._authenticate_and_initialize_client()
+    # --------------------------- auth/session ---------------------------
 
     def _authenticate_and_initialize_client(self) -> requests.Session:
         """Authenticate and initialize the HTTP client with a valid token."""
+        auth = self.config.authentication
+        auth_type = getattr(auth, "type", "m2m")
+
+        if auth_type == "m2m":
+            return self.__build_m2m_session()
+
+        if auth_type == "local":
+            return self.__build_local_session()
+
+        raise DatacosmosException(f"Unsupported authentication type: {auth_type}")
+
+    def _refresh_token_if_needed(self):
+        """Refresh the token if it has expired (only if SDK created it)."""
+        if not getattr(self, "_owns_session", False):
+            return
+        now = datetime.now(timezone.utc)
+        # Treat missing token or missing expiry as 'needs refresh'
+        if (
+            (not self.token)
+            or (self.token_expiry is None)
+            or (self.token_expiry <= now)
+        ):
+            self._http_client = self._authenticate_and_initialize_client()
+
+    def __build_m2m_session(self) -> requests.Session:
+        """Client Credentials (M2M) flow using requests-oauthlib."""
+        auth = self.config.authentication
         try:
-            client = BackendApplicationClient(
-                client_id=self.config.authentication.client_id
-            )
+            client = BackendApplicationClient(client_id=auth.client_id)
             oauth_session = OAuth2Session(client=client)
 
             token_response = oauth_session.fetch_token(
-                token_url=self.config.authentication.token_url,
-                client_id=self.config.authentication.client_id,
-                client_secret=self.config.authentication.client_secret,
-                audience=self.config.authentication.audience,
+                token_url=auth.token_url,
+                client_id=auth.client_id,
+                client_secret=auth.client_secret,
+                audience=auth.audience,
             )
 
             self.token = token_response["access_token"]
-            self.token_expiry = datetime.now(timezone.utc) + timedelta(
-                seconds=token_response.get("expires_in", 3600)
-            )
+            expires_at = token_response.get("expires_at")
+            if isinstance(expires_at, (int, float)):
+                self.token_expiry = datetime.fromtimestamp(expires_at, tz=timezone.utc)
+            else:
+                self.token_expiry = datetime.now(timezone.utc) + timedelta(
+                    seconds=int(token_response.get("expires_in", 3600))
+                )
 
             http_client = requests.Session()
             http_client.headers.update({"Authorization": f"Bearer {self.token}"})
             return http_client
+
         except (HTTPError, ConnectionError, Timeout) as e:
-            raise DatacosmosException(f"Authentication failed: {str(e)}") from e
+            raise DatacosmosException(f"Authentication failed: {e}") from e
         except RequestException as e:
             raise DatacosmosException(
-                f"Unexpected request failure during authentication: {str(e)}"
+                f"Unexpected request failure during authentication: {e}"
             ) from e
 
-    def _refresh_token_if_needed(self):
-        """Refresh the token if it has expired (only if SDK created it)."""
-        if self._owns_session and (
-            not self.token or self.token_expiry <= datetime.now(timezone.utc)
-        ):
-            self._http_client = self._authenticate_and_initialize_client()
+    def __build_local_session(self) -> requests.Session:
+        """Interactive local login via LocalTokenFetcher (cached + refresh)."""
+        auth = self.config.authentication
+        try:
+            from datacosmos.auth.local_token_fetcher import LocalTokenFetcher
+
+            fetcher = LocalTokenFetcher(
+                client_id=auth.client_id,
+                authorization_endpoint=auth.authorization_endpoint,
+                token_endpoint=auth.token_endpoint,
+                redirect_port=int(auth.redirect_port),
+                audience=auth.audience,
+                scopes=auth.scopes,
+                token_file=Path(auth.cache_file).expanduser(),
+            )
+            tok = fetcher.get_token()
+        except Exception as e:
+            raise DatacosmosException(f"Local authentication failed: {e}") from e
+
+        self.token = tok.access_token
+        self.token_expiry = datetime.fromtimestamp(tok.expires_at, tz=timezone.utc)
+
+        http_client = requests.Session()
+        http_client.headers.update({"Authorization": f"Bearer {self.token}"})
+
+        # keep for potential reuse in refresh path (optional)
+        self._local_token_fetcher = fetcher
+        return http_client
+
+    # --------------------------- request API ---------------------------
 
     def request(
         self, method: str, url: str, *args: Any, **kwargs: Any

{datacosmos-0.0.12.dist-info → datacosmos-0.0.13.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datacosmos
-Version: 0.0.12
+Version: 0.0.13
 Summary: A library for interacting with DataCosmos from Python code
 Author-email: Open Cosmos <support@open-cosmos.com>
 Classifier: Programming Language :: Python :: 3
@@ -20,6 +20,7 @@ Requires-Dist: black==22.3.0; extra == "dev"
 Requires-Dist: ruff==0.9.5; extra == "dev"
 Requires-Dist: pytest==7.2.0; extra == "dev"
 Requires-Dist: bandit[toml]==1.7.4; extra == "dev"
+Requires-Dist: pbr>=6.0.0; extra == "dev"
 Requires-Dist: isort==5.11.4; extra == "dev"
 Requires-Dist: pydocstyle==6.1.1; extra == "dev"
 Dynamic: license-file

{datacosmos-0.0.12.dist-info → datacosmos-0.0.13.dist-info}/RECORD

@@ -1,11 +1,18 @@
 datacosmos/__init__.py,sha256=dVHKpbz5FVtfoJAWHRdsUENG6H-vs4UrkuwnIvOGJr4,66
-datacosmos/datacosmos_client.py,sha256=3BurTz1fPk1Dzp8B5xt5gZZrFiqk1AT5oaqKeYmXPec,6517
+datacosmos/datacosmos_client.py,sha256=qbKAzym-84ihLO9WiUgw15QbAEplxPmLc4BMUBtNoEg,10191
+datacosmos/auth/__init__.py,sha256=ynCThS9QyLKV9miRdnjm8uF_breiGGiCcI0FaOSw_2o,45
+datacosmos/auth/local_token_fetcher.py,sha256=E4MI2lTRHAmxIQA7qY6hmpAUZETTzXNO8MViBaXnxGs,5268
+datacosmos/auth/token.py,sha256=neSV9gnnFa-rxEwMAJlZe_cReV6g4PQf8mq4-1mZzB8,2558
 datacosmos/config/__init__.py,sha256=KCsaTb9-ZgFui1GM8wZFIPLJy0D0O8l8Z1Sv3NRD9UM,140
-datacosmos/config/config.py,sha256=3iet6ou0vrcreaJjIFn0s59fyXHnolf026r1qe9PEvY,8487
+datacosmos/config/config.py,sha256=JHWmS6Q_T32iMly7cvJncjPCvtIgamBigKJJcvjGH7g,3465
+datacosmos/config/constants.py,sha256=HztzJ0OCti20uMXPQGvCFf_M4Vz1xRdxD2_2k9mAThs,855
+datacosmos/config/auth/__init__.py,sha256=jsqJQby3tyugcGtY7BoDKvv5qotkAomPc2uOELUlKtE,51
+datacosmos/config/auth/factory.py,sha256=svkL58xfqZ2ubcqQGZq9llb4RH-zkwrMPgBDD1Wk3Js,6213
+datacosmos/config/loaders/yaml_source.py,sha256=GY3RZvIjFJagTPiPmOhmFRa8aD0p0rZtTXgywU28fxo,2281
 datacosmos/config/models/__init__.py,sha256=r3lThPkyKjBjUZXRNscFzOrmn_-m_i9DvG3RePfCFYc,41
 datacosmos/config/models/authentication_config.py,sha256=01Q90-yupbJ5orYDtatZIm9EaL7roQ-oUMoZfFMRzIM,499
-datacosmos/config/models/local_user_account_authentication_config.py,sha256=8WApn720MBXMKQa6w7bCd7Z37GRmYR-I7mBUgUI20lQ,701
-datacosmos/config/models/m2m_authentication_config.py,sha256=n76N4bakpPPycTOeKpiM8pazYtNqiJGMzZXmI_ogbHM,847
+datacosmos/config/models/local_user_account_authentication_config.py,sha256=SJZRmrOm1nILHN9b-yyMN0vrhhHVYO81W-MUHvfUxJ0,971
+datacosmos/config/models/m2m_authentication_config.py,sha256=4l3Mmgips73rYGX5l7FCoHAWpWSGQYYkzZYvQzbmRz0,782
 datacosmos/config/models/no_authentication_config.py,sha256=x5xikSGPuqQbrf_S2oIWXo5XxAORci2sSE5KyJvZHVw,312
 datacosmos/config/models/url.py,sha256=bBeulXQ2c-tLJyIoo3sTi9SPsZIyIDn_D2zmkCGWp9s,1597
 datacosmos/exceptions/__init__.py,sha256=Crz8W7mOvPUXYcfDVotvjUt_3HKawBpmJA_-uel9UJk,45
@@ -44,8 +51,8 @@ datacosmos/utils/http_response/check_api_response.py,sha256=dKWW01jn2_lWV0xpOBAB
 datacosmos/utils/http_response/models/__init__.py,sha256=Wj8YT6dqw7rAz_rctllxo5Or_vv8DwopvQvBzwCTvpw,45
 datacosmos/utils/http_response/models/datacosmos_error.py,sha256=Uqi2uM98nJPeCbM7zngV6vHSk97jEAb_nkdDEeUjiQM,740
 datacosmos/utils/http_response/models/datacosmos_response.py,sha256=oV4n-sue7K1wwiIQeHpxdNU8vxeqF3okVPE2rydw5W0,336
-datacosmos-0.0.12.dist-info/licenses/LICENSE.md,sha256=vpbRI-UUbZVQfr3VG_CXt9HpRnL1b5kt8uTVbirxeyI,1486
-datacosmos-0.0.12.dist-info/METADATA,sha256=HvFc03wc5mu0XRmfl5Xw7iP8qxyC7Cmz-VFXQJjxQuo,897
-datacosmos-0.0.12.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-datacosmos-0.0.12.dist-info/top_level.txt,sha256=ueobs5CNeyDbPMgXPcVV0d0yNdm8CvGtDT3CaksRVtA,11
-datacosmos-0.0.12.dist-info/RECORD,,
+datacosmos-0.0.13.dist-info/licenses/LICENSE.md,sha256=vpbRI-UUbZVQfr3VG_CXt9HpRnL1b5kt8uTVbirxeyI,1486
+datacosmos-0.0.13.dist-info/METADATA,sha256=8SZ4fh8VHOt8UXkmbu9WnDUX75CEyMdxm777mMZ_0vo,939
+datacosmos-0.0.13.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+datacosmos-0.0.13.dist-info/top_level.txt,sha256=ueobs5CNeyDbPMgXPcVV0d0yNdm8CvGtDT3CaksRVtA,11
+datacosmos-0.0.13.dist-info/RECORD,,