datacosmos 0.0.16__tar.gz → 0.0.18__tar.gz

{datacosmos-0.0.16 → datacosmos-0.0.18}/PKG-INFO

@@ -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 → datacosmos-0.0.18}/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-0.0.18/datacosmos/stac/enums/processing_level.py

@@ -0,0 +1,28 @@
+"""Level enum class."""
+
+from enum import 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"
+    L0 = "l0"
+    L1A = "l1A"
+    L2A = "l2A"
+    L1B = "l1B"
+    L1C = "l1C"
+    L1D = "l1D"
+    L3 = "l3"

datacosmos-0.0.18/datacosmos/stac/item/models/datacosmos_item.py

@@ -0,0 +1,139 @@
+"""Model representing a datacosmos item."""
+
+import math
+from datetime import datetime
+from typing import Any
+
+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 flexible Datacosmos STAC item with mandatory business fields."""
+
+    model_config = ConfigDict(extra="allow")
+
+    id: str
+    type: str
+    geometry: dict[str, Any]
+    bbox: list[float]
+    properties: dict[str, Any]
+
+    links: list[dict[str, Any]]
+    assets: dict[str, Asset]
+
+    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)
+
+    def get_asset(self, key: str) -> Asset | None:
+        """Get an asset from the Datacosmos item."""
+        return self.assets.get(key)
+
+    @property
+    def datetime(self) -> datetime:
+        """Get the datetime of the Datacosmos item."""
+        return datetime.strptime(self.properties["datetime"], "%Y-%m-%dT%H:%M:%SZ")
+
+    @property
+    def level(self) -> ProcessingLevel:
+        """Get the processing level of the Datacosmos item."""
+        return ProcessingLevel(self.properties["processing:level"].lower())
+
+    @property
+    def sat_int_designator(self) -> str:
+        """Get the satellite international designator of the Datacosmos item."""
+        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."""
+        return self.model_dump()

{datacosmos-0.0.16 → datacosmos-0.0.18}/datacosmos.egg-info/PKG-INFO

@@ -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 → datacosmos-0.0.18}/datacosmos.egg-info/requires.txt

@@ -7,6 +7,7 @@ pystac==1.12.1
 pyyaml==6.0.2
 structlog==24.4.0
 tenacity>=8.2.3
+shapely>=1.8.0
 
 [dev]
 black==22.3.0

{datacosmos-0.0.16 → datacosmos-0.0.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "datacosmos"
-version = "0.0.16"
+version = "0.0.18"
 authors = [
     { name="Open Cosmos", email="support@open-cosmos.com" },
 ]
@@ -23,7 +23,8 @@ dependencies = [
     "pystac==1.12.1",
     "pyyaml==6.0.2",
     "structlog==24.4.0",
-    "tenacity>=8.2.3"
+    "tenacity>=8.2.3",
+    "shapely>=1.8.0"
 ]
 
 [project.optional-dependencies]

datacosmos-0.0.16/datacosmos/stac/enums/processing_level.py

@@ -1,16 +0,0 @@
-"""Level enum class."""
-
-from enum import Enum
-
-
-class ProcessingLevel(Enum):
-    """Enum class for the processing levels of the data."""
-
-    RAW = "RAW"
-    L0 = "l0"
-    L1A = "l1A"
-    L2A = "l2A"
-    L1B = "l1B"
-    L1C = "l1C"
-    L1D = "l1D"
-    L3 = "l3"

datacosmos-0.0.16/datacosmos/stac/item/models/datacosmos_item.py

@@ -1,55 +0,0 @@
-"""Model representing a datacosmos item."""
-
-from datetime import datetime
-
-from pydantic import BaseModel
-
-from datacosmos.stac.enums.processing_level import ProcessingLevel
-from datacosmos.stac.item.models.asset import Asset
-
-
-class DatacosmosItem(BaseModel):
-    """Model representing a datacosmos item."""
-
-    id: str
-    type: str
-    stac_version: str
-    stac_extensions: list | None
-    geometry: dict
-    properties: dict
-    links: list
-    assets: dict[str, Asset]
-    collection: str
-    bbox: tuple[float, float, float, float]
-
-    def get_property(self, key: str) -> str | None:
-        """Get a property value from the Datacosmos item."""
-        return self.properties.get(key)
-
-    def get_asset(self, key: str) -> Asset | None:
-        """Get an asset from the Datacosmos item."""
-        return self.assets.get(key)
-
-    @property
-    def datetime(self) -> datetime:
-        """Get the datetime of the Datacosmos item."""
-        return datetime.strptime(self.properties["datetime"], "%Y-%m-%dT%H:%M:%SZ")
-
-    @property
-    def level(self) -> ProcessingLevel:
-        """Get the processing level of the Datacosmos item."""
-        return ProcessingLevel(self.properties["processing:level"].lower())
-
-    @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
-
-    def to_dict(self) -> dict:
-        """Converts the DatacosmosItem instance to a dictionary."""
-        return self.model_dump()