earthscope-sdk 0.2.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

earthscope_sdk/common/service.py

@@ -0,0 +1,59 @@
+from typing import TYPE_CHECKING
+
+from earthscope_sdk.auth.error import UnauthenticatedError, UnauthorizedError
+
+if TYPE_CHECKING:
+    from httpx import Request
+
+    from earthscope_sdk.common.context import SdkContext
+
+
+class SdkService:
+    """
+    Base class for EarthScope SDK services
+    """
+
+    @property
+    def ctx(self):
+        """
+        SDK Context
+        """
+        return self._ctx
+
+    @property
+    def resources(self):
+        """
+        References to EarthScope resources
+        """
+        return self.ctx.settings.resources
+
+    def __init__(self, ctx: "SdkContext"):
+        self._ctx = ctx
+
+    async def _send(self, request: "Request"):
+        """
+        Send an HTTP request.
+
+        Performs common response handling.
+        """
+        resp = await self.ctx.httpx_client.send(request=request)
+
+        # Throw specific errors for certain status codes
+
+        if resp.status_code == 401:
+            await resp.aread()  # must read body before using .text prop
+            raise UnauthenticatedError(resp.text)
+
+        if resp.status_code == 403:
+            await resp.aread()  # must read body before using .text prop
+            raise UnauthorizedError(resp.text)
+
+        # Raise HTTP errors
+        resp.raise_for_status()
+
+        return resp
+
+    async def _send_with_retries(self, request: "Request"):
+        async for attempt in self.ctx.settings.http.retry.retry_context():
+            with attempt:
+                return await self._send(request=request)

earthscope_sdk/config/_bootstrap.py

@@ -0,0 +1,42 @@
+"""
+This module facilitates bootstrapping SDK settings from a JSON-encoded environment variable.
+"""
+
+import json
+import logging
+import os
+
+from pydantic_settings import PydanticBaseSettingsSource
+
+logger = logging.getLogger(__name__)
+
+
+class BootstrapEnvironmentSettingsSource(PydanticBaseSettingsSource):
+    """
+    This SettingsSource facilitates bootstrapping the SDK from a special environment variable.
+
+    The environment variable should be a JSON string of the expected SDK settings and structure.
+    """
+
+    def __init__(self, settings_cls, env_var: str):
+        super().__init__(settings_cls)
+        self._env_var = env_var
+
+    def __call__(self):
+        try:
+            bootstrap_settings = os.environ[self._env_var]
+        except KeyError:
+            return {}
+
+        try:
+            return json.loads(bootstrap_settings)
+        except json.JSONDecodeError:
+            logger.warning(
+                f"Found bootstrap environment variable '{self._env_var}', but unable to decode content as JSON"
+            )
+            return {}
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(env_var='{self._env_var}')"
+
+    def get_field_value(self, *args, **kwargs): ...  # unused abstract method

earthscope_sdk/config/_compat.py

