earthscope-sdk 1.0.0b1__py3-none-any.whl → 1.1.0__py3-none-any.whl

earthscope_sdk/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.0.0b1"
+__version__ = "1.1.0"
 
 from earthscope_sdk.client import AsyncEarthScopeClient, EarthScopeClient
 

earthscope_sdk/auth/auth_flow.py

@@ -311,9 +311,10 @@ class AuthFlow(httpx.Auth):
         """
         super().async_auth_flow
         if request.headers.get("authorization") is None:
-            await self.async_refresh_if_necessary()
-            access_token = self.access_token
-            request.headers["authorization"] = f"Bearer {access_token}"
+            if self._settings.is_host_allowed(request.url.host):
+                await self.async_refresh_if_necessary()
+                access_token = self.access_token
+                request.headers["authorization"] = f"Bearer {access_token}"
 
         yield request
 
@@ -326,8 +327,9 @@ class AuthFlow(httpx.Auth):
         # NOTE: we explicitly redefine this sync method because ctx.syncify()
         # does not support generators
         if request.headers.get("authorization") is None:
-            self.refresh_if_necessary()
-            access_token = self.access_token
-            request.headers["authorization"] = f"Bearer {access_token}"
+            if self._settings.is_host_allowed(request.url.host):
+                self.refresh_if_necessary()
+                access_token = self.access_token
+                request.headers["authorization"] = f"Bearer {access_token}"
 
         yield request

earthscope_sdk/auth/client_credentials_flow.py

@@ -1,5 +1,4 @@
 import logging
-from dataclasses import dataclass
 from json import JSONDecodeError
 
 from earthscope_sdk.auth.auth_flow import AuthFlow
@@ -9,12 +8,6 @@ from earthscope_sdk.common.context import SdkContext
 logger = logging.getLogger(__name__)
 
 
-@dataclass
-class GetTokensErrorResponse:
-    error: str
-    error_description: str
-
-
 class ClientCredentialsFlow(AuthFlow):
     """
     Implements the oauth2 Client Credentials "machine-to-machine" (M2M) flow.
@@ -69,12 +62,9 @@ class ClientCredentialsFlow(AuthFlow):
 
         # Unauthorized
         if r.status_code == 401:
-            err = GetTokensErrorResponse(**resp)
-            if err.error == "access_denied":
-                if err.error_description == "Unauthorized":
-                    raise UnauthorizedError(
-                        f"m2m client '{self._settings.client_id}' is not authorized"
-                    )
+            raise UnauthorizedError(
+                f"m2m client '{self._settings.client_id}' is not authorized. IdP response: {resp}"
+            )
 
         # Unhandled
         raise ClientCredentialsFlowError("client credentials flow failed", r.content)

earthscope_sdk/auth/device_code_flow.py

@@ -1,11 +1,12 @@
 import logging
+from asyncio import sleep
 from contextlib import asynccontextmanager, contextmanager
-from dataclasses import dataclass
 from enum import Enum
 from json import JSONDecodeError
-from time import sleep
 from typing import Optional
 
