datacosmos 0.0.16__py3-none-any.whl → 0.0.18__py3-none-any.whl

datacosmos/datacosmos_client.py

@@ -1,9 +1,10 @@
 """Client to interact with the Datacosmos API with authentication and request handling."""
 from __future__ import annotations
 
+import logging
 import threading
 from datetime import datetime, timedelta, timezone
-from typing import Any, Optional
+from typing import Any, Callable, List, Optional
 
 import requests
 from requests.exceptions import ConnectionError, HTTPError, RequestException, Timeout
@@ -21,6 +22,11 @@ from datacosmos.auth.m2m_authenticator import M2MAuthenticator
 from datacosmos.config.config import Config
 from datacosmos.exceptions.datacosmos_exception import DatacosmosException
 
+_log = logging.getLogger(__name__)
+
+RequestHook = Callable[[str, str, Any, Any], None]
+ResponseHook = Callable[[requests.Response], None]
+
 
 class DatacosmosClient:
     """Client to interact with the Datacosmos API with authentication and request handling."""
@@ -31,18 +37,24 @@ class DatacosmosClient:
         self,
         config: Optional[Config | Any] = None,
         http_session: Optional[requests.Session | OAuth2Session] = None,
+        request_hooks: Optional[List[RequestHook]] = None,
+        response_hooks: Optional[List[ResponseHook]] = None,
     ):
         """Initialize the DatacosmosClient.
 
         Args:
             config (Optional[Config]): Configuration object (only needed when SDK creates its own session).
             http_session (Optional[requests.Session]): Pre-authenticated session.
+            request_hooks (Optional[List[RequestHook]]): A list of functions to be called before each request.
+            response_hooks (Optional[List[ResponseHook]]): A list of functions to be called after each successful response.
         """
         self.config = self._coerce_config(config)
         self.token: Optional[str] = None
         self.token_expiry: Optional[datetime] = None
         self._refresh_lock = threading.Lock()
         self._authenticator: Optional[BaseAuthenticator] = None
+        self._request_hooks = request_hooks or []
+        self._response_hooks = response_hooks or []
 
         if http_session is not None:
             self._init_with_injected_session(http_session)
@@ -172,11 +184,40 @@ class DatacosmosClient:
     def request(
         self, method: str, url: str, *args: Any, **kwargs: Any
     ) -> requests.Response:
-        """Send an HTTP request using the authenticated session (with auto-refresh and retries)."""
+        """Send an HTTP request using the authenticated session (with auto-refresh and retries).
+
+        Args:
+            method (str): The HTTP method (e.g., "GET", "POST").
+            url (str): The URL for the request.
+            *args: Positional arguments for requests.request().
+            **kwargs: Keyword arguments for requests.request().
+
+        Returns:
+            requests.Response: The HTTP response.
+
+        Raises:
+            DatacosmosException: For any HTTP or request-related errors.
+        """
         self._refresh_token_if_needed()
+
+        # Call pre-request hooks
+        for hook in self._request_hooks:
+            try:
+                hook(method, url, *args, **kwargs)
+            except Exception:
+                _log.error("Request hook failed.", exc_info=True)
+
         try:
             response = self._http_client.request(method, url, *args, **kwargs)
             response.raise_for_status()
+
+            # Call post-response hooks on success
+            for hook in self._response_hooks:
+                try:
+                    hook(response)
+                except Exception:
+                    _log.error("Response hook failed.", exc_info=True)
+
             return response
         except HTTPError as e:
             status = getattr(e.response, "status_code", None)

datacosmos/stac/enums/processing_level.py

@@ -3,7 +3,19 @@
 from enum import Enum
 
 
-class ProcessingLevel(Enum):
+class CaseInsensitiveEnum(Enum):
+    """An enum that can be initialized with case-insensitive strings."""
+
+    @classmethod
+    def _missing_(cls, value: object):
+        if isinstance(value, str):
+            for member in cls:
+                if member.value.lower() == value.lower():
+                    return member
+        return super()._missing_(value)
+
+
+class ProcessingLevel(CaseInsensitiveEnum):
     """Enum class for the processing levels of the data."""
 
     RAW = "RAW"

