datacosmos 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration package for the Datacosmos SDK.
+
+This package includes modules for loading and managing authentication
+configurations.
+"""

config/config.py

@@ -0,0 +1,167 @@
+"""Configuration module for the Datacosmos SDK.
+
+Handles configuration management using Pydantic and Pydantic Settings.
+It loads default values, allows overrides via YAML configuration files,
+and supports environment variable-based overrides.
+"""
+
+import os
+from typing import ClassVar, Optional
+
+import yaml
+from pydantic import field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from config.models.m2m_authentication_config import M2MAuthenticationConfig
+from config.models.url import URL
+
+
+class Config(BaseSettings):
+    """Centralized configuration for the Datacosmos SDK."""
+
+    model_config = SettingsConfigDict(
+        env_nested_delimiter="__",
+        nested_model_default_partial_update=True,
+        extra="allow",
+    )
+
+    authentication: Optional[M2MAuthenticationConfig] = None
+    stac: Optional[URL] = None
+
+    DEFAULT_AUTH_TYPE: ClassVar[str] = "m2m"
+    DEFAULT_AUTH_TOKEN_URL: ClassVar[str] = "https://login.open-cosmos.com/oauth/token"
+    DEFAULT_AUTH_AUDIENCE: ClassVar[str] = "https://beeapp.open-cosmos.com"
+
+    @classmethod
+    def from_yaml(cls, file_path: str = "config/config.yaml") -> "Config":
+        """Load configuration from a YAML file and override defaults.
+
+        Args:
+            file_path (str): The path to the YAML configuration file.
+
+        Returns:
+            Config: An instance of the Config class with loaded settings.
+        """
+        config_data: dict = {}
+        if os.path.exists(file_path):
+            with open(file_path, "r") as f:
+                yaml_data = yaml.safe_load(f) or {}
+                # Remove empty values from YAML to avoid overwriting with `None`
+                config_data = {
+                    key: value
+                    for key, value in yaml_data.items()
+                    if value not in [None, ""]
+                }
+
+        return cls(**config_data)
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        """Load configuration from environment variables.
+
+        Returns:
+            Config: An instance of the Config class with settings loaded from environment variables.
+        """
+        authentication_config = M2MAuthenticationConfig(
+            type=os.getenv("OC_AUTH_TYPE", cls.DEFAULT_AUTH_TYPE),
+            client_id=os.getenv("OC_AUTH_CLIENT_ID"),
+            client_secret=os.getenv("OC_AUTH_CLIENT_SECRET"),
+            token_url=os.getenv("OC_AUTH_TOKEN_URL", cls.DEFAULT_AUTH_TOKEN_URL),
+            audience=os.getenv("OC_AUTH_AUDIENCE", cls.DEFAULT_AUTH_AUDIENCE),
+        )
+
+        stac_config = URL(
+            protocol=os.getenv("OC_STAC_PROTOCOL", "https"),
+            host=os.getenv("OC_STAC_HOST", "app.open-cosmos.com"),
+            port=int(os.getenv("OC_STAC_PORT", "443")),
+            path=os.getenv("OC_STAC_PATH", "/api/data/v0/stac"),
+        )
+
+        return cls(authentication=authentication_config, stac=stac_config)
+
+    @field_validator("authentication", mode="before")
+    @classmethod
+    def validate_authentication(
+        cls, auth_data: Optional[dict]
+    ) -> M2MAuthenticationConfig:
+        """Ensure authentication is provided and apply defaults.
+
+        Args:
+            auth_data (Optional[dict]): The authentication config as a dictionary.
+
+        Returns:
+            M2MAuthenticationConfig: The validated authentication configuration.
+
+        Raises:
+            ValueError: If authentication is missing or required fields are not set.
+        """
+        if not auth_data:
+            cls.raise_missing_auth_error()
+
+        auth = cls.parse_auth_config(auth_data)
+        auth = cls.apply_auth_defaults(auth)
+
+        cls.check_required_auth_fields(auth)
+        return auth
+
+    @staticmethod
+    def raise_missing_auth_error():
+        """Raise an error when authentication is missing."""
+        raise ValueError(
+            "M2M authentication is required. Provide it via:\n"
+            "1. Explicit instantiation (Config(authentication=...))\n"
+            "2. A YAML config file (config.yaml)\n"
+            "3. Environment variables (OC_AUTH_CLIENT_ID, OC_AUTH_CLIENT_SECRET, etc.)"
+        )
+
+    @staticmethod
+    def parse_auth_config(auth_data: dict) -> M2MAuthenticationConfig:
+        """Convert dictionary input to M2MAuthenticationConfig object."""
+        return (
+            M2MAuthenticationConfig(**auth_data)
+            if isinstance(auth_data, dict)
+            else auth_data
+        )
+
+    @classmethod
+    def apply_auth_defaults(
+        cls, auth: M2MAuthenticationConfig
+    ) -> M2MAuthenticationConfig:
+        """Apply default authentication values if they are missing."""
+        auth.type = auth.type or cls.DEFAULT_AUTH_TYPE
+        auth.token_url = auth.token_url or cls.DEFAULT_AUTH_TOKEN_URL
+        auth.audience = auth.audience or cls.DEFAULT_AUTH_AUDIENCE
+        return auth
+
+    @staticmethod
+    def check_required_auth_fields(auth: M2MAuthenticationConfig):
+        """Ensure required fields (client_id, client_secret) are provided."""
+        missing_fields = [
+            field
+            for field in ("client_id", "client_secret")
+            if not getattr(auth, field)
+        ]
+        if missing_fields:
+            raise ValueError(
+                f"Missing required authentication fields: {', '.join(missing_fields)}"
+            )
+
+    @field_validator("stac", mode="before")
+    @classmethod
+    def validate_stac(cls, stac_config: Optional[URL]) -> URL:
+        """Ensure STAC configuration has a default if not explicitly set.
+
+        Args:
+            stac_config (Optional[URL]): The STAC config to validate.
+
+        Returns:
+            URL: The validated STAC configuration.
+        """
+        if stac_config is None:
+            return URL(
+                protocol="https",
+                host="app.open-cosmos.com",
+                port=443,
+                path="/api/data/v0/stac",
+            )
+        return stac_config

config/models/__init__.py

@@ -0,0 +1 @@
+"""Models for configuration settings."""

config/models/m2m_authentication_config.py

@@ -0,0 +1,23 @@
+"""Module for configuring machine-to-machine (M2M) authentication.
+
+Used when running scripts in the cluster that require automated authentication
+without user interaction.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class M2MAuthenticationConfig(BaseModel):
+    """Configuration for machine-to-machine authentication.
+
+    This is used when running scripts in the cluster that require authentication
+    with client credentials.
+    """
+
+    type: Literal["m2m"]
+    client_id: str
+    token_url: str
+    audience: str
+    client_secret: str

