ee-client 2.0.3__tar.gz → 2.1.0__tar.gz

{ee_client-2.0.3 → ee_client-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ee-client
-Version: 2.0.3
+Version: 2.1.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
@@ -32,15 +32,22 @@ Dynamic: license-file
 Earth Engine Client 🌎
 ==============================
 
-The **Earth Engine Session Client** is a Python package that extends the Google Earth Engine (GEE) API by introducing multi-user session management through a custom authentication. 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.
+The **Earth Engine Session Client** is a Python package that extends the Google Earth Engine (GEE) API by introducing multi-user session management through custom authentication. 
+
+**Why This Package?**
+
+While Google Earth Engine applications can be created using a global service account, this approach has significant limitations: users cannot access their private GEE assets without making them public. This package solves this problem by handling custom authentication, allowing each user to access their own private assets securely.
+
+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.
 
 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.
-- **Custom Session Management**: Encapsulate user-specific credentials and project data in an ``EESession`` object.
+- **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.
   - ``get_map_id``: Generate a map ID for an Earth Engine image.

{ee_client-2.0.3 → ee_client-2.1.0}/README.rst

@@ -1,15 +1,22 @@
 Earth Engine Client 🌎
 ==============================
 
-The **Earth Engine Session Client** is a Python package that extends the Google Earth Engine (GEE) API by introducing multi-user session management through a custom authentication. 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.
+The **Earth Engine Session Client** is a Python package that extends the Google Earth Engine (GEE) API by introducing multi-user session management through custom authentication. 
+
+**Why This Package?**
+
+While Google Earth Engine applications can be created using a global service account, this approach has significant limitations: users cannot access their private GEE assets without making them public. This package solves this problem by handling custom authentication, allowing each user to access their own private assets securely.
+
+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.
 
 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.
-- **Custom Session Management**: Encapsulate user-specific credentials and project data in an ``EESession`` object.
+- **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.
   - ``get_map_id``: Generate a map ID for an Earth Engine image.

{ee_client-2.0.3 → ee_client-2.1.0}/ee_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ee-client
-Version: 2.0.3
+Version: 2.1.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
@@ -32,15 +32,22 @@ Dynamic: license-file
 Earth Engine Client 🌎
 ==============================
 
-The **Earth Engine Session Client** is a Python package that extends the Google Earth Engine (GEE) API by introducing multi-user session management through a custom authentication. 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.
+The **Earth Engine Session Client** is a Python package that extends the Google Earth Engine (GEE) API by introducing multi-user session management through custom authentication. 
+
+**Why This Package?**
+
+While Google Earth Engine applications can be created using a global service account, this approach has significant limitations: users cannot access their private GEE assets without making them public. This package solves this problem by handling custom authentication, allowing each user to access their own private assets securely.
+
+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.
 
 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.
-- **Custom Session Management**: Encapsulate user-specific credentials and project data in an ``EESession`` object.
+- **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.
   - ``get_map_id``: Generate a map ID for an Earth Engine image.

{ee_client-2.0.3 → ee_client-2.1.0}/ee_client.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ eeclient/exceptions.py
 eeclient/helpers.py
 eeclient/models.py
 eeclient/oauth_app.py
+eeclient/sepal_credential_mixin.py
 eeclient/tasks.py
 eeclient/export/__init__.py
 eeclient/export/image.py

{ee_client-2.0.3 → ee_client-2.1.0}/eeclient/__init__.py

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

{ee_client-2.0.3 → ee_client-2.1.0}/eeclient/client.py

@@ -9,6 +9,7 @@ from contextlib import asynccontextmanager
 
 from eeclient.exceptions import EEClientError, EERestException
 from eeclient.models import GEEHeaders, GoogleTokens, SepalHeaders
+from eeclient.sepal_credential_mixin import SepalCredentialMixin
 
 import eeclient.export as _export_module
 import eeclient.data as _operations_module
@@ -33,7 +34,7 @@ SEPAL_API_DOWNLOAD_URL = None
 VERIFY_SSL = True
 
 
-class EESession:
+class EESession(SepalCredentialMixin):
     def __init__(self, sepal_headers: SepalHeaders, enforce_project_id: bool = True):
         """Session that handles two scenarios to set the headers for Earth Engine API
 
@@ -48,38 +49,17 @@ class EESession:
         Raises:
             ValueError: If SEPAL_HOST environment variable is not set
         """
-        # Get and validate environment variables that are required for the session
-        self.sepal_host = os.getenv("SEPAL_HOST")
-        if not self.sepal_host:
-            raise ValueError("SEPAL_HOST environment variable not set")
-
-        self.sepal_api_download_url = (
-            f"https://{self.sepal_host}/api/user-files/download/"
-            "?path=%2F.config%2Fearthengine%2Fcredentials"
-        )
-        self.verify_ssl = not (
-            self.sepal_host == "host.docker.internal"
-            or self.sepal_host == "danielg.sepal.io"
-        )
+        super().__init__(sepal_headers)
 
-        self.expiry_date = 0
         self.max_retries = 3
         self._credentials = None
-
         self.enforce_project_id = enforce_project_id
-        self.sepal_headers = SepalHeaders.model_validate(sepal_headers)
-        self.sepal_session_id = self.sepal_headers.cookies["SEPAL-SESSIONID"]
-        self.sepal_user_data = self.sepal_headers.sepal_user
-        self.user = self.sepal_user_data.username
 
         # Create user-specific logger
         self.logger = logging.getLogger(f"eeclient.{self.user}")
 
         # Initialize credentials from the initial tokens
-        self._google_tokens = self.sepal_user_data.google_tokens
         if self._google_tokens:
-            self.expiry_date = self._google_tokens.access_token_expiry_date
-            self.project_id = self._google_tokens.project_id
             self._credentials = self._google_tokens
         else:
             self._credentials = None
@@ -118,7 +98,7 @@ class EESession:
         return await session.initialize()
 
     async def get_assets_folder(self) -> str:
-        if self.is_expired():
+        if self.needs_credentials_refresh():
             await self.set_credentials()
         return f"projects/{self.project_id}/assets/"
 
@@ -126,6 +106,10 @@ class EESession:
         """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()
+
     def get_current_headers(self) -> GEEHeaders:
         """Get current headers without refreshing credentials"""
         if not self._credentials:
@@ -143,7 +127,7 @@ class EESession:
 
     async def get_headers(self) -> GEEHeaders:
         """Async method to get headers, refreshing credentials if needed"""
-        if self.is_expired():
+        if self.needs_credentials_refresh():
             await self.set_credentials()
         return self.get_current_headers()
 
@@ -246,9 +230,12 @@ class EESession:
             try:
                 async with self.get_client() as client:
                     url_with_project = self.set_url_project(url)
-                    self.logger.debug(
-                        f"Making async (asdf) {method} request to {url_with_project}"
-                    )
+
+                    if "assets" not in url_with_project:
+                        # Do not log assets requests
+                        self.logger.debug(
+                            f"Making async  {method} request to {url_with_project}"
+                        )
                     response = await client.request(
                         method, url_with_project, json=data, params=params
                     )

{ee_client-2.0.3 → ee_client-2.1.0}/eeclient/export/image.py

@@ -9,6 +9,7 @@ if TYPE_CHECKING:
 from ee import serializer
 import ee
 import logging
+from eeclient.tasks import Task
 
 log = logging.getLogger("eeclient.export.image")
 
@@ -127,11 +128,14 @@ async def _export_image(
     scale: Optional[float] = None,
     crs: Optional[str] = None,
     crs_transform: Optional[AffineTransform] = None,
-) -> dict:
+) -> Task:
     """
-    Export a table to either Google Drive or Earth Engine Asset.
+    Export an image to either Google Drive or Earth Engine Asset.
 
     Exactly one of drive_options or asset_options must be provided.
+
+    Returns:
+        Task: The export task response from the API
     """
     if (drive_options is None and asset_options is None) or (
         drive_options is not None and asset_options is not None
@@ -177,7 +181,8 @@ async def _export_image(
     log.debug(f"Exporting image with params: {request_params}")
 
     url = "{earth_engine_api_url}/projects/{project}/image:export"
-    return await client.rest_call("POST", url, data=request_params)
+    response_data = await client.rest_call("POST", url, data=request_params)
+    return Task.model_validate(response_data)
 
 
 async def image_to_drive_async(
@@ -198,8 +203,12 @@ async def image_to_drive_async(
     scale: Optional[float] = None,
     crs: Optional[str] = None,
     crs_transform: Optional[AffineTransform] = None,
-) -> dict:
-    """Abstracts the export of an image to Google Drive."""
+) -> Task:
+    """Abstracts the export of an image to Google Drive.
+
+    Returns:
+        Task: The export task response from the API
+    """
     drive_options = DriveOptions(
         file_format=file_format,
         drive_destination=DriveDestination(
@@ -240,8 +249,12 @@ async def image_to_asset_async(
     scale: Optional[float] = None,
     crs: Optional[str] = None,
     crs_transform: Optional[AffineTransform] = None,
-) -> dict:
-    """Abstracts the export of an image to Earth Engine Asset."""
+) -> Task:
+    """Abstracts the export of an image to Earth Engine Asset.
+
+    Returns:
+        Task: The export task response from the API
+    """
     asset_options = AssetOptions(
         earth_engine_destination=EarthEngineDestination(name=asset_id),
     )

{ee_client-2.0.3 → ee_client-2.1.0}/eeclient/export/table.py

@@ -7,6 +7,7 @@ if TYPE_CHECKING:
     from eeclient.client import EESession
 
 from ee import serializer, encodable
+from eeclient.tasks import Task
 
 
 class TableFileFormat(str, Enum):
@@ -75,11 +76,14 @@ async def _export_table(
     max_vertices: Optional[int] = None,
     workload_tag: Optional[str] = None,
     priority: Optional[int] = None,
-) -> dict:
+) -> Task:
     """
     Export a table to either Google Drive or Earth Engine Asset.
 
     Exactly one of drive_options or asset_options must be provided.
+
+    Returns:
+        Task: The export task response from the API
     """
     if (drive_options is None and asset_options is None) or (
         drive_options is not None and asset_options is not None
@@ -107,24 +111,30 @@ async def _export_table(
     params = export_options.model_dump(by_alias=True, exclude_none=True)
 
     url = "{earth_engine_api_url}/projects/{project}/table:export"
-    return await client.rest_call("POST", url, data=params)
+    response_data = await client.rest_call("POST", url, data=params)
+    return Task.model_validate(response_data)
 
 
 async def table_to_drive_async(
     client: "EESession",
     collection,
-    filename_prefix: str,
     file_format: TableFileFormat,
+    filename_prefix: str = "",
     folder: Optional[str] = None,
     description: str = "myExportTableTask",
     selectors: Optional[list] = None,
     max_vertices: Optional[int] = None,
     priority: Optional[int] = None,
-) -> dict:
+) -> Task:
     """
     Export a table to Google Drive.
+
+    Returns:
+        Task: The export task response from the API
     """
-    drive_destination = DriveDestination(filename_prefix=filename_prefix, folder=folder)
+    drive_destination = DriveDestination(
+        filename_prefix=filename_prefix or description, folder=folder
+    )
     drive_options = DriveOptions(
         file_format=file_format, drive_destination=drive_destination
     )
@@ -148,9 +158,12 @@ async def table_to_asset_async(
     selectors: Optional[list] = None,
     max_vertices: Optional[int] = None,
     priority: Optional[int] = None,
-) -> dict:
+) -> Task:
     """
     Export a table to Earth Engine Asset.
+
+    Returns:
+        Task: The export task response from the API
     """
     asset_options = AssetOptions(
         earth_engine_destination=EarthEngineDestination(name=asset_id)

{ee_client-2.0.3 → ee_client-2.1.0}/eeclient/helpers.py

@@ -2,7 +2,7 @@ import os
 import requests
 import logging
 from eeclient.models import SepalHeaders, SepalUser
-from typing import Union
+from typing import Optional, Union
 
 from ee.imagecollection import ImageCollection
 from ee.feature import Feature
@@ -59,11 +59,17 @@ def parse_cookie_string(cookie_string):
     return cookies
 
 
-def get_sepal_headers_from_auth():
+def get_sepal_headers_from_auth(
+    sepal_user: Optional[str] = None,
+    sepal_password: Optional[str] = None,
+    sepal_host: Optional[str] = None,
+) -> SepalHeaders:
+
     log.debug("Getting SEPAL headers from authentication")
-    sepal_user = os.getenv("LOCAL_SEPAL_USER")
-    sepal_password = os.getenv("LOCAL_SEPAL_PASSWORD")
-    sepal_host = os.getenv("SEPAL_HOST")
+
+    sepal_user = sepal_user or os.getenv("LOCAL_SEPAL_USER")
+    sepal_password = sepal_password or os.getenv("LOCAL_SEPAL_PASSWORD")
+    sepal_host = sepal_host or os.getenv("SEPAL_HOST")
 
     if not sepal_user or not sepal_password or not sepal_host:
         raise ValueError(

ee_client-2.1.0/eeclient/sepal_credential_mixin.py

@@ -0,0 +1,37 @@
+from eeclient.models import SepalHeaders
+import os
+import logging
+
+log = logging.getLogger("eeclient")
+
+
+class SepalCredentialMixin:
+    def __init__(self, sepal_headers: SepalHeaders):
+        log.debug("Initializing GDriveInterface with SEPAL headers")
+        self.sepal_host = os.getenv("SEPAL_HOST")
+        if not self.sepal_host:
+            raise ValueError("SEPAL_HOST environment variable not set")
+
+        self.sepal_headers = SepalHeaders.model_validate(sepal_headers)
+        self.sepal_session_id = self.sepal_headers.cookies["SEPAL-SESSIONID"]
+        self.sepal_user_data = self.sepal_headers.sepal_user
+        self.user = self.sepal_user_data.username
+
+        self.sepal_api_download_url = (
+            f"https://{self.sepal_host}/api/user-files/download/"
+            "?path=%2F.config%2Fearthengine%2Fcredentials"
+        )
+        self.verify_ssl = not (
+            self.sepal_host == "host.docker.internal"
+            or self.sepal_host == "danielg.sepal.io"
+        )
+
+        self._google_tokens = self.sepal_user_data.google_tokens
+        if self._google_tokens:
+            self.access_token = self._google_tokens.access_token
+            self.project_id = self._google_tokens.project_id
+            self.expiry_date = self._google_tokens.access_token_expiry_date
+        else:
+            self.access_token = None
+            self.project_id = None
+            self.expiry_date = 0

{ee_client-2.0.3 → ee_client-2.1.0}/eeclient/tasks.py

@@ -3,7 +3,7 @@ from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from eeclient.client import EESession
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, computed_field
 from typing import List, Optional, Any
 from datetime import datetime
 
@@ -31,7 +31,7 @@ class Stage(CamelCaseModel):
 
 class TaskMetadata(CamelCaseModel):
     type_info: str = Field(alias="@type")
-    state: str
+    state: Optional[str] = None
     description: str
     priority: int
     create_time: datetime
@@ -40,7 +40,7 @@ class TaskMetadata(CamelCaseModel):
     end_time: Optional[datetime] = None
     type: str
     destination_uris: Optional[List[str]] = None
-    attempt: int
+    attempt: Optional[int] = None
     progress: Optional[float] = None
     stages: Optional[List[Stage]] = None
     batch_eecu_usage_seconds: Optional[float] = None
@@ -55,9 +55,20 @@ class Task(CamelCaseModel):
     metadata: TaskMetadata
     done: Optional[bool] = None
     response: Optional[Response] = None
-    # Add error field which might be present instead of response
     error: Optional[Any] = None
 
+    @computed_field
+    @property
+    def id(self) -> str:
+        """Extract the task ID from the name field.
+
+        The name field has format: 'projects/{project}/operations/{task_id}'
+        This property extracts just the {task_id} part.
+        """
+        if "/operations/" in self.name:
+            return self.name.split("/operations/")[-1]
+        return self.name
+
 
 class TasksResponse(CamelCaseModel):
     operations: List[Task]
@@ -79,7 +90,7 @@ async def get_tasks_async(client: "EESession") -> TasksResponse:
     return operations_response
 
 
-async def get_task_async(client: "EESession", task_id: str):
+async def get_task_async(client: "EESession", task_id: str) -> Optional[Task]:
     """Search for the described task in the user Task list return None if
     nothing is found.
 

{ee_client-2.0.3 → ee_client-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ee-client"
-version = "2.0.3"
+version = "2.1.0"
 description = "extends the capabilities of the earthengine-api by providing custom session management and client interactions"
 readme = { file = "README.rst",  content-type = "text/x-rst" }
 authors = [
@@ -66,7 +66,7 @@ branch = true
 [tool.commitizen]
 tag_format = "v$major.$minor.$patch$prerelease"
 update_changelog_on_bump = false
-version = "2.0.3"
+version = "2.1.0"
 version_files = [
     "pyproject.toml:version",
     "eeclient/__init__.py:__version__",