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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ee-client
-Version: 3.1.2
+Version: 3.2.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.1.2 → ee_client-3.2.0}/ee_client.egg-info/PKG-INFO

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

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

{ee_client-3.1.2 → ee_client-3.2.0}/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.0}/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.0}/pyproject.toml

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

ee_client-3.2.0/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