config/models/url.py

@@ -0,0 +1,35 @@
+"""Module defining a structured URL configuration model.
+
+Ensures that URLs contain required components such as protocol, host,
+port, and path.
+"""
+
+from pydantic import BaseModel
+
+from datacosmos.utils.url import URL as DomainURL
+
+
+class URL(BaseModel):
+    """Generic configuration model for a URL.
+
+    This class provides attributes to store URL components and a method
+    to convert them into a `DomainURL` instance.
+    """
+
+    protocol: str
+    host: str
+    port: int
+    path: str
+
+    def as_domain_url(self) -> DomainURL:
+        """Convert the URL instance to a `DomainURL` object.
+
+        Returns:
+            DomainURL: A domain-specific URL object.
+        """
+        return DomainURL(
+            protocol=self.protocol,
+            host=self.host,
+            port=self.port,
+            base=self.path,
+        )

datacosmos/exceptions/__init__.py

@@ -0,0 +1 @@
+"""Exceptions for the datacosmos package."""

datacosmos/exceptions/datacosmos_exception.py

@@ -0,0 +1,27 @@
+"""Base exception class for all Datacosmos SDK exceptions."""
+
+from typing import Optional
+
+from requests import Response
+from requests.exceptions import RequestException
+
+
+class DatacosmosException(RequestException):
+    """Base exception class for all Datacosmos SDK exceptions."""
+
+    def __init__(self, message: str, response: Optional[Response] = None):
+        """Initialize DatacosmosException.
+
+        Args:
+            message (str): The error message.
+            response (Optional[Response]): The HTTP response object, if available.
+        """
+        self.response = response
+        self.status_code = response.status_code if response else None
+        self.details = response.text if response else None
+        full_message = (
+            f"{message} (Status: {self.status_code}, Details: {self.details})"
+            if response
+            else message
+        )
+        super().__init__(full_message)

datacosmos/stac/__init__.py

@@ -0,0 +1,5 @@
+"""STAC package for interacting with the STAC API, providing query and fetch functionalities.
+
+It enables interaction with STAC (SpatioTemporal Asset Catalog) services
+using an authenticated Datacosmos client.
+"""

datacosmos/stac/collection/__init__.py

@@ -0,0 +1,4 @@
+"""STAC package for interacting with collections from the STAC API, providing query and fetch functionalities.
+
+It enables interaction with collections from the STAC using an authenticated Datacosmos client.
+"""

datacosmos/stac/collection/collection_client.py

