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

earthscope_sdk/auth/error.py

@@ -0,0 +1,46 @@
+class AuthFlowError(Exception):
+    """Generic authentication flow error"""
+
+
+class UnauthenticatedError(AuthFlowError):
+    pass
+
+
+class UnauthorizedError(AuthFlowError):
+    pass
+
+
+class NoTokensError(AuthFlowError):
+    pass
+
+
+class NoAccessTokenError(NoTokensError):
+    pass
+
+
+class NoIdTokenError(NoTokensError):
+    pass
+
+
+class NoRefreshTokenError(NoTokensError):
+    pass
+
+
+class InvalidRefreshTokenError(AuthFlowError):
+    pass
+
+
+class ClientCredentialsFlowError(AuthFlowError):
+    pass
+
+
+class DeviceCodeRequestDeviceCodeError(AuthFlowError):
+    pass
+
+
+class DeviceCodePollingError(AuthFlowError):
+    pass
+
+
+class DeviceCodePollingExpiredError(DeviceCodePollingError):
+    pass

earthscope_sdk/client/__init__.py

@@ -0,0 +1,3 @@
+from earthscope_sdk.client._client import AsyncEarthScopeClient, EarthScopeClient
+
+__all__ = ["EarthScopeClient", "AsyncEarthScopeClient"]

earthscope_sdk/client/_client.py

@@ -0,0 +1,35 @@
+from functools import cached_property
+
+from earthscope_sdk.common.client import AsyncSdkClient, SdkClient
+
+
+class AsyncEarthScopeClient(AsyncSdkClient):
+    """
+    An async client for interacting with api.earthscope.org
+    """
+
+    @cached_property
+    def user(self):
+        """
+        User and Identity Management functionality
+        """
+        # lazy load
+        from earthscope_sdk.client.user._service import AsyncUserService
+
+        return AsyncUserService(self._ctx)
+
+
+class EarthScopeClient(SdkClient):
+    """
+    A client for interacting with api.earthscope.org
+    """
+
+    @cached_property
+    def user(self):
+        """
+        User and Identity Management functionality
+        """
+        # lazy load
+        from earthscope_sdk.client.user._service import UserService
+
+        return UserService(self._ctx)

earthscope_sdk/client/user/_base.py

@@ -0,0 +1,39 @@
+from earthscope_sdk.common.service import SdkService
+
+
+class UserBaseService(SdkService):
+    """
+    L1 user/IDM endpoints
+    """
+
+    async def _get_aws_credentials(self, *, role: str = "s3-miniseed"):
+        """
+        Retrieve temporary AWS credentials
+        """
+
+        from earthscope_sdk.client.user.models import AwsTemporaryCredentials
+
+        req = self.ctx.httpx_client.build_request(
+            method="GET",
+            url=f"{self.resources.api_url}beta/user/credentials/aws/{role}",
+        )
+
+        resp = await self._send_with_retries(req)
+
+        return AwsTemporaryCredentials.model_validate_json(resp.content)
+
+    async def _get_profile(self):
+        """
+        Retrieve your EarthScope user profile
+        """
+
+        from earthscope_sdk.client.user.models import UserProfile
+
+        req = self.ctx.httpx_client.build_request(
+            method="GET",
+            url=f"{self.resources.api_url}beta/user/profile",
+        )
+
+        resp = await self._send_with_retries(req)
+
+        return UserProfile.model_validate_json(resp.content)

earthscope_sdk/client/user/_service.py

