datacosmos 0.0.2__tar.gz → 0.0.4__tar.gz

{datacosmos-0.0.2/datacosmos.egg-info → datacosmos-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: datacosmos
-Version: 0.0.2
+Version: 0.0.4
 Summary: A library for interacting with DataCosmos from Python code
 Author-email: Open Cosmos <support@open-cosmos.com>
 Classifier: Programming Language :: Python :: 3
@@ -13,6 +13,7 @@ Requires-Dist: oauthlib==3.2.0
 Requires-Dist: requests-oauthlib==1.3.1
 Requires-Dist: pydantic==2.10.6
 Requires-Dist: pystac==1.12.1
+Requires-Dist: pyyaml==6.0.2
 Provides-Extra: dev
 Requires-Dist: black==22.3.0; extra == "dev"
 Requires-Dist: ruff==0.9.5; extra == "dev"
@@ -20,3 +21,4 @@ Requires-Dist: pytest==7.2.0; extra == "dev"
 Requires-Dist: bandit[toml]==1.7.4; extra == "dev"
 Requires-Dist: isort==5.11.4; extra == "dev"
 Requires-Dist: pydocstyle==6.1.1; extra == "dev"
+Dynamic: license-file

datacosmos-0.0.4/README.md

@@ -0,0 +1,368 @@
+# DataCosmos SDK
+
+## Overview
+
+The **DataCosmos SDK** enables Open Cosmos customers to interact with the **DataCosmos APIs** for efficient data management and retrieval. It provides authentication handling, HTTP request utilities, and a client for interacting with the **STAC API** (SpatioTemporal Asset Catalog).
+
+## Installation
+
+Install the SDK using **pip**:
+
+```sh
+pip install datacosmos=={version}
+```
+
+## Initializing the Client
+
+To start using the SDK, initialize the client. The easiest way to do this is by loading the configuration from a YAML file. Alternatively, you can manually instantiate the Config object or use environment variables.
+
+### Default Initialization (Recommended)
+
+By default, the client loads configuration from a YAML file (`config/config.yaml`).
+
+```python
+from datacosmos.datacosmos_client import DatacosmosClient
+
+client = DatacosmosClient()
+```
+
+### Loading from YAML (Recommended)
+
+Create a YAML file (`config/config.yaml`) with the following content:
+
+```yaml
+authentication:
+    client_id: {client_id}  
+    client_secret: {client_secret}
+```
+
+The client will automatically read this file when initialized.
+
+### Loading from Environment Variables
+
+Set the following environment variables:
+
+```sh
+export OC_AUTH_CLIENT_ID={client_id}
+export OC_AUTH_CLIENT_SECRET={client_secret}
+```
+
+The client will automatically read these values when initialized.
+
+### Manual Instantiation
+
+If manually instantiating `Config`, default values are now applied where possible.
+
+```python
+from config.config import Config
+from config.models.m2m_authentication_config import M2MAuthenticationConfig
+from config.models.url import URL
+
+config = Config(
+    authentication=M2MAuthenticationConfig(
+        client_id="your-client-id",
+        client_secret="your-client-secret"
+    )
+)
+
+client = DatacosmosClient(config=config)
+```
+
+### Configuration Options and Defaults
+
+| Setting                      | Default Value                                     | Override Method |
+|------------------------------|-------------------------------------------------|----------------|
+| `authentication.type`        | `m2m`                                           | YAML / ENV     |
+| `authentication.client_id`   | _Required in manual instantiation_              | YAML / ENV     |
+| `authentication.client_secret` | _Required in manual instantiation_            | YAML / ENV     |
+| `stac.protocol`              | `https`                                         | YAML / ENV     |
+| `stac.host`                  | `app.open-cosmos.com`                           | YAML / ENV     |
+| `stac.port`                  | `443`                                           | YAML / ENV     |
+| `stac.path`                  | `/api/data/v0/stac`                             | YAML / ENV     |
+| `datacosmos_cloud_storage.protocol` | `https`                                 | YAML / ENV     |
+| `datacosmos_cloud_storage.host`     | `app.open-cosmos.com`                   | YAML / ENV     |
+| `datacosmos_cloud_storage.port`     | `443`                                   | YAML / ENV     |
+| `datacosmos_cloud_storage.path`     | `/api/data/v0/storage`                 | YAML / ENV     |
+| `mission_id`                | `0`                                             | YAML / ENV     |
+| `environment`               | `test`                                          | YAML / ENV     |
+
+## STAC Client
+
+The `STACClient` enables interaction with the STAC API, allowing for searching, retrieving, creating, updating, and deleting STAC items and collections.
+
+### Initialize STACClient
+
+```python
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.stac_client import STACClient
+
+client = DatacosmosClient()
+stac_client = STACClient(client)
+```
+
+### STACClient Methods
+
+#### 1. **Search Items**
+```python
+from datacosmos.stac.item.models.catalog_search_parameters import CatalogSearchParameters
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.stac_client import STACClient
+
+client = DatacosmosClient()
+stac_client = STACClient(client)
+
+params = CatalogSearchParameters(
+     start_date="2/9/2025",
+     end_date="2/9/2025",
+     satellite=["MANTIS"],
+     product_type=["Satellite"],
+     processing_level=["L1A"]
+)
+
+items = list(stac_client.search_items(parameters=params, project_id="your-project-id"))
+```
+
+#### 2. **Fetch a Single Item**
+```python
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.stac_client import STACClient
+
+client = DatacosmosClient()
+stac_client = STACClient(client)
+
+item = stac_client.fetch_item(item_id="example-item", collection_id="example-collection")
+```
+
+#### 3. **Fetch All Items in a Collection**
+```python
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.stac_client import STACClient
+
+client = DatacosmosClient()
+stac_client = STACClient(client)
+
+items = stac_client.fetch_collection_items(collection_id="example-collection")
+```
+
+#### 4. **Create a New STAC Item**
+```python
+from pystac import Item, Asset
+from datetime import datetime
+
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.stac_client import STACClient
+
+client = DatacosmosClient()
+stac_client = STACClient(client)
+
+stac_item = Item(
+    id="new-item",
+    geometry={"type": "Point", "coordinates": [102.0, 0.5]},
+    bbox=[101.0, 0.0, 103.0, 1.0],
+    datetime=datetime.utcnow(),
+    properties={},
+    collection="example-collection"
+)
+
+stac_item.add_asset(
+    "image",
+    Asset(
+        href="https://example.com/sample-image.tiff",
+        media_type="image/tiff",
+        roles=["data"],
+        title="Sample Image"
+    )
+)
+
+stac_client.create_item(collection_id="example-collection", item=stac_item)
+```
+
+#### 5. **Update an Existing STAC Item**
+```python
+from datacosmos.stac.models.item_update import ItemUpdate
+from pystac import Asset, Link
+
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.stac_client import STACClient
+
+client = DatacosmosClient()
+stac_client = STACClient(client)
+
+update_payload = ItemUpdate(
+    properties={
+        "new_property": "updated_value",
+        "datetime": "2024-11-10T14:58:00Z"
+    },
+    assets={
+        "image": Asset(
+            href="https://example.com/updated-image.tiff",
+            media_type="image/tiff"
+        )
+    },
+    links=[
+        Link(rel="self", target="https://example.com/updated-image.tiff")
+    ],
+    geometry={
+        "type": "Point",
+        "coordinates": [10, 20]
+    },
+    bbox=[10.0, 20.0, 30.0, 40.0]
+)
+
+stac_client.update_item(item_id="new-item", collection_id="example-collection", update_data=update_payload)
+```
+
+#### 6. **Delete an Item**
+```python
+
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.stac_client import STACClient
+
+client = DatacosmosClient()
+stac_client = STACClient(client)
+
+stac_client.delete_item(item_id="new-item", collection_id="example-collection")
+```
+
+#### 7. Fetch a Collection
+
+```python
+
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.stac_client import STACClient
+
+client = DatacosmosClient()
+stac_client = STACClient(client)
+
+collection = stac_client.fetch_collection("test-collection")
+```
+
+#### 8. Fetch All Collections
+
+```python
+
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.stac_client import STACClient
+
+client = DatacosmosClient()
+stac_client = STACClient(client)
+
+collections = list(stac_client.fetch_all_collections())
+```
+
+#### 9. Create a Collection
+
+```python
+from pystac import Collection
+
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.stac_client import STACClient
+
+client = DatacosmosClient()
+stac_client = STACClient(client)
+
+new_collection = Collection(
+    id="test-collection",
+    title="Test Collection",
+    description="This is a test collection",
+    license="proprietary",
+    extent={
+        "spatial": {"bbox": [[-180, -90, 180, 90]]},
+        "temporal": {"interval": [["2023-01-01T00:00:00Z", None]]},
+    },
+)
+
+stac_client.create_collection(new_collection)
+```
+
+#### 10. Update a Collection
+
+```python
+from datacosmos.stac.collection.models.collection_update import CollectionUpdate
+
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.stac_client import STACClient
+
+client = DatacosmosClient()
+stac_client = STACClient(client)
+
+update_data = CollectionUpdate(
+    title="Updated Collection Title",
+    description="Updated description",
+)
+
+stac_client.update_collection("test-collection", update_data)
+```
+
+#### 11. Delete a Collection
+
+```python
+
+from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.stac.stac_client import STACClient
+
+client = DatacosmosClient()
+stac_client = STACClient(client)
+
+stac_client.delete_collection("test-collection")
+```
+
+### Uploading Files and Registering STAC Items
+
+You can use the `DatacosmosUploader` class to upload files to the DataCosmos cloud storage and register a STAC item.
+
+#### Upload Files and Register STAC Item
+
+```python
+from datacosmos.uploader.datacosmos_uploader import DatacosmosUploader
+
+from datacosmos.datacosmos_client import DatacosmosClient
+
+client = DatacosmosClient()
+
+uploader = DatacosmosUploader(client)
+item_json_file_path = "/path/to/stac_item.json"
+uploader.upload_and_register_item(item_json_file_path)
+```
+
+## Error Handling
+
+Use `try-except` blocks to handle API errors gracefully:
+
+```python
+try:
+    data = client.get_data("dataset_id")
+    print(data)
+except Exception as e:
+    print(f"An error occurred: {e}")
+```
+
+## Contributing
+
+To contribute:
+
+1. Fork the repository.
+2. Create a feature branch.
+3. Submit a pull request.
+
+### Development Setup
+
+Use `uv` for dependency management:
+
+```sh
+pip install uv
+uv venv
+uv pip install -r pyproject.toml .[dev]
+source .venv/bin/activate
+```
+
+Before making changes, run:
+
+```sh
+black .
+isort .
+ruff check .
+pydocstyle .
+bandit -r -c pyproject.toml .
+pytest
+```

{datacosmos-0.0.2 → datacosmos-0.0.4}/config/config.py

@@ -6,7 +6,7 @@ and supports environment variable-based overrides.
 """
 
 import os
-from typing import ClassVar, Optional
+from typing import ClassVar, Literal, Optional
 
 import yaml
 from pydantic import field_validator
@@ -27,6 +27,9 @@ class Config(BaseSettings):
 
     authentication: Optional[M2MAuthenticationConfig] = None
     stac: Optional[URL] = None
+    datacosmos_cloud_storage: Optional[URL] = None
+    mission_id: int = 0
+    environment: Literal["local", "test", "prod"] = "test"
 
     DEFAULT_AUTH_TYPE: ClassVar[str] = "m2m"
     DEFAULT_AUTH_TOKEN_URL: ClassVar[str] = "https://login.open-cosmos.com/oauth/token"
@@ -77,7 +80,20 @@ class Config(BaseSettings):
             path=os.getenv("OC_STAC_PATH", "/api/data/v0/stac"),
         )
 
-        return cls(authentication=authentication_config, stac=stac_config)
+        datacosmos_cloud_storage_config = URL(
+            protocol=os.getenv("DC_CLOUD_STORAGE_PROTOCOL", "https"),
+            host=os.getenv("DC_CLOUD_STORAGE_HOST", "app.open-cosmos.com"),
+            port=int(os.getenv("DC_CLOUD_STORAGE_PORT", "443")),
+            path=os.getenv("DC_CLOUD_STORAGE_PATH", "/api/data/v0/storage"),
+        )
+
+        return cls(
+            authentication=authentication_config,
+            stac=stac_config,
+            datacosmos_cloud_storage=datacosmos_cloud_storage_config,
+            mission_id=int(os.getenv("MISSION_ID", "0")),
+            environment=os.getenv("ENVIRONMENT", "test"),
+        )
 
     @field_validator("authentication", mode="before")
     @classmethod
@@ -96,7 +112,7 @@ class Config(BaseSettings):
             ValueError: If authentication is missing or required fields are not set.
         """
         if not auth_data:
-            cls.raise_missing_auth_error()
+            return cls.apply_auth_defaults(M2MAuthenticationConfig())
 
         auth = cls.parse_auth_config(auth_data)
         auth = cls.apply_auth_defaults(auth)
@@ -105,34 +121,24 @@ class Config(BaseSettings):
         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:
+    def apply_auth_defaults(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
+        auth.type = auth.type or Config.DEFAULT_AUTH_TYPE
+        auth.token_url = auth.token_url or Config.DEFAULT_AUTH_TOKEN_URL
+        auth.audience = auth.audience or Config.DEFAULT_AUTH_AUDIENCE
         return auth
 
+    @classmethod
+    def parse_auth_config(cls, auth_data: dict) -> M2MAuthenticationConfig:
+        """Parse authentication config from a dictionary."""
+        return M2MAuthenticationConfig(
+            type=auth_data.get("type", cls.DEFAULT_AUTH_TYPE),
+            token_url=auth_data.get("token_url", cls.DEFAULT_AUTH_TOKEN_URL),
+            audience=auth_data.get("audience", cls.DEFAULT_AUTH_AUDIENCE),
+            client_id=auth_data.get("client_id"),
+            client_secret=auth_data.get("client_secret"),
+        )
+
     @staticmethod
     def check_required_auth_fields(auth: M2MAuthenticationConfig):
         """Ensure required fields (client_id, client_secret) are provided."""
@@ -165,3 +171,25 @@ class Config(BaseSettings):
                 path="/api/data/v0/stac",
             )
         return stac_config
+
+    @field_validator("datacosmos_cloud_storage", mode="before")
+    @classmethod
+    def validate_datacosmos_cloud_storage(
+        cls, datacosmos_cloud_storage_config: Optional[URL]
+    ) -> URL:
+        """Ensure datacosmos cloud storage configuration has a default if not explicitly set.
+
+        Args:
+            datacosmos_cloud_storage_config (Optional[URL]): The datacosmos cloud storage config to validate.
+
+        Returns:
+            URL: The validated datacosmos cloud storage configuration.
+        """
+        if datacosmos_cloud_storage_config is None:
+            return URL(
+                protocol="https",
+                host="app.open-cosmos.com",
+                port=443,
+                path="/api/data/v0/storage",
+            )
+        return datacosmos_cloud_storage_config

{datacosmos-0.0.2 → datacosmos-0.0.4}/datacosmos/stac/collection/collection_client.py

@@ -6,6 +6,7 @@ from pystac import Collection, Extent, SpatialExtent, TemporalExtent
 from pystac.utils import str_to_datetime
 
 from datacosmos.datacosmos_client import DatacosmosClient
+from datacosmos.exceptions.datacosmos_exception import DatacosmosException
 from datacosmos.stac.collection.models.collection_update import CollectionUpdate
 from datacosmos.utils.http_response.check_api_response import check_api_response
 
@@ -145,5 +146,8 @@ class CollectionClient:
         """
         try:
             return next_href.split("?")[1].split("=")[-1]
-        except (IndexError, AttributeError):
-            raise InvalidRequest(f"Failed to parse pagination token from {next_href}")
+        except (IndexError, AttributeError) as e:
+            raise DatacosmosException(
+                f"Failed to parse pagination token from {next_href}",
+                response=e.response,
+            ) from e

{datacosmos-0.0.2 → datacosmos-0.0.4}/datacosmos/stac/collection/models/collection_update.py

@@ -2,6 +2,7 @@
 
 Allows partial updates where only the provided fields are modified.
 """
+
 from typing import Any, Dict, List, Optional
 
 from pydantic import BaseModel, Field

datacosmos-0.0.4/datacosmos/stac/constants/__init__.py

@@ -0,0 +1 @@
+"""Constants for STAC."""

datacosmos-0.0.4/datacosmos/stac/constants/satellite_name_mapping.py

@@ -0,0 +1,20 @@
+"""Satellite name mapping."""
+
+SATELLITE_NAME_MAPPING = {
+    "GEOSAT-2": "2014-033D",
+    "SUPERVIEW-1-01": "2016-083A",
+    "SUPERVIEW-1-02": "2016-083B",
+    "SUPERVIEW-1-03": "2018-002A",
+    "SUPERVIEW-1-04": "2018-002B",
+    "MANTIS": "2023-174B",
+    "MENUT": "2023-001B",
+    "HAMMER": "2024-043BC",
+    "HAMMER-EM": "COSPAR-HAMMER-EM-TBD",
+    "Alisio": "2023-185M",
+    "Platero": "2023-174G",
+    "PHISAT-2": "2024-149C",
+    "PHISAT-2 EM": "COSPAR-PHISAT2-EM-TBD",
+    "Sentinel-2A": "2015-028A",
+    "Sentinel-2B": "2017-013A",
+    "Sentinel-2C": "2024-157A",
+}

datacosmos-0.0.4/datacosmos/stac/enums/__init__.py

@@ -0,0 +1 @@
+"""Enums for STAC."""

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

@@ -0,0 +1,15 @@
+"""Level enum class."""
+
+from enum import Enum
+
+
+class ProcessingLevel(Enum):
+    """Enum class for the processing levels of the data."""
+
+    L0 = "L0"
+    L1A = "L1A"
+    L2A = "L2A"
+    L1B = "L1B"
+    L1C = "L1C"
+    L1D = "L1D"
+    L3 = "L3"

datacosmos-0.0.4/datacosmos/stac/enums/product_type.py

@@ -0,0 +1,11 @@
+"""Product type enum class."""
+
+from enum import Enum
+
+
+class ProductType(str, Enum):
+    """Different product types."""
+
+    SATELLITE = "Satellite"
+    VECTOR = "Vector"
+    INSIGHT = "Insight"

datacosmos-0.0.4/datacosmos/stac/enums/season.py

@@ -0,0 +1,14 @@
+"""Season enum class."""
+
+from enum import Enum
+
+
+class Season(str, Enum):
+    """Different Open Cosmos seasons."""
+
+    SUMMER = "Summer"
+    WINTER = "Winter"
+    AUTUMN = "Autumn"
+    SPRING = "Spring"
+    RAINY = "Rainy"
+    DRY = "Dry"

{datacosmos-0.0.2 → datacosmos-0.0.4}/datacosmos/stac/item/item_client.py

@@ -9,6 +9,10 @@ from pystac import Item
 
 from datacosmos.datacosmos_client import DatacosmosClient
 from datacosmos.exceptions.datacosmos_exception import DatacosmosException
+from datacosmos.stac.item.models.catalog_search_parameters import (
+    CatalogSearchParameters,
+)
+from datacosmos.stac.item.models.datacosmos_item import DatacosmosItem
 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
@@ -58,20 +62,23 @@ class ItemClient:
 
         return self.search_items(parameters)
 
-    def search_items(self, parameters: SearchParameters) -> Generator[Item, None, None]:
+    def search_items(
+        self, parameters: CatalogSearchParameters, project_id: str
+    ) -> Generator[Item, None, None]:
         """Query the STAC catalog using the POST endpoint with filtering and pagination.
 
         Args:
-            parameters (SearchParameters): The search parameters.
+            parameters (CatalogSearchParameters): 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)
+        parameters_query = parameters.to_query()
+        body = {"project": project_id, "limit": 50, "query": parameters_query}
         return self._paginate_items(url, body)
 
-    def create_item(self, collection_id: str, item: Item) -> None:
+    def create_item(self, collection_id: str, item: Item | DatacosmosItem) -> None:
         """Create a new STAC item in a specified collection.
 
         Args:

datacosmos-0.0.4/datacosmos/stac/item/models/asset.py

@@ -0,0 +1,23 @@
+"""Model representing a datacosmos item asset."""
+
+from pydantic import BaseModel, Field
+
+from datacosmos.stac.item.models.eo_band import EoBand
+from datacosmos.stac.item.models.raster_band import RasterBand
+
+
+class Asset(BaseModel):
+    """Model representing a datacosmos item asset."""
+
+    href: str
+    title: str
+    description: str
+    type: str
+    roles: list[str] | None
+    eo_bands: list[EoBand] | None = Field(default=None, alias="eo:bands")
+    raster_bands: list[RasterBand] | None = Field(default=None, alias="raster:bands")
+
+    class Config:
+        """Pydantic configuration."""
+
+        populate_by_name = True