@@ -0,0 +1,149 @@
+"""Handles operations related to STAC collections."""
+
+from typing import Generator, Optional
+
+from pystac import Collection, Extent, SpatialExtent, TemporalExtent
+from pystac.utils import str_to_datetime
+
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.collection.models.collection_update import CollectionUpdate
+from datacosmos.utils.http_response.check_api_response import check_api_response
+
+
+class CollectionClient:
+    """Handles operations related to STAC collections."""
+
+    def __init__(self, client: DatacosmosClient):
+        """Initialize the CollectionClient with a DatacosmosClient."""
+        self.client = client
+        self.base_url = client.config.stac.as_domain_url()
+
+    def fetch_collection(self, collection_id: str) -> Collection:
+        """Fetch details of an existing STAC collection."""
+        url = self.base_url.with_suffix(f"/collections/{collection_id}")
+        response = self.client.get(url)
+        check_api_response(response)
+        return Collection.from_dict(response.json())
+
+    def create_collection(self, collection: Collection) -> None:
+        """Create a new STAC collection.
+
+        Args:
+            collection (Collection): The STAC collection to create.
+
+        Raises:
+            InvalidRequest: If the collection data is malformed.
+        """
+        if isinstance(collection.extent, dict):
+            spatial_data = collection.extent.get("spatial", {}).get("bbox", [[]])
+            temporal_data = collection.extent.get("temporal", {}).get("interval", [[]])
+
+            # Convert string timestamps to datetime objects
+            parsed_temporal = []
+            for interval in temporal_data:
+                start = str_to_datetime(interval[0]) if interval[0] else None
+                end = (
+                    str_to_datetime(interval[1])
+                    if len(interval) > 1 and interval[1]
+                    else None
+                )
+                parsed_temporal.append([start, end])
+
+            collection.extent = Extent(
+                spatial=SpatialExtent(spatial_data),
+                temporal=TemporalExtent(parsed_temporal),
+            )
+
+        url = self.base_url.with_suffix("/collections")
+        response = self.client.post(url, json=collection.to_dict())
+        check_api_response(response)
+
+    def update_collection(
+        self, collection_id: str, update_data: CollectionUpdate
+    ) -> None:
+        """Update an existing STAC collection."""
+        url = self.base_url.with_suffix(f"/collections/{collection_id}")
+        response = self.client.patch(
+            url, json=update_data.model_dump(by_alias=True, exclude_none=True)
+        )
+        check_api_response(response)
+
+    def delete_collection(self, collection_id: str) -> None:
+        """Delete a STAC collection by its ID."""
+        url = self.base_url.with_suffix(f"/collections/{collection_id}")
+        response = self.client.delete(url)
+        check_api_response(response)
+
+    def fetch_all_collections(self) -> Generator[Collection, None, None]:
+        """Fetch all STAC collections with pagination support."""
+        url = self.base_url.with_suffix("/collections")
+        params = {"limit": 10}
+
+        while True:
+            data = self._fetch_collections_page(url, params)
+            yield from self._parse_collections(data)
+
+            next_cursor = self._get_next_pagination_cursor(data)
+            if not next_cursor:
+                break
+
+            params["cursor"] = next_cursor
+
+    def _fetch_collections_page(self, url: str, params: dict) -> dict:
+        """Fetch a single page of collections from the API."""
+        response = self.client.get(url, params=params)
+        check_api_response(response)
+
+        data = response.json()
+
+        if isinstance(data, list):
+            return {"collections": data}
+
+        return data
+
+    def _parse_collections(self, data: dict) -> Generator[Collection, None, None]:
+        """Convert API response data to STAC Collection objects, ensuring required fields exist."""
+        return (
+            Collection.from_dict(
+                {
+                    **collection,
+                    "type": collection.get("type", "Collection"),
+                    "id": collection.get("id", ""),
+                    "stac_version": collection.get("stac_version", "1.0.0"),
+                    "extent": collection.get(
+                        "extent",
+                        {"spatial": {"bbox": []}, "temporal": {"interval": []}},
+                    ),
+                    "links": collection.get("links", []) or [],
+                    "properties": collection.get("properties", {}),
+                }
+            )
+            for collection in data.get("collections", [])
+            if collection.get("type") == "Collection"
+        )
+
+    def _get_next_pagination_cursor(self, data: dict) -> Optional[str]:
+        """Extract the next pagination token from the response."""
+        next_href = self._get_next_link(data)
+        return self._extract_pagination_token(next_href) if next_href else None
+
+    def _get_next_link(self, data: dict) -> Optional[str]:
+        """Extract the next page link from the response."""
+        next_link = next(
+            (link for link in data.get("links", []) if link.get("rel") == "next"), None
+        )
+        return next_link.get("href", "") if next_link else None
+
+    def _extract_pagination_token(self, next_href: str) -> Optional[str]:
+        """Extract the pagination token from the next link URL.
+
+        Args:
+            next_href (str): The next page URL.
+
+        Returns:
+            Optional[str]: The extracted token, or None if parsing fails.
+        """
+        try:
+            return next_href.split("?")[1].split("=")[-1]
+        except (IndexError, AttributeError):
+            raise InvalidRequest(f"Failed to parse pagination token from {next_href}")