@@ -0,0 +1,94 @@
+from contextlib import suppress
+from datetime import timedelta
+from typing import TYPE_CHECKING, Optional
+
+from earthscope_sdk.client.user._base import UserBaseService
+
+if TYPE_CHECKING:
+    from earthscope_sdk.client.user.models import AwsTemporaryCredentials
+    from earthscope_sdk.common.context import SdkContext
+
+
+class _UserService(UserBaseService):
+    """
+    L2 user/IDM service functionality
+    """
+
+    def __init__(self, ctx: "SdkContext"):
+        super().__init__(ctx)
+
+        self._aws_creds_by_role = dict[str, "AwsTemporaryCredentials"]()
+
+    async def _get_aws_credentials(
+        self,
+        *,
+        role: str = "s3-miniseed",
+        force=False,
+        ttl_threshold: Optional[timedelta] = None,
+    ):
+        """
+        Retrieve temporary AWS credentials.
+
+        Leverages a memory cache and disk cache in this profile's state directory
+        (`~/.earthscope/<profile_name>/aws.<role>.json`)
+
+        Args:
+            role: Alias of the role to assume. Defaults to `s3-miniseed`.
+            force: Ignore cache and fetch new credentials. Defaults to `False`.
+            ttl_threshold: Time-to-live remaining on cached credentials after which new credentials are fetched. Defaults to 30s.
+
+        Returns: Temporary AWS credentials for the selected role.
+        """
+        # lazy imports
+        from pydantic import ValidationError
+
+        from earthscope_sdk.client.user.models import AwsTemporaryCredentials
+
+        aws_creds_file_path = self.ctx.settings.profile_dir / f"aws.{role}.json"
+
+        if not force:
+            # Check memory cache
+            if aws_creds := self._aws_creds_by_role.get(role):
+                if not aws_creds.is_expired(ttl_threshold):
+                    return aws_creds
+
+            # Check disk cache
+            with suppress(FileNotFoundError, ValidationError):
+                aws_creds_bytes = aws_creds_file_path.read_bytes()
+                aws_creds = AwsTemporaryCredentials.model_validate_json(aws_creds_bytes)
+                if not aws_creds.is_expired(ttl_threshold):
+                    return aws_creds
+
+        # Get new AWS creds
+        # NOTE: this method will implicitly refresh our access token if necessary
+        aws_creds = await super()._get_aws_credentials(role=role)
+
+        # persist in memory and on disk
+        self._aws_creds_by_role[role] = aws_creds
+        aws_creds_file_path.write_bytes(aws_creds.model_dump_json().encode())
+
+        return aws_creds
+
+
+class AsyncUserService(_UserService):
+    """
+    User and Identity Management functionality
+    """
+
+    def __init__(self, ctx: "SdkContext"):
+        super().__init__(ctx)
+
+        self.get_aws_credentials = self._get_aws_credentials
+        self.get_profile = self._get_profile
+
+
+class UserService(_UserService):
+    """
+    User and Identity Management functionality
+    """
+
+    def __init__(self, ctx: "SdkContext"):
+        super().__init__(ctx)
+
+        self.get_aws_credentials = ctx.syncify(self._get_aws_credentials)
+        self.get_profile = ctx.syncify(self._get_profile)

earthscope_sdk/client/user/models.py

@@ -0,0 +1,53 @@
+import datetime as dt
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class UserProfile(BaseModel):
+    """
+    EarthScope user profile
+    """
+
+    first_name: str
+    last_name: str
+    country_code: str
+    region_code: Optional[str]
+    institution: str
+    work_sector: str
+    user_id: str
+    primary_email: str
+    created_at: dt.datetime
+    updated_at: dt.datetime
+
+
+class AwsTemporaryCredentials(BaseModel):
+    """
+    AWS temporary credentials
+    """
+
+    aws_access_key_id: str
+    aws_secret_access_key: str
+    aws_session_token: str
+    expiration: dt.datetime
+
+    model_config = ConfigDict(frozen=True)
+
+    @property
+    def ttl(self):
+        """
+        Time to live
+        """
+        return self.expiration - dt.datetime.now(dt.timezone.utc)
+
+    def is_expired(self, ttl_threshold: Optional[dt.timedelta] = None):
+        """
+        Check if these credentials are past or near expiration
+
+        Args:
+            ttl_threshold: remaining time-to-live before considering the temporary AWS creds expired (Default: 30s)
+        """
+        if ttl_threshold is None:
+            ttl_threshold = dt.timedelta(seconds=30)
+
+        return self.ttl <= ttl_threshold