@@ -0,0 +1,148 @@
+"""
+This module facilitates compatibility with EarthScope CLI v0.x.x
+"""
+
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Union
+
+from pydantic_settings import PydanticBaseSettingsSource
+
+logger = logging.getLogger(__name__)
+
+####
+# The following code is nearly verbatim from Click's source (which is what Typer uses underneath)
+# https://github.com/pallets/click/blob/main/src/click/utils.py.
+#
+# The various functions and consts have been renamed to be "private"
+#
+# Click's get_app_dir() was used to determine the "application directory" in earthscope-cli v0.x.x.
+# whereas this has moved to ~/.earthscope/ starting in 1.0.0
+#
+# We replicate this functionality here so that the SDK does not need a dependency on Click.
+####
+
+_WIN = sys.platform.startswith("win")
+
+
+def _posixify(name: str) -> str:
+    return "-".join(name.split()).lower()
+
+
+def _get_legacy_app_dir(
+    app_name: str,
+    roaming: bool = True,
+    force_posix: bool = False,
+) -> str:
+    r"""Returns the config folder for the application.  The default behavior
+    is to return whatever is most appropriate for the operating system.
+
+    To give you an idea, for an app called ``"Foo Bar"``, something like
+    the following folders could be returned:
+
+    Mac OS X:
+      ``~/Library/Application Support/Foo Bar``
+    Mac OS X (POSIX):
+      ``~/.foo-bar``
+    Unix:
+      ``~/.config/foo-bar``
+    Unix (POSIX):
+      ``~/.foo-bar``
+    Windows (roaming):
+      ``C:\Users\<user>\AppData\Roaming\Foo Bar``
+    Windows (not roaming):
+      ``C:\Users\<user>\AppData\Local\Foo Bar``
+
+    .. versionadded:: 2.0
+
+    :param app_name: the application name.  This should be properly capitalized
+                     and can contain whitespace.
+    :param roaming: controls if the folder should be roaming or not on Windows.
+                    Has no effect otherwise.
+    :param force_posix: if this is set to `True` then on any POSIX system the
+                        folder will be stored in the home folder with a leading
+                        dot instead of the XDG config home or darwin's
+                        application support folder.
+    """
+    if _WIN:
+        key = "APPDATA" if roaming else "LOCALAPPDATA"
+        folder = os.environ.get(key)
+        if folder is None:
+            folder = os.path.expanduser("~")
+        return os.path.join(folder, app_name)
+    if force_posix:
+        return os.path.join(os.path.expanduser(f"~/.{_posixify(app_name)}"))
+    if sys.platform == "darwin":
+        return os.path.join(
+            os.path.expanduser("~/Library/Application Support"), app_name
+        )
+    return os.path.join(
+        os.environ.get("XDG_CONFIG_HOME", os.path.expanduser("~/.config")),
+        _posixify(app_name),
+    )
+
+
+####
+# end of Click code
+####
+
+# Legacy state was just the exact response body from Auth0 e.g.
+# {
+#   "access_token": "<TOKEN>",
+#   "id_token": "<TOKEN>",
+#   "refresh_token": "<TOKEN>",
+#   "scope": "openid profile email offline_access",
+#   "expires_at": 1734742981,
+#   "issued_at": 1734714181
+# }
+
+# the following is how the local app directory was determined in v0.x.x
+_LEGACY_APP_DIR = Path(
+    os.environ.get("APP_DIRECTORY", _get_legacy_app_dir("earthscope-cli"))
+)
+
+
+def _get_legacy_auth_state_path():
+    return _LEGACY_APP_DIR / "sso_tokens.json"
+
+
+class LegacyEarthScopeCLISettingsSource(PydanticBaseSettingsSource):
+    """
+    This SettingsSource facilitates migrating earthscope-cli v0.x.x local state into
+    earthscope-sdk v1.x.x state
+    """
+
+    def __init__(self, settings_cls, *keys: str):
+        super().__init__(settings_cls)
+        self._keys = keys
+
+    def __call__(self):
+        # load path dynamically so we can override in tests
+        state_path = _get_legacy_auth_state_path()
+
+        # attempt to load from legacy sso_tokens.json
+        try:
+            with state_path.open() as f:
+                state: dict[str, Union[str, int]] = json.load(f)
+
+        # In either error case, just return an empty
+        except json.JSONDecodeError:
+            logger.warning(
+                f"Found legacy earthscope-cli state at '{state_path}', but unable to decode content as JSON"
+            )
+            return {}
+
+        except FileNotFoundError:
+            return {}
+
+        # only preserve specific keys if non-null
+        settings = {k: v for k in self._keys if (v := state.get(k)) is not None}
+        return {"oauth2": settings}
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}()"
+
+    def get_field_value(self, *args, **kwargs): ...  # unused abstract method

earthscope_sdk/config/_util.py

@@ -0,0 +1,48 @@
+import pathlib
+from functools import reduce
+
+
+def _merge(a: dict, b: dict):
+    for key in b:
+        if key in a:
+            if isinstance(a[key], dict) and isinstance(b[key], dict):
+                _merge(a[key], b[key])
+                continue
+
+        a[key] = b[key]
+
+    return a
+
+
+def deep_merge(*mappings: dict, **kwargs):
+    """
+    Merge all of the dictionaries provided, reursing into nested dictionaries.
+
+    Behavior:
+    - The precedence increases from left to right, with keyword arguments as the highest precedence.
+    - The leftmost dictionary is modified in-place. Pass an empty dictionary first to avoid modification of inputs.
+    """
+    return reduce(_merge, (*mappings, kwargs))
+
+
+def get_config_dir(app_name: str):
+    r"""
+    Returns the hidden config folder in the user's home directory for the application.
+
+    Mac OS X:
+        `~/.app-name`
+    Unix:
+        `~/.app-name`
+    Windows:
+        `C:\Users\<user>\.app-name`
+    """
+    app_slug = slugify(app_name)
+    config_dir = pathlib.Path.home() / f".{app_slug}"
+    return config_dir
+
+
+def slugify(name: str) -> str:
+    """
+    Convert the given name into a slug which can be used more easily in file names
+    """
+    return "-".join(name.split()).lower()

earthscope_sdk/config/error.py

@@ -0,0 +1,4 @@
+class ProfileDoesNotExistError(KeyError):
+    """
+    The named profile does not exist
+    """

earthscope_sdk/config/models.py