+from pydantic import BaseModel, ValidationError
+
 from earthscope_sdk.auth.auth_flow import AuthFlow
 from earthscope_sdk.auth.error import (
     DeviceCodePollingError,
@@ -25,18 +26,16 @@ class PollingErrorType(str, Enum):
     ACCESS_DENIED = "access_denied"
 
 
-@dataclass
-class GetDeviceCodeResponse:
+class GetDeviceCodeResponse(BaseModel):
     device_code: str
     user_code: str
     verification_uri: str
     verification_uri_complete: str
     expires_in: int
-    interval: int
+    interval: float
 
 
-@dataclass
-class PollingErrorResponse:
+class PollingErrorResponse(BaseModel):
     error: PollingErrorType
     error_description: str
 
@@ -157,7 +156,7 @@ class DeviceCodeFlow(AuthFlow):
         try:
             while True:
                 # IdP-provided poll interval
-                sleep(codes.interval)
+                await sleep(codes.interval)
 
                 r = await self._ctx.httpx_client.post(
                     f"{self._settings.domain}oauth/token",
@@ -185,7 +184,12 @@ class DeviceCodeFlow(AuthFlow):
                     return self
 
                 # Keep polling
-                poll_err = PollingErrorResponse(**resp)
+                try:
+                    poll_err = PollingErrorResponse.model_validate(resp)
+                except ValidationError as e:
+                    raise DeviceCodePollingError(
+                        f"Failed to unpack polling response: {r.text}"
+                    ) from e
                 if poll_err.error in [
                     PollingErrorType.AUTHORIZATION_PENDING,
                     PollingErrorType.SLOW_DOWN,
@@ -235,7 +239,12 @@ class DeviceCodeFlow(AuthFlow):
                 f"Failed to get a device code: {r.content}"
             )
 
-        codes = GetDeviceCodeResponse(**r.json())
+        try:
+            codes = GetDeviceCodeResponse.model_validate_json(r.content)
+        except ValidationError as e:
+            raise DeviceCodeRequestDeviceCodeError(
+                f"Failed to unpack device code response: {r.text}"
+            ) from e
 
         logger.debug(f"Got device code response: {codes}")
         return codes

earthscope_sdk/common/context.py

@@ -78,6 +78,8 @@ class SdkContext:
         self._httpx_client = httpx.AsyncClient(
             auth=self.auth_flow,
             headers={
+                **self.settings.http.extra_headers,
+                # override anything specified via extra_headers
                 "user-agent": self.settings.http.user_agent,
             },
             limits=self.settings.http.limits,

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/models.py

@@ -1,6 +1,7 @@
 import base64
 import binascii
 import datetime as dt
+import fnmatch
 import functools
 from contextlib import suppress
 from enum import Enum
@@ -15,14 +16,12 @@ from pydantic import (
     ConfigDict,
     Field,
     HttpUrl,
-    SecretStr,
-    SerializationInfo,
     ValidationError,
-    field_serializer,
     model_validator,
 )
 
 from earthscope_sdk import __version__
+from earthscope_sdk.model.secret import SecretStr
 
 
 def _try_float(v: Any):
@@ -94,23 +93,6 @@ class Tokens(BaseModel):
 
         raise ValueError("Unable to decode access token body")
 
-    @field_serializer("access_token", "id_token", "refresh_token", when_used="json")
-    def dump_secret_json(self, secret: Optional[SecretStr], info: SerializationInfo):
-        """
-        A special field serializer to dump the actual secret value when writing to JSON.
-
-        Only writes secret in plaintext when `info.context == "plaintext".
-
-        See [Pydantic docs](https://docs.pydantic.dev/latest/concepts/serialization/#serialization-context)
-        """
-        if secret is None:
-            return None
-
-        if info.context == "plaintext":
-            return secret.get_secret_value()
-
-        return str(secret)
-
     @model_validator(mode="after")
     def ensure_one_of(self):
         # allow all fields to be optional in subclasses
@@ -207,6 +189,12 @@ class AuthFlowSettings(Tokens):
     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,
@@ -222,6 +210,37 @@ class AuthFlowSettings(Tokens):
 
         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):
     """
@@ -242,6 +261,7 @@ class HttpSettings(BaseModel):
 
     # Other
     user_agent: str = f"earthscope-sdk py/{__version__}"
+    extra_headers: dict[str, str] = {}
 
     @cached_property
     def limits(self):

earthscope_sdk/config/settings.py

@@ -11,11 +11,15 @@ from pydantic_settings import (
     TomlConfigSettingsSource,
 )
 
+from earthscope_sdk.config._bootstrap import BootstrapEnvironmentSettingsSource
 from earthscope_sdk.config._compat import LegacyEarthScopeCLISettingsSource
 from earthscope_sdk.config._util import deep_merge, get_config_dir, slugify
 from earthscope_sdk.config.error import ProfileDoesNotExistError
 from earthscope_sdk.config.models import SdkBaseSettings, Tokens
 
+_BOOTSTRAP_ENV_VAR = "ES_BOOTSTRAP_SETTINGS"
+"""Environment variable for bootstrapping the SDK"""
+
 _DEFAULT_PROFILE = "default"
 """Default profile name"""
 
@@ -269,6 +273,12 @@ class SdkSettings(SdkBaseSettings, BaseSettings):
         alias = SdkSettings.model_fields["profile_name"].validation_alias
         global_settings = _GlobalSettingsSource(settings_cls, "profile_name", alias)
 
+        # Check for bootstrapping configuration
+        bootstrap_settings = BootstrapEnvironmentSettingsSource(
+            settings_cls,
+            _BOOTSTRAP_ENV_VAR,
+        )
+
         # Compatibility with earthscope-cli v0.x.x state:
         # If we find this file, we only care about the access and refresh tokens
         keep_keys = {"access_token", "refresh_token"}
@@ -281,4 +291,5 @@ class SdkSettings(SdkBaseSettings, BaseSettings):
             dotenv_settings,
             global_settings,
             legacy_settings,
+            bootstrap_settings,
         )

earthscope_sdk/model/secret.py

@@ -0,0 +1,29 @@
+from typing import Annotated
+
+from pydantic import PlainSerializer, SerializationInfo
+from pydantic import SecretStr as _SecretStr
+
+
+def _dump_secret_plaintext(secret: _SecretStr, info: SerializationInfo):
+    """
+    A special field serializer to dump the actual secret value.
+
+    Only writes secret in plaintext when `info.context == "plaintext".
+
+    See [Pydantic docs](https://docs.pydantic.dev/latest/concepts/serialization/#serialization-context)
+    """
+
+    if info.context == "plaintext":
+        return secret.get_secret_value()
+
+    return str(secret)
+
+
+SecretStr = Annotated[
+    _SecretStr,
+    PlainSerializer(
+        _dump_secret_plaintext,
+        return_type=str,
+        when_used="json-unless-none",
+    ),
+]

{earthscope_sdk-1.0.0b1.dist-info → earthscope_sdk-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: earthscope-sdk
-Version: 1.0.0b1
+Version: 1.1.0
 Summary: An SDK for EarthScope API
 Author-email: EarthScope <data-help@earthscope.org>
 License:                                  Apache License
@@ -222,6 +222,7 @@ Requires-Dist: build; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: pip-tools; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: pytest-httpx; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
@@ -243,7 +244,7 @@ pip install earthscope-sdk
 
 ### Usage
 
-For detailed usage options and examples, visit [our usage docs](docs/usage.md).
+For detailed usage info and examples, visit [our SDK docs](https://docs.earthscope.org/projects/SDK).
 
 ```py
 # Import and create a client
@@ -300,7 +301,7 @@ Once refreshable credentials are available to the SDK, it will transparently han
 
 ### Same host
 
-If you have the [EarthScope CLI](TODO) installed on the same host that is running your application which uses `earthscope-sdk`, you can simply log in using the CLI. The CLI shares credentials and configuration with this SDK (when running on the same host).
+If you have the [EarthScope CLI](https://docs.earthscope.org/projects/CLI) installed on the same host that is running your application which uses `earthscope-sdk`, you can simply log in using the CLI. The CLI shares credentials and configuration with this SDK (when running on the same host).
 
 Running `es login` will open your browser and prompt you to log in to your EarthScope account.
 
@@ -320,7 +321,7 @@ Now when you run your application, `earthscope-sdk` will find your credentials.
 
 Sometimes your workload runs on different hosts than your main workstation and you cannot feasibly "log in" on all of them. For example, maybe you're running many containers in your workload.
 
-You can still use the [EarthScope CLI](TODO) to facilitate auth for applications on other machines.
+You can still use the [EarthScope CLI](https://docs.earthscope.org/projects/CLI) to facilitate auth for applications on other machines.
 
 1. Use the CLI on your primary workstation [as described above](#same-host) to log in.
 

{earthscope_sdk-1.0.0b1.dist-info → earthscope_sdk-1.1.0.dist-info}/RECORD

@@ -1,8 +1,8 @@
-earthscope_sdk/__init__.py,sha256=GUJAs2cToEo9f8MaCUP_VnRsyqZWNhsN-pId5vzPk4U,156
+earthscope_sdk/__init__.py,sha256=bkZcCw9euoFA9FOzEZW4H6cpa-EPH1GUsAsUEwLclIY,154
 earthscope_sdk/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-earthscope_sdk/auth/auth_flow.py,sha256=6jBQxLJ2gAxXGgtZYXDH1yg5L_WUmgu7fRvW4JoCi4Q,10198
-earthscope_sdk/auth/client_credentials_flow.py,sha256=1GyDSIR1OgYP4u0xZoTov1u_YhY1AzHFpOcBCzY1h6E,2769
-earthscope_sdk/auth/device_code_flow.py,sha256=dC5Ffj3HzBguRxSHCZYvTe1MD3C-iKf2AlanGuRKNvI,7922
+earthscope_sdk/auth/auth_flow.py,sha256=gxJmCr5TAhMEss7RskYFCv6-D3A5h0Zw2ejeLJJ_9aI,10352
+earthscope_sdk/auth/client_credentials_flow.py,sha256=GAvskuoEd6qHe-BtfGwYQisMedmSkDhagy4aRPVPri4,2494
+earthscope_sdk/auth/device_code_flow.py,sha256=p53pgRQraToFwONPBj3O3DHAa4x4rE6rvygo_Bbj5_U,8394
 earthscope_sdk/auth/error.py,sha256=eC33Bw1HaBEJE7-eI2krtE__5PxStc3EyiYO12v0kVw,693
 earthscope_sdk/client/__init__.py,sha256=JotTr5oTiiOsUc0RTg82EVCUSg_-u80Qu_R0-crCXkY,139
 earthscope_sdk/client/_client.py,sha256=ai7WdsTOYglA6bLkT-Wntvxlke6nSaGHwqrtg5PEy80,833
@@ -13,16 +13,18 @@ earthscope_sdk/client/user/models.py,sha256=drZAMwOYC1NVCzBZQhNL-pPTB28SURKfoZF8
 earthscope_sdk/common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 earthscope_sdk/common/_sync_runner.py,sha256=h_A2pSEjZCLj7ov50M6cWHVoX6eXVmGzz5nX0MwLWDY,4131
 earthscope_sdk/common/client.py,sha256=g5ZTNhFm33H68J9pWD5fDu760Yd5cBdfQmsbU3t8D_4,2156
-earthscope_sdk/common/context.py,sha256=vrCB_Ez-98Ir7c0GrCe-g7DuRCgc9vPaoRWFYf5q8Ko,5138
+earthscope_sdk/common/context.py,sha256=bt2UhSsIZGBaukA0QJiFsPhJaSUDdcT9kmAZrfTQsc4,5254
 earthscope_sdk/common/service.py,sha256=SCUZVJA3jFaEPeFrOf0v9osf2UpqldhlFmirOYWJjxM,1506
 earthscope_sdk/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+earthscope_sdk/config/_bootstrap.py,sha256=BvDSRccvFPFRnLS4MlE7OMLGYEgxY7znxFZ6AYgxvOE,1243
 earthscope_sdk/config/_compat.py,sha256=P3F5y_Kf5zp9m9uOhl1Bp3ke6expxq4Sm9AeVaBbAHk,4610
 earthscope_sdk/config/_util.py,sha256=RZ6zvKrvjUkO7i69s7AVoIDhamRg4x71CAZLnucr9QM,1249
 earthscope_sdk/config/error.py,sha256=jh25q-b317lAvp32WwQw0zdYoV-MxZtg-n5FgZOMymI,95
-earthscope_sdk/config/models.py,sha256=1334Rxzw4qDLSdQg9btxFQySBOCb8TEW6J95M-lyKEc,8198
-earthscope_sdk/config/settings.py,sha256=I2DwEvfmETcaYbSvUybs0EIih0yiJO9D46WnWzKPqbo,8812
-earthscope_sdk-1.0.0b1.dist-info/licenses/LICENSE,sha256=E_MrVXxRaMQNpvZhsDuz_J9N_ux7dlL_WpYSsE391HU,11349
-earthscope_sdk-1.0.0b1.dist-info/METADATA,sha256=BHeAUzZ882lmEExnoVKIywGSYvIbyNdnIh8BzRJs2Ng,17988
-earthscope_sdk-1.0.0b1.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-earthscope_sdk-1.0.0b1.dist-info/top_level.txt,sha256=zTtIT9yN3JPJF7TqmTzqQcAvZZe4pAm907DLoGa5T_E,15
-earthscope_sdk-1.0.0b1.dist-info/RECORD,,
+earthscope_sdk/config/models.py,sha256=MCN9fbJKqnKHnSeg-KhUOsnXsqMxmawcOiZ62689ZS0,8723
+earthscope_sdk/config/settings.py,sha256=kGsoqAgoUS2xrI0rvdqbLEsI2M0Mpbm73oEDLpJG4_Q,9205
+earthscope_sdk/model/secret.py,sha256=QTyWCqXvf9ZYWaVVQcGzdt3rGtyU3sx13AlzkNE3gaU,731
+earthscope_sdk-1.1.0.dist-info/licenses/LICENSE,sha256=E_MrVXxRaMQNpvZhsDuz_J9N_ux7dlL_WpYSsE391HU,11349
+earthscope_sdk-1.1.0.dist-info/METADATA,sha256=t9dLQDJbJeZBd-CiUncz2Hh4JnGazSsZg19MnIP6KQ8,18122
+earthscope_sdk-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+earthscope_sdk-1.1.0.dist-info/top_level.txt,sha256=zTtIT9yN3JPJF7TqmTzqQcAvZZe4pAm907DLoGa5T_E,15
+earthscope_sdk-1.1.0.dist-info/RECORD,,

{earthscope_sdk-1.0.0b1.dist-info → earthscope_sdk-1.1.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.1.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any