earthscope_sdk/common/_sync_runner.py

@@ -0,0 +1,141 @@
+import abc
+import asyncio
+import functools
+import sys
+from typing import Any, Callable, Coroutine, TypeVar
+
+if sys.version_info >= (3, 10):
+    from typing import ParamSpec
+else:
+    from typing_extensions import ParamSpec
+
+T_Retval = TypeVar("T_Retval")
+T_ParamSpec = ParamSpec("T_ParamSpec")
+
+
+class SyncRunner(abc.ABC):
+    """
+    Facilitates running async functions in a synchronous manner
+    """
+
+    @property
+    def is_closed(self) -> bool:
+        """
+        The async runner is closed and no more synchronous invocations may occur.
+        """
+        return False
+
+    @abc.abstractmethod
+    def stop(self):
+        """
+        Stop the async runner (i.e. clean up any allocated resources).
+
+        Methods created via `.syncify()` may not work after stopping this runner.
+        """
+
+    @abc.abstractmethod
+    def syncify(
+        self,
+        async_function: Callable[T_ParamSpec, Coroutine[Any, Any, T_Retval]],
+    ) -> Callable[T_ParamSpec, T_Retval]:
+        """
+        Create a synchronous version of an async function
+        """
+
+
+class SimpleSyncRunner(SyncRunner):
+    """
+    Runs async functions in a dedicated event loop in the same thread as the caller.
+
+    This is a simple light-weight option, but does not work when an EventLoop already
+    exists in the calling thread.
+    """
+
+    def __init__(self):
+        self._loop = asyncio.new_event_loop()
+
+    @property
+    def is_closed(self):
+        return self._loop.is_closed()
+
+    def stop(self):
+        # implements abstract method
+        self._loop.stop()
+        self._loop.close()
+
+    def syncify(
+        self,
+        async_function: Callable[T_ParamSpec, Coroutine[Any, Any, T_Retval]],
+    ) -> Callable[T_ParamSpec, T_Retval]:
+        # implements abstract method
+
+        @functools.wraps(async_function)
+        def wrapper(*args: T_ParamSpec.args, **kwargs: T_ParamSpec.kwargs) -> T_Retval:
+            partial_f = functools.partial(async_function, *args, **kwargs)
+
+            # run_until_complete() only runs the event loop until partial_f() has finished.
+            # - The loop does not continue running in the background.
+            # - This method will throw a RuntimeError if there is already an event loop
+            #   running in the calling thread.
+            return self._loop.run_until_complete(partial_f())
+
+        return wrapper
+
+
+class BackgroundSyncRunner(SyncRunner):
+    """
+    Runs async functions in a dedicated event loop in a background thread.
+
+    This has the overhead of spawning a dedicated daemon thread.
+    """
+
+    def __init__(self):
+        # lazy import
+        import threading
+
+        self._lock = threading.Lock()
+        self._loop = asyncio.new_event_loop()
+        self._running = False
+        self._thread = threading.Thread(target=self._run_loop, daemon=True)
+
+    @property
+    def is_closed(self):
+        return self._loop.is_closed() and not self._thread.is_alive()
+
+    def start(self):
+        with self._lock:
+            if not self._thread.is_alive():
+                self._thread.start()
+
+    def stop(self):
+        # implements abstract method
+        with self._lock:
+            if self._running:
+                self._loop.call_soon_threadsafe(self._loop.stop)
+                self._thread.join()
+
+    def syncify(
+        self,
+        async_function: Callable[T_ParamSpec, Coroutine[Any, Any, T_Retval]],
+    ) -> Callable[T_ParamSpec, T_Retval]:
+        # implements abstract method
+
+        # start the thread (if necessary) for running sync functions created here
+        self.start()
+
+        @functools.wraps(async_function)
+        def wrapper(*args: T_ParamSpec.args, **kwargs: T_ParamSpec.kwargs) -> T_Retval:
+            partial_f = functools.partial(async_function, *args, **kwargs)
+            fut = asyncio.run_coroutine_threadsafe(partial_f(), self._loop)
+            return fut.result()
+
+        return wrapper
+
+    def _run_loop(self):
+        asyncio.set_event_loop(self._loop)
+        self._running = True
+        try:
+            self._loop.run_forever()
+        finally:
+            self._loop.close()
+            self._running = False

