ee-client 3.2.0__tar.gz → 3.3.0__tar.gz

{ee_client-3.2.0 → ee_client-3.3.0}/PKG-INFO

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

{ee_client-3.2.0 → ee_client-3.3.0}/ee_client.egg-info/PKG-INFO

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

{ee_client-3.2.0 → ee_client-3.3.0}/ee_client.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ eeclient/interfaces/tasks.py
 tests/test_agnostic_auth_integration.py
 tests/test_cache.py
 tests/test_client.py
+tests/test_compute_pixels.py
 tests/test_credential_mixin_close.py
 tests/test_data.py
 tests/test_export_image.py
@@ -39,5 +40,6 @@ tests/test_loop_scoping.py
 tests/test_models.py
 tests/test_providers.py
 tests/test_resolution.py
+tests/test_rest_call_raw.py
 tests/test_tasks.py
 tests/test_tls_verify.py

{ee_client-3.2.0 → ee_client-3.3.0}/eeclient/__init__.py

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

{ee_client-3.2.0 → ee_client-3.3.0}/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.2.0 → ee_client-3.3.0}/eeclient/client.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any, Dict, Literal, Optional
+from typing import Any, Dict, Literal, Optional, Union
 
 import os
 import asyncio
@@ -350,8 +350,15 @@ class EESession(CredentialMixin):
         max_attempts: int = 4,
         initial_wait: float = 1,
         max_wait: float = 60,
-    ) -> Dict[str, Any]:
-        """Async REST call with retry logic"""
+        raw: bool = False,
+    ) -> Union[Dict[str, Any], bytes]:
+        """Async REST call with retry logic.
+
+        ``raw=True`` returns the response body as bytes instead of decoding it
+        as JSON, for endpoints that answer with an image rather than a
+        document (``image:computePixels``). Errors are unaffected: the failure
+        path already inspects ``Content-Type`` before parsing.
+        """
 
         attempt = 0
         last_error = None
@@ -399,6 +406,9 @@ class EESession(CredentialMixin):
                                 )
                                 raise EERestException(error_data)
 
+                        if raw:
+                            return response.content
+
                         try:
                             return response.json()
                         except Exception as e:

{ee_client-3.2.0 → ee_client-3.3.0}/eeclient/data.py

@@ -74,6 +74,64 @@ async def get_map_id_async(
     }
 
 
+async def compute_pixels_async(
+    client: "EESession",
+    ee_image: Image,
+    grid: Optional[dict] = None,
+    bands: Optional[List[str]] = None,
+    file_format: str = "GEO_TIFF",
+    visualization_options: Optional[dict] = None,
+    workload_tag: Optional[str] = None,
+) -> bytes:
+    """Async version of ee.data.computePixels.
+
+    Computes an image and returns its pixels as an encoded file, on this
+    session's credentials rather than the ambient ``ee`` module's, so a
+    multi-user host fetches as the connected user.
+
+    Earth Engine caps a single request at 48 MiB counted on **uncompressed**
+    pixels (width x height x bytes per pixel x bands), independent of how well
+    the result compresses; a larger grid is refused outright. A caller wanting
+    a big area tiles the grid itself and requests each tile in turn. The
+    session's rate limiter and inflight semaphore already meter those requests,
+    and ``rest_call`` already retries 429/401/5xx, so the caller needs no retry
+    loop of its own.
+
+    Args:
+        client: The asynchronous session object.
+        ee_image: The image to compute.
+        grid: The pixel grid to fetch, as ``crsCode`` / ``affineTransform`` /
+            ``dimensions``. Defaults to the data's native grid.
+        bands: The bands to return. Defaults to all of them.
+        file_format: An Earth Engine image file format, ``GEO_TIFF`` by
+            default. The client-side conversions ``ee.data.computePixels``
+            offers (``NUMPY_NDARRAY``) are not applied; this returns the bytes
+            the service sent.
+        visualization_options: Visualization options to apply before the
+            pixels are computed.
+        workload_tag: An optional workload tag.
+
+    Returns:
+        The encoded image, as bytes.
+    """
+    url = "https://earthengine.googleapis.com/v1/projects/{project}/image:computePixels"
+
+    request_body = {
+        "expression": serializer.encode(ee_image, for_cloud_api=True),
+        "fileFormat": _cloud_api_utils.convert_to_image_file_format(file_format),
+    }
+    if grid is not None:
+        request_body["grid"] = grid
+    if bands is not None:
+        request_body["bandIds"] = _cloud_api_utils.convert_to_band_list(bands)
+    if visualization_options is not None:
+        request_body["visualizationOptions"] = visualization_options
+    if workload_tag is not None:
+        request_body["workloadTag"] = workload_tag
+
+    return await client.rest_call("POST", url, data=request_body, raw=True)
+
+
 async def get_info_async(
     client: "EESession",
     ee_object: Union[ComputedObject, None] = None,

{ee_client-3.2.0 → ee_client-3.3.0}/eeclient/interfaces/operations.py

@@ -14,6 +14,16 @@ class OperationsProtocol(Protocol):
         format: Optional[str] = None,
     ) -> dict: ...
 