datacosmos/stac/item/models/datacosmos_item.py

@@ -1,28 +1,111 @@
 """Model representing a datacosmos item."""
 
+import math
 from datetime import datetime
+from typing import Any
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict, field_validator, model_validator
+from shapely.errors import ShapelyError
+from shapely.geometry import Polygon, shape
 
+from datacosmos.exceptions.datacosmos_exception import DatacosmosException
 from datacosmos.stac.enums.processing_level import ProcessingLevel
 from datacosmos.stac.item.models.asset import Asset
 
+_REQUIRED_DATACOSMOS_PROPERTIES = [
+    "datetime",
+    "processing:level",
+    "sat:platform_international_designator",
+]
+
 
 class DatacosmosItem(BaseModel):
-    """Model representing a datacosmos item."""
+    """Model representing a flexible Datacosmos STAC item with mandatory business fields."""
+
+    model_config = ConfigDict(extra="allow")
 
     id: str
     type: str
-    stac_version: str
-    stac_extensions: list | None
-    geometry: dict
-    properties: dict
-    links: list
+    geometry: dict[str, Any]
+    bbox: list[float]
+    properties: dict[str, Any]
+
+    links: list[dict[str, Any]]
     assets: dict[str, Asset]
-    collection: str
-    bbox: tuple[float, float, float, float]
 