@@ -0,0 +1,310 @@
+import base64
+import binascii
+import datetime as dt
+import fnmatch
+import functools
+from contextlib import suppress
+from enum import Enum
+from functools import cached_property
+from typing import Annotated, Any, Optional, Type, Union
+
+from annotated_types import Ge, Gt
+from pydantic import (
+    AliasChoices,
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    Field,
+    HttpUrl,
+    ValidationError,
+    model_validator,
+)
+
+from earthscope_sdk import __version__
+from earthscope_sdk.model.secret import SecretStr
+
+
+def _try_float(v: Any):
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return v
+
+
+Timedelta = Annotated[dt.timedelta, BeforeValidator(_try_float)]
+
+
+class AccessTokenBody(BaseModel):
+    """
+    Access token payload
+
+    [See Auth0 docs](https://auth0.com/docs/secure/tokens/access-tokens/access-token-profiles)
+    """
+
+    audience: Annotated[Union[str, list[str]], Field(alias="aud")]
+    issuer: Annotated[str, Field(alias="iss")]
+    issued_at: Annotated[dt.datetime, Field(alias="iat")]
+    expires_at: Annotated[dt.datetime, Field(alias="exp")]
+    scope: Annotated[str, Field(alias="scope")] = ""
+    subject: Annotated[str, Field(alias="sub")]
+    grant_type: Annotated[Optional[str], Field(alias="gty")] = None
+    token_id: Annotated[Optional[str], Field(alias="jti")] = None
+    client_id: Annotated[
+        str,
+        Field(
+            validation_alias=AliasChoices("client_id", "azp"),
+            serialization_alias="client_id",
+        ),
+    ]
+
+    @cached_property
+    def ttl(self) -> dt.timedelta:
+        """time to live (TTL) until expiration"""
+        return self.expires_at - dt.datetime.now(dt.timezone.utc)
+
+    model_config = ConfigDict(extra="allow", frozen=True, populate_by_name=True)
+
+
+class AuthFlowType(Enum):
+    DeviceCode = "device_code"
+    MachineToMachine = "m2m"
+
+
+class Tokens(BaseModel):
+    """
+    EarthScope SDK oauth2 tokens
+    """
+
+    access_token: Optional[SecretStr] = None
+    id_token: Optional[SecretStr] = None
+    refresh_token: Optional[SecretStr] = None
+
+    model_config = ConfigDict(frozen=True)
+
+    @cached_property
+    def access_token_body(self):
+        if self.access_token is None:
+            return None
+
+        with suppress(IndexError, binascii.Error, ValidationError):
+            payload_b64 = self.access_token.get_secret_value().split(".", 2)[1]
+            payload = base64.b64decode(payload_b64 + "==")  # extra padding
+            return AccessTokenBody.model_validate_json(payload)
+
+        raise ValueError("Unable to decode access token body")
+
+    @model_validator(mode="after")
+    def ensure_one_of(self):
+        # allow all fields to be optional in subclasses
+        if self.__class__ != Tokens:
+            return self
+
+        if self.access_token or self.refresh_token:
+            return self
+
+        raise ValueError("At least one of access token and refresh token is required.")
+
+
+class RetrySettings(BaseModel):
+    """
+    Retry configuration for the [Stamina library](https://stamina.hynek.me/en/stable/index.html)
+    """
+
+    # same defaults as AWS SDK "standard" mode:
+    # https://boto3.amazonaws.com/v1/documentation/api/latest/guide/retries.html#standard-retry-mode
+
+    attempts: Annotated[int, Ge(0)] = 3
+    timeout: Timedelta = dt.timedelta(seconds=20)
+
+    wait_initial: Timedelta = dt.timedelta(milliseconds=100)
+    wait_max: Timedelta = dt.timedelta(seconds=5)
+    wait_jitter: Timedelta = dt.timedelta(seconds=1)
+    wait_exp_base: Annotated[float, Gt(0)] = 2
+
+    async def retry_context(self, *retry_exc: Type[Exception]):
+        """
+        Obtain a [Stamina](https://stamina.hynek.me/en/stable/index.html) retry iterator.
+        """
+        from stamina import retry_context
+
+        retry_on = functools.partial(self.is_retriable, retry_exc=retry_exc)
+
+        ctx = retry_context(
+            on=retry_on,
+            attempts=self.attempts,
+            timeout=self.timeout,
+            wait_initial=self.wait_initial,
+            wait_jitter=self.wait_jitter,
+            wait_max=self.wait_max,
+            wait_exp_base=self.wait_exp_base,
+        )
+        async for attempt in ctx:
+            yield attempt
+
+    def is_retriable(
+        self,
+        exc: Exception,
+        *args,
+        retry_exc: tuple[Type[Exception]] = (),
+        **kwargs,
+    ) -> bool:
+        """
+        Check if the given exception can be retried
+        """
+        if retry_exc and isinstance(exc, retry_exc):
+            return True
+
+        return False
+
+
+class HttpRetrySettings(RetrySettings):
+    status_codes: set[int] = {429, 500, 502, 503, 504}
+
+    def is_retriable(
+        self,
+        exc: Exception,
+        *args,
+        **kwargs,
+    ) -> bool:
+        from httpx import HTTPStatusError
+
+        if isinstance(exc, HTTPStatusError):
+            if exc.response.status_code in self.status_codes:
+                return True
+
+        return super().is_retriable(exc, *args, **kwargs)
+
+
+class AuthFlowSettings(Tokens):
+    """
+    Auth flow configuration
+
+    Not for direct use.
+    """
+
+    # Auth parameters
+    audience: str = "https://api.earthscope.org"
+    domain: HttpUrl = HttpUrl("https://login.earthscope.org")
+    client_id: str = "b9DtAFBd6QvMg761vI3YhYquNZbJX5G0"
+    scope: str = "offline_access"
+    client_secret: Optional[SecretStr] = None
+
+    # Only inject bearer token for requests to these hosts
+    allowed_hosts: set[str] = {
+        "earthscope.org",
+        "*.earthscope.org",
+    }
+
+    # Auth exchange retries
+    retry: HttpRetrySettings = HttpRetrySettings(
+        attempts=5,
+        timeout=dt.timedelta(seconds=30),
+        wait_initial=dt.timedelta(seconds=1),
+        wait_jitter=dt.timedelta(seconds=3),
+    )
+
+    @cached_property
+    def auth_flow_type(self) -> AuthFlowType:
+        if self.client_secret is not None:
+            return AuthFlowType.MachineToMachine
+
+        return AuthFlowType.DeviceCode
+
+    @cached_property
+    def allowed_host_patterns(self) -> set[str]:
+        """
+        The subset of allowed hosts that are glob patterns.
+
+        Use `is_host_allowed` to check if a host is allowed by any of these patterns.
+        """
+        return {h for h in self.allowed_hosts if "*" in h or "?" in h}
+
+    def is_host_allowed(self, host: str) -> bool:
+        """
+        Check if a host matches any pattern in the allowed hosts set.
+
+        Supports glob patterns with '?' and '*' characters (e.g., *.earthscope.org).
+
+        Args:
+            host: The hostname to check
+
+        Returns:
+            True if the host matches any allowed pattern, False otherwise
+        """
+        if host in self.allowed_hosts:
+            return True
+
+        for allowed_pattern in self.allowed_host_patterns:
+            if fnmatch.fnmatch(host, allowed_pattern):
+                self.allowed_hosts.add(host)
+                return True
+
+        return False
+
+
+class HttpSettings(BaseModel):
+    """
+    HTTP client configuration
+    """
+
+    # httpx limits
+    keepalive_expiry: Timedelta = dt.timedelta(seconds=5)
+    max_connections: Optional[int] = None
+    max_keepalive_connections: Optional[int] = None
+
+    # httpx timeouts
+    timeout_connect: Timedelta = dt.timedelta(seconds=5)
+    timeout_read: Timedelta = dt.timedelta(seconds=5)
+
+    # automatically retry requests
+    retry: HttpRetrySettings = HttpRetrySettings()
+
+    # Other
+    user_agent: str = f"earthscope-sdk py/{__version__}"
+
+    @cached_property
+    def limits(self):
+        """httpx Limits on client connection pool"""
+        # lazy import
+        import httpx
+
+        return httpx.Limits(
+            max_connections=self.max_connections,
+            max_keepalive_connections=self.max_keepalive_connections,
+            keepalive_expiry=self.keepalive_expiry.total_seconds(),
+        )
+
+    @cached_property
+    def timeouts(self):
+        """httpx Timeouts default behavior"""
+        # lazy import
+        import httpx
+
+        return httpx.Timeout(
+            connect=self.timeout_connect.total_seconds(),
+            # reuse read timeout for others
+            read=self.timeout_read.total_seconds(),
+            write=self.timeout_read.total_seconds(),
+            pool=self.timeout_read.total_seconds(),
+        )
+
+
+class ResourceRefs(BaseModel):
+    """
+    References to EarthScope resources
+    """
+
+    api_url: HttpUrl = HttpUrl("https://api.earthscope.org")
+    """Base URL for api.earthscope.org"""
+
+
+class SdkBaseSettings(BaseModel):
+    """
+    Common base class for SDK settings
+
+    Not for direct use.
+    """
+
+    http: HttpSettings = HttpSettings()
+    oauth2: AuthFlowSettings = AuthFlowSettings()
+    resources: ResourceRefs = ResourceRefs()