ee-client 3.1.2__tar.gz → 3.2.1__tar.gz

{ee_client-3.1.2 → ee_client-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ee-client
-Version: 3.1.2
+Version: 3.2.1
 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

{ee_client-3.1.2 → ee_client-3.2.1}/ee_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ee-client
-Version: 3.1.2
+Version: 3.2.1
 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

{ee_client-3.1.2 → ee_client-3.2.1}/ee_client.egg-info/SOURCES.txt

@@ -31,6 +31,7 @@ tests/test_client.py
 tests/test_credential_mixin_close.py
 tests/test_data.py
 tests/test_export_image.py
+tests/test_export_image_pyramiding.py
 tests/test_export_table.py
 tests/test_factories.py
 tests/test_integration_get_assets.py

{ee_client-3.1.2 → ee_client-3.2.1}/eeclient/__init__.py

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

{ee_client-3.1.2 → ee_client-3.2.1}/eeclient/cache.py

@@ -1,4 +1,5 @@
 import asyncio
+import contextlib
 import hashlib
 import json
 import time
@@ -19,6 +20,7 @@ class CacheEntry:
         self.error = error
         self.task = task
         self.timestamp = time.time()
+        self.waiters = 0
 
     def is_expired(self, ttl: float) -> bool:
         """Check if the cache entry has exceeded its TTL."""
@@ -65,49 +67,51 @@ class ResponseCache:
         Returns:
             The cached or freshly fetched result
         """
-        # Check cache and get task reference if needed
         async with self._lock:
-            if key in self._cache:
-                entry = self._cache[key]
-
-                # If there's an in-flight task, we'll wait for it
-                if entry.task and not entry.task.done():
-                    in_flight_task = entry.task
-                elif not entry.is_expired(self.ttl):
-                    # Valid cached result - return it
+            entry = self._cache.get(key)
+            if entry is not None and entry.task is not None and entry.task.done():
+                # Its starter was cancelled before it could settle the entry.
+                self._settle(key, entry)
+                entry = self._cache.get(key)
+            if entry is not None and entry.task is None:
+                if not entry.is_expired(self.ttl):
                     self._cache.move_to_end(key)
                     return entry.get_result()
-                else:
-                    # Expired entry - remove it and fetch new
-                    del self._cache[key]
-                    in_flight_task = None
-            else:
-                in_flight_task = None
-
-            # No in-flight task - create a new one
-            if in_flight_task is None:
+                del self._cache[key]
+                entry = None
+            if entry is None:
                 task = asyncio.create_task(fetch_func(*args, **kwargs))
-                self._cache[key] = CacheEntry(task=task)
+                entry = CacheEntry(task=task)
+                self._cache[key] = entry
+                task.add_done_callback(lambda _: self._settle(key, entry))
 
                 # LRU eviction
                 while len(self._cache) > self.max_size:
                     self._cache.popitem(last=False)
-            else:
-                # Use the existing in-flight task
-                task = in_flight_task
+            entry.waiters += 1
 
-        # Wait for the task outside the lock to avoid deadlock
+        # Shielded, so one cancelled caller does not cancel the fetch the others
+        # (and the cache) wait on. The last caller to leave cancels it instead: a
+        # fetch must not outlive its callers, nor its loop.
         try:
-            result = await task
-            async with self._lock:
-                if key in self._cache:
-                    self._cache[key] = CacheEntry(value=result)
-            return result
-        except Exception as e:
-            async with self._lock:
-                if key in self._cache:
-                    self._cache[key] = CacheEntry(error=e)
-            raise
+            return await asyncio.shield(entry.task)
+        finally:
+            entry.waiters -= 1
+            if entry.waiters == 0 and not entry.task.done():
+                entry.task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await asyncio.wait({entry.task})
+
+    def _settle(self, key: str, entry: CacheEntry) -> None:
+        """Keep what a finished fetch produced, or drop it when it was cancelled."""
+        if self._cache.get(key) is not entry or not entry.task.done():
+            return
+        if entry.task.cancelled():
+            del self._cache[key]
+        elif entry.task.exception() is not None:
+            self._cache[key] = CacheEntry(error=entry.task.exception())
+        else:
+            self._cache[key] = CacheEntry(value=entry.task.result())
 
     def clear(self):
         """Clear all cached entries."""

{ee_client-3.1.2 → ee_client-3.2.1}/eeclient/export/image.py

@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import TYPE_CHECKING, Optional, Union
+from typing import TYPE_CHECKING, Dict, Optional, Union
 from pydantic import BaseModel, ConfigDict, field_validator, model_validator
 from pydantic.alias_generators import to_camel
 
@@ -66,8 +66,34 @@ class DriveOptions(BaseExportModel):
     # See the api: https://developers.google.com/earth-engine/reference/rest/v1alpha/ImageFileExportOptions
 
 
+class PyramidingPolicy(str, Enum):
+    """Reducer that builds an asset's overview levels.
+
+    The server default is ``MEAN``, which averages class codes across every
+    overview of a categorical image and renders it wrong below native zoom.
+    Such images want ``MODE`` or ``SAMPLE``.
+    """
+
+    MEAN = "MEAN"
+    SAMPLE = "SAMPLE"
+    MIN = "MIN"
+    MAX = "MAX"
+    MODE = "MODE"
+    MEDIAN = "MEDIAN"
+
+    @classmethod
+    def _missing_(cls, value):
+        # ``ee.batch`` upper-cases whatever the caller passes, so callers are
+        # used to writing "mode".
+        if isinstance(value, str):
+            return cls.__members__.get(value.upper())
+        return None
+
+
 class AssetOptions(BaseExportModel):
     earth_engine_destination: EarthEngineDestination
+    pyramiding_policy: Optional[PyramidingPolicy] = None
+    pyramiding_policy_overrides: Optional[Dict[str, PyramidingPolicy]] = None
 
 
 class GridDimensions(BaseModel):
@@ -267,6 +293,8 @@ async def image_to_asset_async(
     scale: Optional[float] = None,
     crs: Optional[str] = None,
     crs_transform: Optional[AffineTransform] = None,
+    pyramiding_policy: Optional[PyramidingPolicy] = None,
+    pyramiding_policy_overrides: Optional[Dict[str, PyramidingPolicy]] = None,
 ) -> Task:
     """Abstracts the export of an image to Earth Engine Asset.
 
@@ -275,6 +303,8 @@ async def image_to_asset_async(
     """
     asset_options = AssetOptions(
         earth_engine_destination=EarthEngineDestination(name=asset_id),
+        pyramiding_policy=pyramiding_policy,
+        pyramiding_policy_overrides=pyramiding_policy_overrides,
     )
 
     return await _export_image(

{ee_client-3.1.2 → ee_client-3.2.1}/eeclient/interfaces/export.py

@@ -1,5 +1,10 @@
-from typing import Optional, Protocol, Union, Any
-from eeclient.export.image import ImageFileFormat, PixelGrid, AffineTransform
+from typing import Any, Dict, Optional, Protocol, Union
+from eeclient.export.image import (
+    AffineTransform,
+    ImageFileFormat,
+    PixelGrid,
+    PyramidingPolicy,
+)
 from eeclient.export.table import TableFileFormat
 
 
@@ -18,6 +23,8 @@ class ExportProtocol(Protocol):
         scale: Optional[float] = ...,
         crs: Optional[str] = ...,
         crs_transform: Optional[AffineTransform] = ...,
+        pyramiding_policy: Optional[PyramidingPolicy] = ...,
+        pyramiding_policy_overrides: Optional[Dict[str, PyramidingPolicy]] = ...,
     ) -> dict: ...
 
     async def image_to_drive_async(

{ee_client-3.1.2 → ee_client-3.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ee-client"
-version = "3.1.2"
+version = "3.2.1"
 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 = "3.1.2"
+version = "3.2.1"
 version_files = [
     "pyproject.toml:version",
     "eeclient/__init__.py:__version__",

{ee_client-3.1.2 → ee_client-3.2.1}/tests/test_cache.py

@@ -250,3 +250,76 @@ async def test_get_assets_concurrent_deduplication():
         assert all(len(r) == 1 for r in results)
         assert all(r[0]["id"] == "test_id" for r in results)
         assert call_count == 1
+
+
+# Cancellation
+
+
+async def _cancel(task):
+    task.cancel()
+    await asyncio.gather(task, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+async def test_cache_cancelled_caller_leaves_no_stale_none():
+    """A second call within the TTL must fetch again, not read a cancelled entry."""
+    cache = ResponseCache(ttl=10.0, max_size=100)
+    call_count = 0
+
+    async def fetch_data():
+        nonlocal call_count
+        call_count += 1
+        await asyncio.sleep(0.05)
+        return ["asset"]
+
+    key = cache.make_cache_key("folder")
+    first = asyncio.create_task(cache.get_or_fetch(key, fetch_data))
+    await asyncio.sleep(0.01)
+    await _cancel(first)
+
+    assert await cache.get_or_fetch(key, fetch_data) == ["asset"]
+    assert call_count == 2
+
+
+@pytest.mark.asyncio
+async def test_cache_last_caller_to_leave_cancels_the_fetch():
+    """A fetch nobody waits for must not run on, nor stay in the cache."""
+    cache = ResponseCache(ttl=10.0, max_size=100)
+    cancelled = asyncio.Event()
+
+    async def fetch_data():
+        try:
+            await asyncio.sleep(300)
+        except asyncio.CancelledError:
+            cancelled.set()
+            raise
+
+    key = cache.make_cache_key("folder")
+    caller = asyncio.create_task(cache.get_or_fetch(key, fetch_data))
+    await asyncio.sleep(0.01)
+    await _cancel(caller)
+
+    assert cancelled.is_set()
+    assert key not in cache._cache
+
+
+@pytest.mark.asyncio
+async def test_cache_cancelled_caller_does_not_cancel_the_others():
+    """Callers deduplicated onto one fetch must not lose it when one of them leaves."""
+    cache = ResponseCache(ttl=10.0, max_size=100)
+    call_count = 0
+
+    async def fetch_data():
+        nonlocal call_count
+        call_count += 1
+        await asyncio.sleep(0.05)
+        return ["asset"]
+
+    key = cache.make_cache_key("folder")
+    leaver = asyncio.create_task(cache.get_or_fetch(key, fetch_data))
+    stayer = asyncio.create_task(cache.get_or_fetch(key, fetch_data))
+    await asyncio.sleep(0.01)
+    await _cancel(leaver)
+
+    assert await asyncio.wait_for(stayer, timeout=5.0) == ["asset"]
+    assert call_count == 1

ee_client-3.2.1/tests/test_export_image_pyramiding.py

@@ -0,0 +1,96 @@
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from eeclient.export.image import (
+    AssetOptions,
+    EarthEngineDestination,
+    PyramidingPolicy,
+    image_to_asset_async,
+)
+from eeclient.interfaces.export import ExportProtocol
+
+
+def _asset_options(**kwargs):
+    return AssetOptions(
+        earth_engine_destination=EarthEngineDestination(name="projects/p/assets/x"),
+        **kwargs,
+    )
+
+
+def test_asset_options_omit_pyramiding_by_default():
+    dumped = _asset_options().model_dump(by_alias=True, exclude_none=True)
+    assert "pyramidingPolicy" not in dumped
+    assert "pyramidingPolicyOverrides" not in dumped
+
+
+def test_asset_options_serialize_default_policy_as_camel_case():
+    dumped = _asset_options(pyramiding_policy="MODE").model_dump(
+        by_alias=True, exclude_none=True
+    )
+    assert dumped["pyramidingPolicy"] == "MODE"
+
+
+def test_asset_options_serialize_per_band_overrides():
+    dumped = _asset_options(pyramiding_policy_overrides={"B1": "MIN"}).model_dump(
+        by_alias=True, exclude_none=True
+    )
+    assert dumped["pyramidingPolicyOverrides"] == {"B1": "MIN"}
+
+
+def test_asset_options_accept_lowercase_policy():
+    """`ee.batch` upper-cases whatever the caller passes, so callers write "mode"."""
+    opts = _asset_options(
+        pyramiding_policy="mode", pyramiding_policy_overrides={"B1": "min"}
+    )
+    assert opts.pyramiding_policy is PyramidingPolicy.MODE
+    assert opts.pyramiding_policy_overrides == {"B1": PyramidingPolicy.MIN}
+
+
+def test_asset_options_reject_unknown_policy():
+    with pytest.raises(ValueError):
+        _asset_options(pyramiding_policy="average")
+
+
+def test_asset_options_reject_unknown_override_policy():
+    with pytest.raises(ValueError):
+        _asset_options(pyramiding_policy_overrides={"B1": "average"})
+
+
+@pytest.mark.asyncio
+async def test_image_to_asset_async_forwards_pyramiding_to_the_request():
+    image = MagicMock(name="image")
+    image._apply_crs_and_affine.return_value = (image, {}, False)
+    image._apply_selection_and_scale.return_value = (image, {})
+
+    client = MagicMock()
+    client.rest_call = AsyncMock(return_value={})
+
+    with (
+        patch("eeclient.export.image.serializer.encode", return_value={}),
+        patch("eeclient.export.image.Task.model_validate", return_value=MagicMock()),
+    ):
+        await image_to_asset_async(
+            client=client,
+            image=image,
+            asset_id="projects/p/assets/x",
+            pyramiding_policy="mode",
+            pyramiding_policy_overrides={"B1": "min"},
+        )
+
+    # Asserted through json, because `rest_call` hands `data` to httpx as
+    # `json=` -- a policy that stringified as "PyramidingPolicy.MODE" would
+    # still compare equal to "MODE" here as a str enum.
+    body = json.loads(json.dumps(client.rest_call.await_args.kwargs["data"]))
+    asset_options = body["assetExportOptions"]
+    assert asset_options["pyramidingPolicy"] == "MODE"
+    assert asset_options["pyramidingPolicyOverrides"] == {"B1": "MIN"}
+
+
+@pytest.mark.parametrize("param", ["pyramiding_policy", "pyramiding_policy_overrides"])
+def test_export_protocol_matches_the_implementation(param):
+    """`session.export.*` dispatches through the Protocol, so it must agree."""
+    import inspect
+
+    assert param in inspect.signature(ExportProtocol.image_to_asset_async).parameters