+    async def compute_pixels_async(
+        self,
+        ee_image: Image,
+        grid: Optional[dict] = None,
+        bands: Optional[List[str]] = None,
+        file_format: str = "GEO_TIFF",
+        visualization_options: Optional[dict] = None,
+        workload_tag: Optional[str] = None,
+    ) -> bytes: ...
+
     async def get_info_async(
         self,
         ee_object: Union[ComputedObject, None] = None,

{ee_client-3.2.0 → ee_client-3.3.0}/pyproject.toml

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

{ee_client-3.2.0 → ee_client-3.3.0}/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.3.0/tests/test_compute_pixels.py

@@ -0,0 +1,97 @@
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from eeclient.data import compute_pixels_async
+
+FAKE_EXPRESSION = {"values": {}, "result": "0"}
+GRID = {
+    "dimensions": {"width": 256, "height": 256},
+    "affineTransform": {
+        "scaleX": 0.00025,
+        "shearX": 0,
+        "translateX": 16.0,
+        "shearY": 0,
+        "scaleY": -0.00025,
+        "translateY": 1.4,
+    },
+    "crsCode": "EPSG:4326",
+}
+
+
+def _client(payload=b"\x49\x49\x2a\x00tiff bytes"):
+    client = AsyncMock()
+    client.rest_call = AsyncMock(return_value=payload)
+    return client
+
+
+async def _compute(client, **kwargs):
+    with patch("eeclient.data.serializer.encode", return_value=FAKE_EXPRESSION):
+        return await compute_pixels_async(client=client, ee_image=object(), **kwargs)
+
+
+@pytest.mark.asyncio
+async def test_returns_the_bytes_the_service_sent():
+    client = _client()
+
+    result = await _compute(client, grid=GRID, bands=["lossyear"])
+
+    assert result == b"\x49\x49\x2a\x00tiff bytes"
+
+
+@pytest.mark.asyncio
+async def test_posts_to_the_compute_pixels_endpoint_asking_for_raw_bytes():
+    client = _client()
+
+    await _compute(client, grid=GRID, bands=["lossyear"])
+
+    assert client.rest_call.await_count == 1
+    args, kwargs = client.rest_call.call_args
+    assert args[0] == "POST"
+    assert args[1].endswith("/image:computePixels")
+    # the response is an image, so it must not be decoded as JSON
+    assert kwargs["raw"] is True
+
+
+@pytest.mark.asyncio
+async def test_sends_expression_grid_bands_and_format():
+    client = _client()
+
+    await _compute(client, grid=GRID, bands=["lossyear"])
+
+    payload = client.rest_call.call_args.kwargs["data"]
+    assert payload["expression"] == FAKE_EXPRESSION
+    assert payload["fileFormat"] == "GEO_TIFF"
+    assert payload["grid"] == GRID
+    assert payload["bandIds"] == ["lossyear"]
+
+
+@pytest.mark.asyncio
+async def test_omits_the_optional_fields_when_they_are_not_given():
+    client = _client()
+
+    await _compute(client)
+
+    payload = client.rest_call.call_args.kwargs["data"]
+    assert set(payload) == {"expression", "fileFormat"}
+
+
+@pytest.mark.asyncio
+async def test_passes_visualization_options_and_workload_tag_through():
+    client = _client()
+    vis = {"ranges": [{"min": 0, "max": 23}]}
+
+    await _compute(client, visualization_options=vis, workload_tag="sbae")
+
+    payload = client.rest_call.call_args.kwargs["data"]
+    assert payload["visualizationOptions"] == vis
+    assert payload["workloadTag"] == "sbae"
+
+
+@pytest.mark.asyncio
+async def test_a_single_band_string_is_accepted_as_a_band_list():
+    client = _client()
+
+    await _compute(client, bands="lossyear")
+
+    assert client.rest_call.call_args.kwargs["data"]["bandIds"] == ["lossyear"]

ee_client-3.3.0/tests/test_rest_call_raw.py

@@ -0,0 +1,107 @@
+"""``rest_call(raw=True)`` hands back the response body undecoded.
+
+``image:computePixels`` answers with an encoded image, not a document, so the
+JSON decode at the end of ``rest_call`` has to be skippable. These tests drive
+a real local HTTP server rather than a mock, so the bytes make the whole round
+trip through httpx exactly as they would against Earth Engine.
+"""
+
+import asyncio
+import json
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import pytest
+
+from eeclient.client import EESession
+from eeclient.exceptions import EERestException
+from eeclient.providers import CredentialSnapshot
+
+# a TIFF magic number followed by bytes that are not valid UTF-8, so a decode
+# attempt anywhere along the way would fail loudly instead of silently passing
+TIFF_BYTES = b"II*\x00" + bytes(range(256))
+
+
+class _StubProvider:
+    """Credentials that never expire and never touch the network."""
+
+    auth_mode = "stub"
+    auth_source = "stub"
+    user = "tester"
+    verify_ssl = True
+
+    def initial_snapshot(self):
+        return CredentialSnapshot(
+            access_token="token",
+            project_id="ee-project",
+            expiry_date=int((time.time() + 3600) * 1000),
+            native=object(),
+        )
+
+    def refresh_sync(self):
+        raise AssertionError("credentials must not be refreshed in these tests")
+
+    async def refresh(self):
+        raise AssertionError("credentials must not be refreshed in these tests")
+
+
+class _Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def do_POST(self):
+        length = int(self.headers.get("Content-Length", 0))
+        self.rfile.read(length)
+
+        if self.path.endswith("/boom"):
+            body = json.dumps({"error": {"code": 400, "message": "bad grid"}}).encode()
+            self.send_response(400)
+            self.send_header("Content-Type", "application/json")
+        else:
+            body = TIFF_BYTES
+            self.send_response(200)
+            self.send_header("Content-Type", "image/tiff")
+
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, *args):
+        pass
+
+
+@pytest.fixture(scope="module")
+def base_url():
+    server = ThreadingHTTPServer(("127.0.0.1", 0), _Handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    yield f"http://127.0.0.1:{server.server_address[1]}"
+    server.shutdown()
+
+
+@pytest.fixture()
+def session():
+    return EESession(_provider=_StubProvider())
+
+
+def test_raw_returns_the_body_verbatim(session, base_url):
+    result = asyncio.run(session.rest_call("POST", f"{base_url}/pixels", raw=True))
+
+    assert isinstance(result, bytes)
+    assert result == TIFF_BYTES
+
+
+def test_without_raw_the_same_body_is_rejected_as_json(session, base_url):
+    """The guard that makes `raw` necessary: bytes are not a document."""
+    with pytest.raises(EERestException) as excinfo:
+        asyncio.run(session.rest_call("POST", f"{base_url}/pixels"))
+
+    assert "Invalid JSON response" in str(excinfo.value)
+
+
+def test_raw_still_raises_on_an_error_response(session, base_url):
+    """A failure is JSON even when success is not, and must not reach the caller
+    as bytes."""
+    with pytest.raises(EERestException) as excinfo:
+        asyncio.run(session.rest_call("POST", f"{base_url}/boom", raw=True))
+
+    assert excinfo.value.code == 400