earthscope_sdk/common/client.py

@@ -0,0 +1,99 @@
+from typing import TYPE_CHECKING, Optional, overload
+
+if TYPE_CHECKING:
+    from earthscope_sdk.common.context import SdkContext
+    from earthscope_sdk.config.settings import SdkSettings
+
+
+class _SdkClient:
+    @property
+    def ctx(self):
+        """
+        SDK Context
+        """
+        return self._ctx
+
+    @property
+    def is_closed(self):
+        """
+        This client is closed
+        """
+        return self._ctx.is_closed
+
+    @property
+    def resources(self):
+        """
+        References to EarthScope resources
+        """
+        return self.ctx.settings.resources
+
+    @overload
+    def __init__(self): ...
+
+    @overload
+    def __init__(self, *, ctx: "SdkContext"): ...
+
+    @overload
+    def __init__(self, *, settings: "SdkSettings"): ...
+
+    def __init__(
+        self,
+        *,
+        ctx: Optional["SdkContext"] = None,
+        settings: Optional["SdkSettings"] = None,
+    ):
+        # lazy imports
+        from earthscope_sdk.common.context import SdkContext
+        from earthscope_sdk.config.settings import SdkSettings
+
+        if ctx:
+            self._created_ctx = False
+
+        else:
+            if settings is None:
+                settings = SdkSettings()
+
+            ctx = SdkContext(settings=settings)
+            self._created_ctx = True
+
+        self._ctx = ctx
+
+
+class AsyncSdkClient(_SdkClient):
+    """
+    Base class for asynchronous EarthScope SDK clients
+    """
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_t, exc_v, exc_tb):
+        await self.close()
+
+    async def close(self):
+        """
+        Close this client
+        """
+        # only close the context if we created it
+        if self._created_ctx:
+            await self.ctx.async_close()
+
+
+class SdkClient(_SdkClient):
+    """
+    Base class for synchronous EarthScope SDK clients
+    """
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def close(self):
+        """
+        Close this client
+        """
+        # only close the context if we created it
+        if self._created_ctx:
+            self.ctx.close()

earthscope_sdk/common/context.py