-    def get_property(self, key: str) -> str | None:
+    stac_version: str | None = None
+    stac_extensions: list[str] | None = None
+    collection: str | None = None
+
+    @field_validator("properties", mode="before")
+    @classmethod
+    def validate_datacosmos_properties(
+        cls, properties_data: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Validates that Datacosmos-specific properties exist."""
+        missing_keys = [
+            key for key in _REQUIRED_DATACOSMOS_PROPERTIES if key not in properties_data
+        ]
+
+        if missing_keys:
+            raise DatacosmosException(
+                f"Datacosmos-specific properties are missing: {', '.join(missing_keys)}."
+            )
+        return properties_data
+
+    @field_validator("geometry", mode="before")
+    @classmethod
+    def validate_geometry_is_polygon(
+        cls, geometry_data: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Validates that the geometry is a Polygon with coordinates and correct winding order."""
+        if geometry_data.get("type") != "Polygon" or not geometry_data.get(
+            "coordinates"
+        ):
+            raise DatacosmosException("Geometry must be a Polygon with coordinates.")
+
+        try:
+            # Use shape() for robust GeoJSON parsing and validation
+            polygon = shape(geometry_data)
+
+            if not polygon.is_valid:
+                raise ValueError(f"Polygon geometry is invalid: {polygon.geom_type}")
+
+            # right-hand rule validation:
+            # The right-hand rule means exterior ring must be counter-clockwise (CCW).
+            # Shapely's Polygon stores the exterior as CCW if the input is valid.
+            if not polygon.exterior.is_ccw:
+                raise ValueError(
+                    "Polygon winding order violates GeoJSON Right-Hand Rule (Exterior ring is clockwise)."
+                )
+
+        except (KeyError, ShapelyError, ValueError) as e:
+            raise DatacosmosException(f"Invalid geometry data: {e}") from e
+
+        return geometry_data
+
+    @model_validator(mode="after")
+    def validate_bbox_vs_geometry(self) -> "DatacosmosItem":
+        """Validates that the bbox tightly encloses the geometry."""
+        if self.geometry and self.bbox:
+            try:
+                geom_shape = shape(self.geometry)
+                true_bbox = list(geom_shape.bounds)
+
+                # Check for floating point equality within a tolerance
+                if not all(
+                    math.isclose(a, b, rel_tol=1e-9)
+                    for a, b in zip(self.bbox, true_bbox)
+                ):
+                    raise DatacosmosException(
+                        "Provided bbox does not match geometry bounds."
+                    )
+            except Exception as e:
+                # Catch any errors from Shapely or the comparison
+                raise DatacosmosException(f"Invalid bbox or geometry: {e}") from e
+        return self
+
+    def get_property(self, key: str) -> Any | None:
         """Get a property value from the Datacosmos item."""
         return self.properties.get(key)
 
@@ -43,12 +126,13 @@ class DatacosmosItem(BaseModel):
     @property
     def sat_int_designator(self) -> str:
         """Get the satellite international designator of the Datacosmos item."""
-        property = self.get_property("sat:platform_international_designator")
-        if property is None:
-            raise ValueError(
-                "sat:platform_international_designator is missing in STAC item"
-            )
-        return property
+        return self.properties["sat:platform_international_designator"]
+
+    @property
+    def polygon(self) -> Polygon:
+        """Returns the polygon of the item."""
+        coordinates = self.geometry["coordinates"][0]
+        return Polygon(coordinates)
 
     def to_dict(self) -> dict:
         """Converts the DatacosmosItem instance to a dictionary."""

{datacosmos-0.0.16.dist-info → datacosmos-0.0.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datacosmos
-Version: 0.0.16
+Version: 0.0.18
 Summary: A library for interacting with DataCosmos from Python code
 Author-email: Open Cosmos <support@open-cosmos.com>
 Classifier: Programming Language :: Python :: 3
@@ -16,6 +16,7 @@ Requires-Dist: pystac==1.12.1
 Requires-Dist: pyyaml==6.0.2
 Requires-Dist: structlog==24.4.0
 Requires-Dist: tenacity>=8.2.3
+Requires-Dist: shapely>=1.8.0
 Provides-Extra: dev
 Requires-Dist: black==22.3.0; extra == "dev"
 Requires-Dist: ruff==0.9.5; extra == "dev"

{datacosmos-0.0.16.dist-info → datacosmos-0.0.18.dist-info}/RECORD

@@ -1,5 +1,5 @@
 datacosmos/__init__.py,sha256=dVHKpbz5FVtfoJAWHRdsUENG6H-vs4UrkuwnIvOGJr4,66
-datacosmos/datacosmos_client.py,sha256=xt_kHhP2tELNQyvSz_y3bDCSNoR705xpoAmNUh8FXG8,8975
+datacosmos/datacosmos_client.py,sha256=yK9rit_AELs11ReJWm-zXx46wEWyvlDJDUOXy27bP3c,10524
 datacosmos/auth/__init__.py,sha256=ynCThS9QyLKV9miRdnjm8uF_breiGGiCcI0FaOSw_2o,45
 datacosmos/auth/base_authenticator.py,sha256=bSlb-N-vIUTl4K9KnDd3Dz21MevN_nvpWuwxgifdWBE,1814
 datacosmos/auth/local_authenticator.py,sha256=a3jIBZAMB1UlEFUZyECyJTCgSH2yjbTcrFZuUer0F90,2914
@@ -29,7 +29,7 @@ datacosmos/stac/collection/models/collection_update.py,sha256=XC6-29nLz1VGWMxYAw
 datacosmos/stac/constants/__init__.py,sha256=dDRSsF7CKqNF44yIlNdE-PD1sp0Q5mhTEPT7hHIK7YE,26
 datacosmos/stac/constants/satellite_name_mapping.py,sha256=EJqNdO9uW5B-sIeDF72AjnW7va5BM9mm4oNwijtl51w,575
 datacosmos/stac/enums/__init__.py,sha256=GUEL2xGtdjsrszrxivs0X6daxkaZs2JsTu2JoBtsvB4,22
-datacosmos/stac/enums/processing_level.py,sha256=kWGhpMXgzoyTzwR4yoSFd3UQ5IBw3cUf3TaM1FaOtUg,263
+datacosmos/stac/enums/processing_level.py,sha256=_k4FO818VlZWtlm-rULhg-CYkbewkOdTUfqeCfHN8h4,641
 datacosmos/stac/enums/product_type.py,sha256=7lL0unJ1hxevW8Pepn9rmydUUWIORu2x4MEtp6rSFbA,196
 datacosmos/stac/enums/season.py,sha256=QvUzXBYtPEfixhlbV0SAw2u_HK3tRFEnHKshJyIatdg,241
 datacosmos/stac/item/__init__.py,sha256=lRuD_yp-JxoLqBA23q0XMkCNImf4T-X3BJnSw9u_3Yk,200
@@ -37,7 +37,7 @@ datacosmos/stac/item/item_client.py,sha256=HCHl3cHp0u2qxbwLxPk0xkujC1D4uwIBIFI-f
 datacosmos/stac/item/models/__init__.py,sha256=bcOrOcIxGxGBrRVIyQVxSM3C3Xj_qzxIHgQeWo6f7Q8,34
 datacosmos/stac/item/models/asset.py,sha256=mvg_fenYCGOTMGwXXpK2nyqBk5RMsUYxl6KhQTWW_b0,631
 datacosmos/stac/item/models/catalog_search_parameters.py,sha256=3HrUm37VezujwuCR45jhMryS5m1FGc1XmX8-fdTy4jU,4870
-datacosmos/stac/item/models/datacosmos_item.py,sha256=AImz0GRxrpZfIETdzzNfaKX35wpr39Q4f4u0z6r8eys,1745
+datacosmos/stac/item/models/datacosmos_item.py,sha256=MJXUJu_kNJIoaTfIG05OlSys9th3KI4hgbzj2m2xI0Q,5027
 datacosmos/stac/item/models/eo_band.py,sha256=YC3Scn_wFhIo51pIVcJeuJienF7JGWoEv39JngDM6rI,309
 datacosmos/stac/item/models/item_update.py,sha256=_CpjQn9SsfedfuxlHSiGeptqY4M-p15t9YX__mBRueI,2088
 datacosmos/stac/item/models/raster_band.py,sha256=CoEVs-YyPE5Fse0He9DdOs4dGZpzfCsCuVzOcdXa_UM,354
@@ -54,8 +54,8 @@ datacosmos/utils/http_response/check_api_response.py,sha256=dKWW01jn2_lWV0xpOBAB
 datacosmos/utils/http_response/models/__init__.py,sha256=Wj8YT6dqw7rAz_rctllxo5Or_vv8DwopvQvBzwCTvpw,45
 datacosmos/utils/http_response/models/datacosmos_error.py,sha256=Uqi2uM98nJPeCbM7zngV6vHSk97jEAb_nkdDEeUjiQM,740
 datacosmos/utils/http_response/models/datacosmos_response.py,sha256=oV4n-sue7K1wwiIQeHpxdNU8vxeqF3okVPE2rydw5W0,336
-datacosmos-0.0.16.dist-info/licenses/LICENSE.md,sha256=vpbRI-UUbZVQfr3VG_CXt9HpRnL1b5kt8uTVbirxeyI,1486
-datacosmos-0.0.16.dist-info/METADATA,sha256=WiWMHwzjJKXyW5-s_qDyuZW4WogZGh4f9HmkwMslc6I,970
-datacosmos-0.0.16.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-datacosmos-0.0.16.dist-info/top_level.txt,sha256=ueobs5CNeyDbPMgXPcVV0d0yNdm8CvGtDT3CaksRVtA,11
-datacosmos-0.0.16.dist-info/RECORD,,
+datacosmos-0.0.18.dist-info/licenses/LICENSE.md,sha256=vpbRI-UUbZVQfr3VG_CXt9HpRnL1b5kt8uTVbirxeyI,1486
+datacosmos-0.0.18.dist-info/METADATA,sha256=rTT3QYoHGLf1LxLT7i11oLG68l0KUjXaYeC07hFvjOs,1000
+datacosmos-0.0.18.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+datacosmos-0.0.18.dist-info/top_level.txt,sha256=ueobs5CNeyDbPMgXPcVV0d0yNdm8CvGtDT3CaksRVtA,11
+datacosmos-0.0.18.dist-info/RECORD,,