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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ee-client
-Version: 3.2.1
+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.1 → 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.1
+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.1 → 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.1 → ee_client-3.3.0}/eeclient/__init__.py

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

{ee_client-3.2.1 → 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.1 → 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.1 → 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.1 → ee_client-3.3.0}/pyproject.toml

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

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