datacosmos/stac/collection/models/__init__.py

@@ -0,0 +1 @@
+"""Models for the Collection Client."""

datacosmos/stac/collection/models/collection_update.py

@@ -0,0 +1,46 @@
+"""Represents a structured update model for STAC collections.
+
+Allows partial updates where only the provided fields are modified.
+"""
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+from pystac import Extent, Link, Provider, Summaries
+
+
+class CollectionUpdate(BaseModel):
+    """Represents a structured update model for STAC collections.
+
+    Allows partial updates where only the provided fields are modified.
+    """
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    title: Optional[str] = Field(None, description="Title of the STAC collection.")
+    description: Optional[str] = Field(
+        None, description="Description of the collection."
+    )
+    keywords: Optional[List[str]] = Field(
+        None, description="List of keywords associated with the collection."
+    )
+    license: Optional[str] = Field(None, description="Collection license information.")
+    providers: Optional[List[Provider]] = Field(
+        None, description="List of data providers."
+    )
+    extent: Optional[Extent] = Field(
+        None, description="Spatial and temporal extent of the collection."
+    )
+    summaries: Optional[Summaries] = Field(
+        None, description="Summaries for the collection."
+    )
+    links: Optional[List[Link]] = Field(
+        None, description="List of links associated with the collection."
+    )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert the model into a dictionary, excluding `None` values.
+
+        Returns:
+            Dict[str, Any]: Dictionary representation of the update payload.
+        """
+        return self.model_dump(by_alias=True, exclude_none=True)

datacosmos/stac/item/__init__.py

@@ -0,0 +1,4 @@
+"""STAC package for interacting with items from the STAC API, providing query and fetch functionalities.
+
+It enables interaction with items from the STAC using an authenticated Datacosmos client.
+"""

datacosmos/stac/item/item_client.py

@@ -0,0 +1,185 @@
+"""STAC Client module for interacting with a STAC (SpatioTemporal Asset Catalog) API.
+
+Provides methods for querying, fetching, creating, updating, and deleting STAC items.
+"""
+
+from typing import Generator, Optional
+
+from pystac import Item
+
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.exceptions.datacosmos_exception import DatacosmosException
+from datacosmos.stac.item.models.item_update import ItemUpdate
+from datacosmos.stac.item.models.search_parameters import SearchParameters
+from datacosmos.utils.http_response.check_api_response import check_api_response
+
+
+class ItemClient:
+    """Client for interacting with the STAC API."""
+
+    def __init__(self, client: DatacosmosClient):
+        """Initialize the STACClient with a DatacosmosClient.
+
+        Args:
+            client (DatacosmosClient): The authenticated Datacosmos client instance.
+        """
+        self.client = client
+        self.base_url = client.config.stac.as_domain_url()
+
+    def fetch_item(self, item_id: str, collection_id: str) -> Item:
+        """Fetch a single STAC item by ID.
+
+        Args:
+            item_id (str): The ID of the item to fetch.
+            collection_id (str): The ID of the collection containing the item.
+
+        Returns:
+            Item: The fetched STAC item.
+        """
+        url = self.base_url.with_suffix(f"/collections/{collection_id}/items/{item_id}")
+        response = self.client.get(url)
+        check_api_response(response)
+        return Item.from_dict(response.json())
+
+    def fetch_collection_items(
+        self, collection_id: str, parameters: Optional[SearchParameters] = None
+    ) -> Generator[Item, None, None]:
+        """Fetch all items in a collection with optional filtering.
+
+        Args:
+            collection_id (str): The ID of the collection.
+            parameters (Optional[SearchParameters]): Filtering parameters (spatial, temporal, etc.).
+
+        Yields:
+            Item: Parsed STAC item.
+        """
+        if parameters is None:
+            parameters = SearchParameters(collections=[collection_id])
+
+        return self.search_items(parameters)
+
+    def search_items(self, parameters: SearchParameters) -> Generator[Item, None, None]:
+        """Query the STAC catalog using the POST endpoint with filtering and pagination.
+
+        Args:
+            parameters (SearchParameters): The search parameters.
+
+        Yields:
+            Item: Parsed STAC item.
+        """
+        url = self.base_url.with_suffix("/search")
+        body = parameters.model_dump(by_alias=True, exclude_none=True)
+        return self._paginate_items(url, body)
+
+    def create_item(self, collection_id: str, item: Item) -> None:
+        """Create a new STAC item in a specified collection.
+
+        Args:
+            collection_id (str): The ID of the collection where the item will be created.
+            item (Item): The STAC Item to be created.
+
+        Raises:
+            RequestError: If the API returns an error response.
+        """
+        url = self.base_url.with_suffix(f"/collections/{collection_id}/items")
+        item_json: dict = item.to_dict()
+
+        response = self.client.post(url, json=item_json)
+        check_api_response(response)
+
+    def update_item(
+        self, item_id: str, collection_id: str, update_data: ItemUpdate
+    ) -> None:
+        """Partially update an existing STAC item.
+
+        Args:
+            item_id (str): The ID of the item to update.
+            collection_id (str): The ID of the collection containing the item.
+            update_data (ItemUpdate): The structured update payload.
+        """
+        url = self.base_url.with_suffix(f"/collections/{collection_id}/items/{item_id}")
+
+        update_payload = update_data.model_dump(by_alias=True, exclude_none=True)
+
+        if "assets" in update_payload:
+            update_payload["assets"] = {
+                key: asset.to_dict() for key, asset in update_payload["assets"].items()
+            }
+        if "links" in update_payload:
+            update_payload["links"] = [
+                link.to_dict() for link in update_payload["links"]
+            ]
+
+        response = self.client.patch(url, json=update_payload)
+        check_api_response(response)
+
+    def delete_item(self, item_id: str, collection_id: str) -> None:
+        """Delete a STAC item by its ID.
+
+        Args:
+            item_id (str): The ID of the item to delete.
+            collection_id (str): The ID of the collection containing the item.
+
+        Raises:
+            OCError: If the item is not found or deletion is forbidden.
+        """
+        url = self.base_url.with_suffix(f"/collections/{collection_id}/items/{item_id}")
+        response = self.client.delete(url)
+        check_api_response(response)
+
+    def _paginate_items(self, url: str, body: dict) -> Generator[Item, None, None]:
+        """Handle pagination for the STAC search POST endpoint.
+
+        Fetches items one page at a time using the 'next' link.
+
+        Args:
+            url (str): The base URL for the search endpoint.
+            body (dict): The request body containing search parameters.
+
+        Yields:
+            Item: Parsed STAC item.
+        """
+        params = {"limit": body.get("limit", 10)}
+
+        while True:
+            response = self.client.post(url, json=body, params=params)
+            check_api_response(response)
+            data = response.json()
+
+            yield from (Item.from_dict(feature) for feature in data.get("features", []))
+
+            next_href = self._get_next_link(data)
+            if not next_href:
+                break
+
+            token = self._extract_pagination_token(next_href)
+            if not token:
+                break
+            params["cursor"] = token
+
+    def _get_next_link(self, data: dict) -> Optional[str]:
+        """Extract the next page link from the response."""
+        next_link = next(
+            (link for link in data.get("links", []) if link.get("rel") == "next"), None
+        )
+        return next_link.get("href", "") if next_link else None
+
+    def _extract_pagination_token(self, next_href: str) -> Optional[str]:
+        """Extract the pagination token from the next link URL.
+
+        Args:
+            next_href (str): The next page URL.
+
+        Returns:
+            Optional[str]: The extracted token, or None if parsing fails.
+
+        Raises:
+            DatacosmosException: If pagination token extraction fails.
+        """
+        try:
+            return next_href.split("?")[1].split("=")[-1]
+        except (IndexError, AttributeError) as e:
+            raise DatacosmosException(
+                f"Failed to parse pagination token from {next_href}",
+                response=e.response,
+            ) from e

datacosmos/stac/item/models/__init__.py

@@ -0,0 +1 @@
+"""Models for the Item Client."""

datacosmos/stac/item/models/item_update.py

@@ -0,0 +1,57 @@
+"""Model representing a partial update for a STAC item."""
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, model_validator
+from pystac import Asset, Link
+
+
+class ItemUpdate(BaseModel):
+    """Model representing a partial update for a STAC item."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    stac_extensions: Optional[list[str]] = None
+    geometry: Optional[dict[str, Any]] = None
+    bbox: Optional[list[float]] = Field(
+        None, min_items=4, max_items=4
+    )  # Must be [minX, minY, maxX, maxY]
+    properties: Optional[dict[str, Any]] = None
+    assets: Optional[dict[str, Asset]] = None
+    links: Optional[list[Link]] = None
+
+    def set_geometry(self, geom_type: str, coordinates: list[Any]) -> None:
+        """Set the geometry manually without using shapely.
+
+        Args:
+            geom_type (str): The type of geometry (e.g., 'Point', 'Polygon').
+            coordinates (list[Any]): The coordinates defining the geometry.
+        """
+        self.geometry = {"type": geom_type, "coordinates": coordinates}
+
+    @staticmethod
+    def has_valid_datetime(properties: dict[str, Any]) -> bool:
+        """Check if 'datetime' is present and not None."""
+        return properties.get("datetime") is not None
+
+    @staticmethod
+    def has_valid_datetime_range(properties: dict[str, Any]) -> bool:
+        """Check if both 'start_datetime' and 'end_datetime' are present and not None."""
+        return all(
+            properties.get(key) is not None
+            for key in ["start_datetime", "end_datetime"]
+        )
+
+    @model_validator(mode="before")
+    def validate_datetime_fields(cls, values):
+        """Ensure at least one of 'datetime' or 'start_datetime'/'end_datetime' exists."""
+        properties = values.get("properties", {})
+
+        if not cls.has_valid_datetime(properties) and not cls.has_valid_datetime_range(
+            properties
+        ):
+            raise ValueError(
+                "Either 'datetime' or both 'start_datetime' and 'end_datetime' must be provided."
+            )
+
+        return values

