ee-client 2.6.3__tar.gz → 3.0.0__tar.gz

{ee_client-2.6.3 → ee_client-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ee-client
-Version: 2.6.3
+Version: 3.0.0
 Summary: extends the capabilities of the earthengine-api by providing custom session management and client interactions
 Author-email: Daniel Guerrero <dfgm2006@gmail.com>
 Project-URL: Homepage, https://github.com/dfguerrerom/ee-client
@@ -18,6 +18,8 @@ Requires-Dist: earthengine-api
 Requires-Dist: httpx[http2]
 Requires-Dist: tenacity
 Requires-Dist: pydantic
+Requires-Dist: google-auth
+Requires-Dist: requests
 Provides-Extra: dev
 Requires-Dist: pre-commit>=2.18.0; extra == "dev"
 Requires-Dist: commitizen; extra == "dev"
@@ -60,13 +62,12 @@ While Google Earth Engine applications can be created using a global service acc
 
 Unlike the standard GEE API—which relies on a global session object and does not support multi-user environments—this client ensures that each session is authenticated and managed independently with user-specific credentials.
 
-Each session is instantiated via the ``EESession`` class, currently only accepts SEPAL headers as its only parameter. **A valid ``sepal-session-id`` cookie must be present in these headers**, as it is used to retrieve the corresponding GEE credentials. Once authenticated, the session exposes an ``operations`` property that provides easy access to key API methods.
+Each session is instantiated via the ``EESession`` class, which supports several credential sources — a service-account key, an ``EARTHENGINE_TOKEN`` environment variable, ``earthengine authenticate`` OAuth credentials, or Application Default Credentials. Once authenticated, the session exposes an ``operations`` property that provides easy access to key API methods.
 
 Key Features
 ------------
 
 - **Custom User Authentication**: Enable users to access their private GEE assets without requiring them to be public, solving the limitation of global service account approaches.
-- **SEPAL-based Initialization**: Create sessions using SEPAL headers. The required ``sepal-session-id`` cookie is automatically used to retrieve GEE credentials.
 - **Multi-User Session Management**: Encapsulate user-specific credentials and project data in independent ``EESession`` objects.
 - **Enhanced API Operations**: Access GEE functionalities via the ``operations`` property, which includes methods such as:
   - ``get_info``: Retrieve detailed information about an Earth Engine object.
@@ -89,38 +90,35 @@ Usage
 Initialization and Authentication
 +++++++++++++++++++++++++++++++++
 
-The Earth Engine Session Client must be initialized using SEPAL headers. **Ensure that the headers include the ``sepal-session-id`` cookie**, which is essential for retrieving the GEE credentials.
+A session can be built from any standard Google/Earth Engine credential via factory constructors, each holding a live, refreshable credential:
 
 .. code-block:: python
 
    from eeclient import EESession
 
-   # Example SEPAL headers with the mandatory sepal-session-id cookie.
-   sepal_headers = {
-       "cookie": [
-           "sepal-session-id=your_session_id",
-           "other_cookie=other_value"
-       ],
-       "sepal_user": [{
-           "id": 123,
-           "username": "your_username",
-           "googleTokens": {
-               "accessToken": "your_access_token",
-               "refreshToken": "your_refresh_token",
-               "accessTokenExpiryDate": 1234567890,
-               "REFRESH_IF_EXPIRES_IN_MINUTES": 10,
-               "projectId": "your_project_id",
-               "legacyProject": "your_legacy_project"
-           },
-           "status": "active",
-           "roles": ["role1", "role2"],
-           "systemUser": False,
-           "admin": False
-       }]
-   }
-
-   # Create and validate the session with SEPAL headers
-   session = EESession(sepal_headers)
+   # Service-account key (dict or path)
+   session = EESession.from_service_account("sa-key.json")
+
+   # EARTHENGINE_TOKEN env var, else ~/.config/earthengine/credentials
+   session = EESession.from_earthengine_token()
+
+   # An existing google.auth Credentials object
+   session = EESession.from_google_credentials(creds, project="my-project")
+
+   # Application Default Credentials (explicit opt-in)
+   session = EESession.from_application_default()
+
+   # Resolve from the environment (opt-in): EARTHENGINE_TOKEN / EE OAuth file
+   session = EESession.from_default()
+
+Credentials are **never resolved implicitly** — a bare ``EESession()`` constructor call is not supported; always use a ``from_*`` factory to build a session. To resolve from the environment explicitly, call ``EESession.from_default()``, which walks local sources only, in this order:
+
+1. ``EARTHENGINE_TOKEN`` environment variable
+2. Earth Engine OAuth file (``~/.config/earthengine/credentials``)
+
+Application Default Credentials are **not** included — call ``EESession.from_application_default()`` to use them.
+
+To see which source a session ended up using, inspect ``session.auth_mode`` (the credential *kind*: ``file``/``oauth``/``service_account``/``adc``) and ``session.auth_source`` (the precise origin: ``earthengine_token``/``ee_oauth_file``/``service_account``/``application_default``/``google_credentials``).
 
 Making API Calls
 ++++++++++++++++

{ee_client-2.6.3 → ee_client-3.0.0}/README.rst

@@ -29,13 +29,12 @@ While Google Earth Engine applications can be created using a global service acc
 
 Unlike the standard GEE API—which relies on a global session object and does not support multi-user environments—this client ensures that each session is authenticated and managed independently with user-specific credentials.
 
-Each session is instantiated via the ``EESession`` class, currently only accepts SEPAL headers as its only parameter. **A valid ``sepal-session-id`` cookie must be present in these headers**, as it is used to retrieve the corresponding GEE credentials. Once authenticated, the session exposes an ``operations`` property that provides easy access to key API methods.
+Each session is instantiated via the ``EESession`` class, which supports several credential sources — a service-account key, an ``EARTHENGINE_TOKEN`` environment variable, ``earthengine authenticate`` OAuth credentials, or Application Default Credentials. Once authenticated, the session exposes an ``operations`` property that provides easy access to key API methods.
 
 Key Features
 ------------
 
 - **Custom User Authentication**: Enable users to access their private GEE assets without requiring them to be public, solving the limitation of global service account approaches.
-- **SEPAL-based Initialization**: Create sessions using SEPAL headers. The required ``sepal-session-id`` cookie is automatically used to retrieve GEE credentials.
 - **Multi-User Session Management**: Encapsulate user-specific credentials and project data in independent ``EESession`` objects.
 - **Enhanced API Operations**: Access GEE functionalities via the ``operations`` property, which includes methods such as:
   - ``get_info``: Retrieve detailed information about an Earth Engine object.
@@ -58,38 +57,35 @@ Usage
 Initialization and Authentication
 +++++++++++++++++++++++++++++++++
 
-The Earth Engine Session Client must be initialized using SEPAL headers. **Ensure that the headers include the ``sepal-session-id`` cookie**, which is essential for retrieving the GEE credentials.
+A session can be built from any standard Google/Earth Engine credential via factory constructors, each holding a live, refreshable credential:
 
 .. code-block:: python
 
    from eeclient import EESession
 
-   # Example SEPAL headers with the mandatory sepal-session-id cookie.
-   sepal_headers = {
-       "cookie": [
-           "sepal-session-id=your_session_id",
-           "other_cookie=other_value"
-       ],
-       "sepal_user": [{
-           "id": 123,
-           "username": "your_username",
-           "googleTokens": {
-               "accessToken": "your_access_token",
-               "refreshToken": "your_refresh_token",
-               "accessTokenExpiryDate": 1234567890,
-               "REFRESH_IF_EXPIRES_IN_MINUTES": 10,
-               "projectId": "your_project_id",
-               "legacyProject": "your_legacy_project"
-           },
-           "status": "active",
-           "roles": ["role1", "role2"],
-           "systemUser": False,
-           "admin": False
-       }]
-   }
-
-   # Create and validate the session with SEPAL headers
-   session = EESession(sepal_headers)
+   # Service-account key (dict or path)
+   session = EESession.from_service_account("sa-key.json")
+
+   # EARTHENGINE_TOKEN env var, else ~/.config/earthengine/credentials
+   session = EESession.from_earthengine_token()
+
+   # An existing google.auth Credentials object
+   session = EESession.from_google_credentials(creds, project="my-project")
+
+   # Application Default Credentials (explicit opt-in)
+   session = EESession.from_application_default()
+
+   # Resolve from the environment (opt-in): EARTHENGINE_TOKEN / EE OAuth file
+   session = EESession.from_default()
+
+Credentials are **never resolved implicitly** — a bare ``EESession()`` constructor call is not supported; always use a ``from_*`` factory to build a session. To resolve from the environment explicitly, call ``EESession.from_default()``, which walks local sources only, in this order:
+
+1. ``EARTHENGINE_TOKEN`` environment variable
+2. Earth Engine OAuth file (``~/.config/earthengine/credentials``)
+
+Application Default Credentials are **not** included — call ``EESession.from_application_default()`` to use them.
+
+To see which source a session ended up using, inspect ``session.auth_mode`` (the credential *kind*: ``file``/``oauth``/``service_account``/``adc``) and ``session.auth_source`` (the precise origin: ``earthengine_token``/``ee_oauth_file``/``service_account``/``application_default``/``google_credentials``).
 
 Making API Calls
 ++++++++++++++++

{ee_client-2.6.3 → ee_client-3.0.0}/ee_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ee-client
-Version: 2.6.3
+Version: 3.0.0
 Summary: extends the capabilities of the earthengine-api by providing custom session management and client interactions
 Author-email: Daniel Guerrero <dfgm2006@gmail.com>
 Project-URL: Homepage, https://github.com/dfguerrerom/ee-client
@@ -18,6 +18,8 @@ Requires-Dist: earthengine-api
 Requires-Dist: httpx[http2]
 Requires-Dist: tenacity
 Requires-Dist: pydantic
+Requires-Dist: google-auth
+Requires-Dist: requests
 Provides-Extra: dev
 Requires-Dist: pre-commit>=2.18.0; extra == "dev"
 Requires-Dist: commitizen; extra == "dev"
@@ -60,13 +62,12 @@ While Google Earth Engine applications can be created using a global service acc
 
 Unlike the standard GEE API—which relies on a global session object and does not support multi-user environments—this client ensures that each session is authenticated and managed independently with user-specific credentials.
 
-Each session is instantiated via the ``EESession`` class, currently only accepts SEPAL headers as its only parameter. **A valid ``sepal-session-id`` cookie must be present in these headers**, as it is used to retrieve the corresponding GEE credentials. Once authenticated, the session exposes an ``operations`` property that provides easy access to key API methods.
+Each session is instantiated via the ``EESession`` class, which supports several credential sources — a service-account key, an ``EARTHENGINE_TOKEN`` environment variable, ``earthengine authenticate`` OAuth credentials, or Application Default Credentials. Once authenticated, the session exposes an ``operations`` property that provides easy access to key API methods.
 
 Key Features
 ------------
 
 - **Custom User Authentication**: Enable users to access their private GEE assets without requiring them to be public, solving the limitation of global service account approaches.
-- **SEPAL-based Initialization**: Create sessions using SEPAL headers. The required ``sepal-session-id`` cookie is automatically used to retrieve GEE credentials.
 - **Multi-User Session Management**: Encapsulate user-specific credentials and project data in independent ``EESession`` objects.
 - **Enhanced API Operations**: Access GEE functionalities via the ``operations`` property, which includes methods such as:
   - ``get_info``: Retrieve detailed information about an Earth Engine object.
@@ -89,38 +90,35 @@ Usage
 Initialization and Authentication
 +++++++++++++++++++++++++++++++++
 
-The Earth Engine Session Client must be initialized using SEPAL headers. **Ensure that the headers include the ``sepal-session-id`` cookie**, which is essential for retrieving the GEE credentials.
+A session can be built from any standard Google/Earth Engine credential via factory constructors, each holding a live, refreshable credential:
 
 .. code-block:: python
 
    from eeclient import EESession
 
-   # Example SEPAL headers with the mandatory sepal-session-id cookie.
-   sepal_headers = {
-       "cookie": [
-           "sepal-session-id=your_session_id",
-           "other_cookie=other_value"
-       ],
-       "sepal_user": [{
-           "id": 123,
-           "username": "your_username",
-           "googleTokens": {
-               "accessToken": "your_access_token",
-               "refreshToken": "your_refresh_token",
-               "accessTokenExpiryDate": 1234567890,
-               "REFRESH_IF_EXPIRES_IN_MINUTES": 10,
-               "projectId": "your_project_id",
-               "legacyProject": "your_legacy_project"
-           },
-           "status": "active",
-           "roles": ["role1", "role2"],
-           "systemUser": False,
-           "admin": False
-       }]
-   }
-
-   # Create and validate the session with SEPAL headers
-   session = EESession(sepal_headers)
+   # Service-account key (dict or path)
+   session = EESession.from_service_account("sa-key.json")
+
+   # EARTHENGINE_TOKEN env var, else ~/.config/earthengine/credentials
+   session = EESession.from_earthengine_token()
+
+   # An existing google.auth Credentials object
+   session = EESession.from_google_credentials(creds, project="my-project")
+
+   # Application Default Credentials (explicit opt-in)
+   session = EESession.from_application_default()
+
+   # Resolve from the environment (opt-in): EARTHENGINE_TOKEN / EE OAuth file
+   session = EESession.from_default()
+
+Credentials are **never resolved implicitly** — a bare ``EESession()`` constructor call is not supported; always use a ``from_*`` factory to build a session. To resolve from the environment explicitly, call ``EESession.from_default()``, which walks local sources only, in this order:
+
+1. ``EARTHENGINE_TOKEN`` environment variable
+2. Earth Engine OAuth file (``~/.config/earthengine/credentials``)
+
+Application Default Credentials are **not** included — call ``EESession.from_application_default()`` to use them.
+
+To see which source a session ended up using, inspect ``session.auth_mode`` (the credential *kind*: ``file``/``oauth``/``service_account``/``adc``) and ``session.auth_source`` (the precise origin: ``earthengine_token``/``ee_oauth_file``/``service_account``/``application_default``/``google_credentials``).
 
 Making API Calls
 ++++++++++++++++

{ee_client-2.6.3 → ee_client-3.0.0}/ee_client.egg-info/SOURCES.txt

@@ -9,11 +9,13 @@ ee_client.egg-info/top_level.txt
 eeclient/__init__.py
 eeclient/cache.py
 eeclient/client.py
+eeclient/credential_mixin.py
 eeclient/data.py
 eeclient/exceptions.py
 eeclient/helpers.py
 eeclient/models.py
 eeclient/oauth_app.py
+eeclient/providers.py
 eeclient/sepal_credential_mixin.py
 eeclient/tasks.py
 eeclient/export/__init__.py
@@ -23,12 +25,16 @@ eeclient/interfaces/__init__.py
 eeclient/interfaces/export.py
 eeclient/interfaces/operations.py
 eeclient/interfaces/tasks.py
+tests/test_agnostic_auth_integration.py
 tests/test_cache.py
 tests/test_client.py
 tests/test_data.py
 tests/test_export_image.py
 tests/test_export_table.py
+tests/test_factories.py
 tests/test_integration_get_assets.py
 tests/test_models.py
+tests/test_providers.py
+tests/test_resolution.py
 tests/test_tasks.py
 tests/test_tls_verify.py

{ee_client-2.6.3 → ee_client-3.0.0}/ee_client.egg-info/requires.txt

@@ -2,6 +2,8 @@ earthengine-api
 httpx[http2]
 tenacity
 pydantic
+google-auth
+requests
 
 [dev]
 pre-commit>=2.18.0

{ee_client-2.6.3 → ee_client-3.0.0}/eeclient/__init__.py

@@ -1,6 +1,6 @@
 __title__ = "eeclient"
 __summary__ = "A client for Google Earth Engine"
-__version__ = "2.6.3"
+__version__ = "3.0.0"
 
 __author__ = "Daniel Guerrero"
 __email__ = "dfgm2006@gmail.com"

{ee_client-2.6.3 → ee_client-3.0.0}/eeclient/client.py

@@ -10,7 +10,7 @@ from contextlib import asynccontextmanager
 
 from eeclient.exceptions import EEClientError, EERestException
 from eeclient.models import GEEHeaders, SepalHeaders
-from eeclient.sepal_credential_mixin import SepalCredentialMixin
+from eeclient.credential_mixin import CredentialMixin
 from eeclient.cache import ResponseCache
 
 import eeclient.export as _export_module
@@ -30,11 +30,6 @@ logger = logging.getLogger("eeclient")
 # Default values that won't raise exceptions during import
 EARTH_ENGINE_API_URL = "https://earthengine.googleapis.com/v1alpha"
 
-# These will be set properly when EESession is initialized
-SEPAL_HOST = os.getenv("SEPAL_HOST")
-SEPAL_API_DOWNLOAD_URL = None
-VERIFY_SSL = True
-
 
 class SimpleRateLimiter:
     def __init__(self, qps: float | None):
@@ -53,24 +48,29 @@ class SimpleRateLimiter:
             self._next = max(now, self._next) + 1.0 / self.qps
 
 
-class EESession(SepalCredentialMixin):
+class EESession(CredentialMixin):
     def __init__(
         self,
         sepal_headers: Optional[SepalHeaders] = None,
         enforce_project_id: bool = True,
+        *,
+        _provider=None,
     ):
-        """Session that handles two scenarios to set the headers for Earth Engine API
+        """Session for the Earth Engine REST API with pluggable authentication.
 
-        It can be initialized with the headers sent by SEPAL or with the
-        credentials and project
+        Provide a credential source: ``sepal_headers`` for the SEPAL session
+        path, or use an ``EESession.from_*()`` factory / ``from_default()`` for
+        service-account, ``EARTHENGINE_TOKEN``, OAuth or ADC sources. A bare
+        ``EESession()`` with no source raises ``EEClientError``.
 
         Args:
-            sepal_headers (SepalHeaders): The headers sent by SEPAL
-            enforce_project_id (bool, optional): If set, it cannot be changed.
-                Defaults to True.
+            sepal_headers (Optional[SepalHeaders]): SEPAL session headers; omit
+                and use a factory / ``from_default()`` for other sources.
+            enforce_project_id (bool, optional): If set, the project id is not
+                overwritten on refresh. Defaults to True.
 
         Raises:
-            ValueError: If SEPAL_HOST environment variable is not set
+            EEClientError: If no credential source is provided.
         """
         self._inflight = asyncio.BoundedSemaphore(30)
         self._rate = SimpleRateLimiter(60)
@@ -83,7 +83,7 @@ class EESession(SepalCredentialMixin):
         self._assets_cache = ResponseCache(ttl=10.0, max_size=100)
 
         self.enforce_project_id = enforce_project_id
-        super().__init__(sepal_headers)
+        super().__init__(sepal_headers, provider=_provider)
 
         self.logger = logging.getLogger(f"eeclient.{self.user}")
         self.logger.debug(
@@ -117,8 +117,9 @@ class EESession(SepalCredentialMixin):
         """Asynchronously create an EESession instance.
 
         Args:
-            sepal_headers (Optional[SepalHeaders]): The headers sent by SEPAL.
-                If None, will use file-based authentication.
+            sepal_headers (Optional[SepalHeaders]): SEPAL headers for SEPAL
+                session mode (required here). For other sources use an
+                EESession.from_*() factory, or EESession.from_default().
             enforce_project_id (bool, optional): If set, it cannot be changed.
                 Defaults to True.
 
@@ -128,6 +129,113 @@ class EESession(SepalCredentialMixin):
         session = cls(sepal_headers, enforce_project_id)
         return await session.initialize()
 
+    # -- Agnostic credential factories -------------------------------------
+    @classmethod
+    def from_google_credentials(
+        cls,
+        creds,
+        *,
+        project=None,
+        enforce_project_id=True,
+        _auth_mode="oauth",
+        _auth_source="google_credentials",
+    ) -> "EESession":
+        """Build a session from a live ``google.auth`` Credentials object."""
+        from eeclient.providers import GoogleAuthProvider
+
+        provider = GoogleAuthProvider(
+            creds, project, auth_mode=_auth_mode, auth_source=_auth_source
+        )
+        session = cls(enforce_project_id=enforce_project_id, _provider=provider)
+        session.set_credentials_sync()  # eager load (factories are the sync path, D6)
+        return session
+
+    @classmethod
+    def from_service_account(
+        cls, info_or_path, *, project=None, scopes=None, enforce_project_id=True
+    ) -> "EESession":
+        """Build a session from a service-account key (dict or file path)."""
+        from eeclient.providers import DEFAULT_SCOPES, _service_account_credentials
+
+        creds, sa_project = _service_account_credentials(
+            info_or_path, scopes or DEFAULT_SCOPES
+        )
+        return cls.from_google_credentials(
+            creds,
+            project=project or sa_project,
+            enforce_project_id=enforce_project_id,
+            _auth_mode="service_account",
+            _auth_source="service_account",
+        )
+
+    @classmethod
+    def from_earthengine_token(
+        cls, *, project=None, enforce_project_id=True
+    ) -> "EESession":
+        """Build a session from ``EARTHENGINE_TOKEN``, else the EE OAuth file."""
+        from eeclient.providers import (
+            DEFAULT_SCOPES,
+            _credentials_from_earthengine_token,
+            _google_auth_mode,
+            _oauth_credentials_from_ee_file,
+        )
+
+        raw = os.getenv("EARTHENGINE_TOKEN")
+        if raw:
+            creds, tok_project = _credentials_from_earthengine_token(
+                raw, DEFAULT_SCOPES
+            )
+            mode, source = _google_auth_mode(creds), "earthengine_token"
+        else:
+            creds, tok_project = _oauth_credentials_from_ee_file(DEFAULT_SCOPES)
+            mode, source = "oauth", "ee_oauth_file"
+        return cls.from_google_credentials(
+            creds,
+            project=project or tok_project,
+            enforce_project_id=enforce_project_id,
+            _auth_mode=mode,
+            _auth_source=source,
+        )
+
+    @classmethod
+    def from_application_default(
+        cls, *, project=None, scopes=None, enforce_project_id=True
+    ) -> "EESession":
+        """Build a session from Application Default Credentials (opt-in ADC)."""
+        from eeclient.providers import DEFAULT_SCOPES, _application_default_credentials
+
+        creds, adc_project = _application_default_credentials(scopes or DEFAULT_SCOPES)
+        return cls.from_google_credentials(
+            creds,
+            project=project or adc_project,
+            enforce_project_id=enforce_project_id,
+            _auth_mode="adc",
+            _auth_source="application_default",
+        )
+
+    @classmethod
+    def from_sepal_headers(cls, headers, *, enforce_project_id=True) -> "EESession":
+        """Build a session from SEPAL headers (names the existing path)."""
+        return cls(headers, enforce_project_id=enforce_project_id)
+
+    @classmethod
+    def from_default(cls, *, enforce_project_id=True) -> "EESession":
+        """Resolve credentials from the environment — explicit opt-in.
+
+        Walks local sources only (SEPAL file, ``EARTHENGINE_TOKEN``, Earth Engine
+        OAuth file) and fails closed in a SEPAL context. ADC is not included —
+        use ``from_application_default()``. This is opt-in: a bare ``EESession()``
+        does not auto-resolve; the caller must pick a source.
+
+        Construction does no network I/O — the token refresh is deferred to
+        ``await initialize()`` / the first ``get_headers()`` so async callers are
+        not blocked (use ``set_credentials_sync()`` for a synchronous refresh).
+        """
+        from eeclient.providers import resolve_default_provider
+
+        provider = resolve_default_provider()
+        return cls(enforce_project_id=enforce_project_id, _provider=provider)
+
     async def get_assets_folder(self) -> str:
         if self.needs_credentials_refresh():
             await self.set_credentials()
@@ -149,7 +257,7 @@ class EESession(SepalCredentialMixin):
 
         data = {
             "x-goog-user-project": self.project_id,
-            "Authorization": f"Bearer {self._credentials.access_token}",
+            "Authorization": f"Bearer {self.access_token}",
             "Username": username,
         }
 
@@ -268,9 +376,7 @@ class EESession(SepalCredentialMixin):
                     error_type = (
                         "Rate limit exceeded"
                         if e.code == 429
-                        else "Unauthorized"
-                        if e.code == 401
-                        else "Service unavailable"
+                        else "Unauthorized" if e.code == 401 else "Service unavailable"
                     )
                     attempt += 1
                     wait_time = min(initial_wait * (2**attempt), max_wait)

ee_client-3.0.0/eeclient/credential_mixin.py

@@ -0,0 +1,97 @@
+import logging
+import time
+from typing import Optional
+
+from eeclient.exceptions import EEClientError
+from eeclient.models import SepalHeaders
+from eeclient.providers import CredentialSnapshot, SepalSessionProvider
+
+log = logging.getLogger("eeclient")
+
+# SEPAL-specific attributes forwarded from a provider onto the session for
+# backward compatibility (present on SepalSessionProvider / SepalFileProvider,
+# absent -> None for google-auth providers).
+_FORWARDED = (
+    "sepal_headers",
+    "sepal_user_data",
+    "sepal_host",
+    "sepal_session_id",
+    "sepal_api_download_url",
+    "credentials_path",
+)
+
+
+class CredentialMixin:
+    """Holds a :class:`CredentialProvider` and applies its snapshots.
+
+    The provider (SEPAL session, SEPAL file, or google-auth) owns the actual
+    credential logic; this mixin normalizes the result onto the session's
+    ``access_token`` / ``project_id`` / ``expiry_date`` / ``_credentials``
+    surface and delegates refresh.
+    """
+
+    def __init__(self, sepal_headers: Optional[SepalHeaders] = None, *, provider=None):
+        self.max_retries = 3
+        self._credentials = None
+        self._service = None  # backward compatibility
+
+        if provider is not None:
+            self._provider = provider
+        elif sepal_headers is not None:
+            self._provider = SepalSessionProvider(sepal_headers)
+        else:
+            raise EEClientError(
+                "EESession requires a credential source. Call "
+                "EESession.from_default() to resolve credentials from the "
+                "environment, or use an explicit EESession.from_*() factory."
+            )
+
+        prov = self._provider
+        self.auth_mode = prov.auth_mode
+        self.auth_source = getattr(prov, "auth_source", None)
+        self.user = prov.user
+        self.verify_ssl = getattr(prov, "verify_ssl", True)
+        for name in _FORWARDED:
+            setattr(self, name, getattr(prov, name, None))
+
+        self.access_token = None
+        self.project_id = None
+        self.expiry_date = 0
+
+        snap = prov.initial_snapshot()
+        if snap is not None:
+            self._apply_snapshot(snap, initial=True)
+
+        self.logger = logging.getLogger(f"eeclient.{self.user}")
+
+    def _apply_snapshot(
+        self, snap: CredentialSnapshot, *, initial: bool = False
+    ) -> None:
+        self.access_token = snap.access_token
+        self.expiry_date = snap.expiry_date
+        self._credentials = snap.native
+        # Preserve enforce_project_id: on refresh, don't overwrite an enforced
+        # project; on initial population always set it.
+        enforce = getattr(self, "enforce_project_id", False)
+        if initial or not (enforce and self.project_id):
+            self.project_id = snap.project_id
+
+    def is_expired(self) -> bool:
+        """Returns if a token is about to expire."""
+        return (self.expiry_date / 1000) - time.time() < 60
+
+    def needs_credentials_refresh(self) -> bool:
+        """Returns if credentials need to be refreshed (missing or expired)."""
+        return not self._credentials or self.is_expired()
+
+    async def set_credentials(self) -> None:
+        """Refresh credentials via the active provider (async)."""
+        self._apply_snapshot(await self._provider.refresh())
+
+    def set_credentials_sync(self) -> None:
+        """Refresh credentials via the active provider (sync)."""
+        self._apply_snapshot(self._provider.refresh_sync())
+
+
+# Backward-compat alias: SEPAL is now one provider among several.
+SepalCredentialMixin = CredentialMixin

{ee_client-2.6.3 → ee_client-3.0.0}/eeclient/exceptions.py

@@ -92,6 +92,13 @@ class SepalCredentialsUnavailableError(EEClientError):
         super().__init__(error)
 
 
+class CredentialsResolutionError(EEClientError):
+    """Raised when no credential source resolves for a default EESession()."""
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
 # {'code': 401, 'message': 'Request had invalid authentication credentials.
 # Expected OAuth 2 access token, login cookie or other valid authentication
 # credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.',