@@ -0,0 +1,174 @@
+import sys
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, Callable, Coroutine, Optional, TypeVar, cast
+
+if sys.version_info >= (3, 10):
+    from typing import ParamSpec
+else:
+    from typing_extensions import ParamSpec
+
+
+if TYPE_CHECKING:
+    from httpx import AsyncClient
+
+    from earthscope_sdk.common._sync_runner import SyncRunner
+    from earthscope_sdk.config.settings import SdkSettings
+
+T_Retval = TypeVar("T_Retval")
+T_ParamSpec = ParamSpec("T_ParamSpec")
+
+
+class SdkContext:
+    """
+    Shared context for the EarthScope SDK
+    """
+
+    @cached_property
+    def auth_flow(self):
+        """
+        Reusable AuthFlow instance for managing token lifecycle
+        """
+        # lazy import; avoid circular dependency
+        from earthscope_sdk.auth.auth_flow import AuthFlow
+        from earthscope_sdk.config.models import AuthFlowType
+
+        auth_flow_type = self.settings.oauth2.auth_flow_type
+
+        if auth_flow_type == AuthFlowType.DeviceCode:
+            return cast(AuthFlow, self.device_code_flow)
+
+        if auth_flow_type == AuthFlowType.MachineToMachine:
+            return cast(AuthFlow, self.client_credentials_flow)
+
+        # Fall back to base auth flow; if a refresh token is present, we can still
+        # facilitate automated renewal.
+        return AuthFlow(ctx=self)
+
+    @cached_property
+    def client_credentials_flow(self):
+        """
+        Reusable ClientCredentialsFlow instance for managing token lifecycle
+        """
+        # lazy import; avoid circular dependency
+        from earthscope_sdk.auth.client_credentials_flow import ClientCredentialsFlow
+
+        return ClientCredentialsFlow(ctx=self)
+
+    @cached_property
+    def device_code_flow(self):
+        """
+        Resusable DeviceCodeFlow instance for managing token lifecycle
+        """
+        # lazy import; avoid circular dependency
+        from earthscope_sdk.auth.device_code_flow import DeviceCodeFlow
+
+        return DeviceCodeFlow(ctx=self)
+
+    @cached_property
+    def httpx_client(self):
+        """
+        Reusable HTTPx client for shared session and connection pooling.
+
+        Automatically:
+        - injects common headers (e.g. authorization, user-agent)
+            - refreshes access token automatically
+        """
+        import httpx  # lazy import
+
+        self._httpx_client = httpx.AsyncClient(
+            auth=self.auth_flow,
+            headers={
+                "user-agent": self.settings.http.user_agent,
+            },
+            limits=self.settings.http.limits,
+            timeout=self.settings.http.timeouts,
+        )
+
+        return self._httpx_client
+
+    @property
+    def is_closed(self):
+        if (c := self._httpx_client) and not c.is_closed:
+            return False
+
+        if (r := self._runner) and not r.is_closed:
+            return False
+
+        return True
+
+    @cached_property
+    def settings(self):
+        """
+        Profile-specific settings merged with any configured defaults
+        """
+        return self._settings
+
+    def __init__(
+        self,
+        settings: Optional["SdkSettings"] = None,
+        *,
+        runner: Optional["SyncRunner"] = None,
+    ):
+        # lazy import
+        from earthscope_sdk.config.settings import SdkSettings
+
+        # Local state
+        self._httpx_client: Optional["AsyncClient"] = None
+        self._runner: Optional["SyncRunner"] = runner
+        self._settings = settings or SdkSettings()
+
+    async def async_close(self):
+        """
+        Close this SdkContext to release underlying resources (e.g. connection pools)
+        """
+        if self._httpx_client:
+            await self._httpx_client.aclose()
+
+        if self._runner:
+            self._runner.stop()
+
+    def close(self):
+        """
+        Close this SdkContext to release underlying resources (e.g. connection pools)
+        """
+        # needs a different implementation than async_close()
+
+        # need to run aclose() in the event loop
+        if self._httpx_client:
+            self.syncify(self._httpx_client.aclose)()
+
+        # closing the event loop should be done *outside* the event loop *after* all async cleanup
+        if self._runner:
+            self._runner.stop()
+
+    def syncify(
+        self,
+        async_function: Callable[T_ParamSpec, Coroutine[Any, Any, T_Retval]],
+    ) -> Callable[T_ParamSpec, T_Retval]:
+        """
+        Create a synchronous version of an async function
+        """
+        if not self._runner:
+            self._runner = self._get_runner()
+
+        return self._runner.syncify(async_function)
+
+    def _get_runner(self) -> "SyncRunner":
+        # lazy imports
+        import asyncio
+
+        from earthscope_sdk.common._sync_runner import (
+            BackgroundSyncRunner,
+            SimpleSyncRunner,
+        )
+
+        try:
+            asyncio.get_running_loop()
+
+        except RuntimeError:
+            # No event loop exists in this thread; we can run in this thread
+            return SimpleSyncRunner()
+
+        else:
+            # An event loop already exists in this thread; create a background thread
+            return BackgroundSyncRunner()