datacosmos/stac/item/models/search_parameters.py

@@ -0,0 +1,58 @@
+"""Module defining the SearchParameters model for STAC API queries, encapsulating filtering criteria.
+
+It includes spatial, temporal, and property-based filters for querying STAC items efficiently.
+"""
+
+from typing import Optional, Union
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class SearchParameters(BaseModel):
+    """Encapsulates the parameters for the STAC search API with validation."""
+
+    bbox: Optional[list[float]] = Field(
+        None,
+        description="Bounding box filter [minX, minY, maxX, maxY]. Optional six values for 3D bounding box.",
+        example=[-180.0, -90.0, 180.0, 90.0],
+    )
+    datetime_range: Optional[str] = Field(
+        None,
+        alias="datetime",
+        description=(
+            "Temporal filter, either a single RFC 3339 datetime or an interval. "
+            'Example: "2025-01-01T00:00:00Z/.."'
+        ),
+    )
+    intersects: Optional[dict] = Field(
+        None, description="GeoJSON geometry filter, e.g., a Polygon or Point."
+    )
+    ids: Optional[list[str]] = Field(
+        None,
+        description="Array of item IDs to filter by.",
+        example=["item1", "item2"],
+    )
+    collections: Optional[list[str]] = Field(
+        None,
+        description="Array of collection IDs to filter by.",
+        example=["collection1", "collection2"],
+    )
+    limit: Optional[int] = Field(
+        None,
+        ge=1,
+        le=10000,
+        description="Maximum number of items per page. Default: 10, Max: 10000.",
+        example=10,
+    )
+    query: Optional[dict[str, dict[str, Union[str, int, float]]]] = Field(
+        None,
+        description="Additional property filters, e.g., { 'cloud_coverage': { 'lt': 10 } }.",
+    )
+
+    @model_validator(mode="before")
+    def validate_bbox(cls, values):
+        """Validate that the `bbox` field contains either 4 or 6 values."""
+        bbox = values.get("bbox")
+        if bbox and len(bbox) not in {4, 6}:
+            raise ValueError("bbox must contain 4 or 6 values.")
+        return values

datacosmos/stac/stac_client.py

@@ -0,0 +1,12 @@
+"""Unified interface for STAC API, combining Item & Collection operations."""
+
+from datacosmos.stac.collection.collection_client import CollectionClient
+from datacosmos.stac.item.item_client import ItemClient
+
+
+class STACClient(ItemClient, CollectionClient):
+    """Unified interface for STAC API, combining Item & Collection operations."""
+
+    def __init__(self, client):
+        """Initialize the STACClient with a DatacosmosClient."""
+        super().__init__(client)

datacosmos/utils/__init__.py

@@ -0,0 +1 @@
+"""Http response and url utils for datacosmos."""

datacosmos/utils/http_response/__init__.py

@@ -0,0 +1 @@
+"""Validates an API response."""

datacosmos/utils/http_response/check_api_response.py

@@ -0,0 +1,34 @@
+"""Validates an API response and raises a DatacosmosException if an error occurs."""
+
+from pydantic import ValidationError
+from requests import Response
+
+from datacosmos.exceptions.datacosmos_exception import DatacosmosException
+from datacosmos.utils.http_response.models.datacosmos_response import DatacosmosResponse
+
+
+def check_api_response(response: Response) -> None:
+    """Validates an API response and raises a DatacosmosException if an error occurs.
+
+    Args:
+        resp (requests.Response): The response object.
+
+    Raises:
+        DatacosmosException: If the response status code indicates an error.
+    """
+    if 200 <= response.status_code < 400:
+        return
+
+    try:
+        response = DatacosmosResponse.model_validate_json(response.text)
+        msg = response.errors[0].human_readable()
+        if len(response.errors) > 1:
+            msg = "\n  * " + "\n  * ".join(
+                error.human_readable() for error in response.errors
+            )
+        raise DatacosmosException(msg, response=response)
+
+    except ValidationError:
+        raise DatacosmosException(
+            f"HTTP {response.status_code}: {response.text}", response=response
+        )

datacosmos/utils/http_response/models/__init__.py

@@ -0,0 +1 @@
+"""Models for validation of API response."""

datacosmos/utils/http_response/models/datacosmos_error.py

@@ -0,0 +1,26 @@
+"""Structured API error message for Datacosmos."""
+
+from pydantic import BaseModel
+
+
+class DatacosmosError(BaseModel):
+    """Structured API error message for Datacosmos."""
+
+    message: str
+    field: str | None = None
+    type: str | None = None
+    source: str | None = None
+    trace_id: str | None = None
+
+    def human_readable(self) -> str:
+        """Formats the error message into a readable format."""
+        msg = self.message
+        if self.type:
+            msg += f" (type: {self.type})"
+        if self.field:
+            msg += f" (field: {self.field})"
+        if self.source:
+            msg += f" (source: {self.source})"
+        if self.trace_id:
+            msg += f" (trace_id: {self.trace_id})"
+        return msg

datacosmos/utils/http_response/models/datacosmos_response.py

@@ -0,0 +1,11 @@
+"""Structured response for Datacosmos handling multiple API errors."""
+
+from pydantic import BaseModel
+
+from datacosmos.utils.http_response.models.datacosmos_error import DatacosmosError
+
+
+class DatacosmosResponse(BaseModel):
+    """Structured response for Datacosmos handling multiple API errors."""
+
+    errors: list[DatacosmosError]

datacosmos/utils/url.py

@@ -0,0 +1,37 @@
+"""URL utility class for building and handling URLs in the SDK."""
+
+
+class URL:
+    """Class to represent and build URLs in a convenient way."""
+
+    def __init__(self, protocol: str, host: str, port: int, base: str):
+        """Creates a new basis to build URLs.
+
+        Args:
+            protocol (str): Protocol to use in the URL (http/https).
+            host (str): Hostname (e.g., example.com).
+            port (int): Port number.
+            base (str): Base path (e.g., /api/v1).
+        """
+        self.protocol = protocol
+        self.host = host
+        self.port = port
+        self.base = base
+
+    def string(self) -> str:
+        """Returns the full URL as a string."""
+        port = "" if self.port in [80, 443] else f":{self.port}"
+        base = f"/{self.base.lstrip('/')}" if self.base else ""
+        return f"{self.protocol}://{self.host}{port}{base}"
+
+    def with_suffix(self, suffix: str) -> str:
+        """Appends a suffix to the URL, ensuring proper formatting.
+
+        Args:
+            suffix (str): The path to append.
+
+        Returns:
+            str: Full URL with the suffix.
+        """
+        base = self.string()
+        return f"{base.rstrip('/')}/{suffix.lstrip('/')}"

{datacosmos-0.0.1.dist-info → datacosmos-0.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: datacosmos
-Version: 0.0.1
+Version: 0.0.2
 Summary: A library for interacting with DataCosmos from Python code
 Author-email: Open Cosmos <support@open-cosmos.com>
 Classifier: Programming Language :: Python :: 3

datacosmos-0.0.2.dist-info/RECORD

@@ -0,0 +1,32 @@
+config/__init__.py,sha256=KCsaTb9-ZgFui1GM8wZFIPLJy0D0O8l8Z1Sv3NRD9UM,140
+config/config.py,sha256=0M2wKmrcCJjte3UmLNQVags_qce7Id2ampBPqadzPJw,5908
+config/models/__init__.py,sha256=r3lThPkyKjBjUZXRNscFzOrmn_-m_i9DvG3RePfCFYc,41
+config/models/m2m_authentication_config.py,sha256=1eJ_9df7Twn5WeWPbqMuR63ZdxhnTpBtKzqAPMnzP_k,565
+config/models/url.py,sha256=fwr2C06e_RDS8AWxOV_orVxMWhc57bzYoWSjFxQbkwg,835
+datacosmos/__init__.py,sha256=dVHKpbz5FVtfoJAWHRdsUENG6H-vs4UrkuwnIvOGJr4,66
+datacosmos/datacosmos_client.py,sha256=sivVYf45QEHTkUO62fnb1fnObKVmUngTR1Ga-ZRnoQE,4967
+datacosmos/exceptions/__init__.py,sha256=Crz8W7mOvPUXYcfDVotvjUt_3HKawBpmJA_-uel9UJk,45
+datacosmos/exceptions/datacosmos_exception.py,sha256=rKjJvQDvCEbxXWWccxB5GI_sth662bW8Yml0hX-vRw4,923
+datacosmos/stac/__init__.py,sha256=B4x_Mr4X7TzQoYtRC-VzI4W-fEON5WUOaz8cWJbk3Fc,214
+datacosmos/stac/stac_client.py,sha256=Cz_p96RmAgWX8t7Sye4OJRanQpCLihKStvfEw7IgYZc,472
+datacosmos/stac/collection/__init__.py,sha256=VQMLnsU3sER5kh4YxHrHP7XCA3DG1y0n9yoSmvycOY0,212
+datacosmos/stac/collection/collection_client.py,sha256=XTO2s309-cktJosvnwnFFXHDVmJc4vjvbEsZjpsCDmY,5904
+datacosmos/stac/collection/models/__init__.py,sha256=TQaihUS_CM9Eaekm4SbzFTNfv7BmabHv3Z-f37Py5Qs,40
+datacosmos/stac/collection/models/collection_update.py,sha256=Tqmfg4H4UQj5jsgy1dpKJCR59NSfWeiCSi9y8CY8-Cg,1656
+datacosmos/stac/item/__init__.py,sha256=lRuD_yp-JxoLqBA23q0XMkCNImf4T-X3BJnSw9u_3Yk,200
+datacosmos/stac/item/item_client.py,sha256=AYyRR92Wy-rDwc9wFoljb6lAgSCuWft4VT5muqGeyv8,6738
+datacosmos/stac/item/models/__init__.py,sha256=bcOrOcIxGxGBrRVIyQVxSM3C3Xj_qzxIHgQeWo6f7Q8,34
+datacosmos/stac/item/models/item_update.py,sha256=_CpjQn9SsfedfuxlHSiGeptqY4M-p15t9YX__mBRueI,2088
+datacosmos/stac/item/models/search_parameters.py,sha256=yMmcb-Tr2as8585MD5wuZLWcqzwtRRkj07WBkootVS0,2022
+datacosmos/utils/__init__.py,sha256=XQbAnoqJrPpnSpEzAbjh84yqYWw8cBM8mNp8ynTG-54,50
+datacosmos/utils/url.py,sha256=luaGa6UqPIf0h_1u2z3CZ32YQXNl7nGV03lVW7mlRIM,1214
+datacosmos/utils/http_response/__init__.py,sha256=BvOWwC5coYqq_kFn8gIw5m54TLpdfJKlW9vgRkfhXiA,33
+datacosmos/utils/http_response/check_api_response.py,sha256=dKWW01jn2_lWV0xpOBABhEP42CFSsx9dP0iSxykbN54,1186
+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.2.dist-info/LICENSE.md,sha256=vpbRI-UUbZVQfr3VG_CXt9HpRnL1b5kt8uTVbirxeyI,1486
+datacosmos-0.0.2.dist-info/METADATA,sha256=SIuvO1SE647Q9OvrKYuj1VmzWFgKjErvrRxrKoNgcyk,821
+datacosmos-0.0.2.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+datacosmos-0.0.2.dist-info/top_level.txt,sha256=Iu5b533Fmdfz0rFKTnuBPjSUOQL2lEkTfHxsokP72s4,18
+datacosmos-0.0.2.dist-info/RECORD,,

{datacosmos-0.0.1.dist-info → datacosmos-0.0.2.dist-info}/top_level.txt

@@ -1 +1,2 @@
+config
 datacosmos

datacosmos-0.0.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-datacosmos/__init__.py,sha256=dVHKpbz5FVtfoJAWHRdsUENG6H-vs4UrkuwnIvOGJr4,66
-datacosmos/datacosmos_client.py,sha256=sivVYf45QEHTkUO62fnb1fnObKVmUngTR1Ga-ZRnoQE,4967
-datacosmos-0.0.1.dist-info/LICENSE.md,sha256=vpbRI-UUbZVQfr3VG_CXt9HpRnL1b5kt8uTVbirxeyI,1486
-datacosmos-0.0.1.dist-info/METADATA,sha256=N8KMHCWaO8ED0OYT0hUikP31GgD1fB6SDpFuNAhL924,821
-datacosmos-0.0.1.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-datacosmos-0.0.1.dist-info/top_level.txt,sha256=ueobs5CNeyDbPMgXPcVV0d0yNdm8CvGtDT3CaksRVtA,11
-datacosmos-0.0.1.dist-info/RECORD,,