cecil 0.1.3__py3-none-any.whl

cecil/__init__.py

@@ -0,0 +1,3 @@
+from .client import Client
+from .errors import Error
+from .version import __version__

cecil/client.py

@@ -0,0 +1,212 @@
+import os
+from typing import Dict, List, Optional
+
+import pandas as pd
+import requests
+
+from pydantic import BaseModel
+from requests import auth
+
+import xarray
+from .errors import (
+    Error,
+    _handle_bad_request,
+    _handle_method_not_allowed,
+    _handle_not_found,
+    _handle_too_many_requests,
+    _handle_unprocessable_entity,
+)
+from .models import (
+    AOI,
+    AOICreate,
+    OrganisationSettings,
+    RecoverAPIKey,
+    RecoverAPIKeyRequest,
+    RotateAPIKey,
+    RotateAPIKeyRequest,
+    User,
+    UserCreate,
+    SubscriptionParquetFiles,
+    SubscriptionListFiles,
+    Subscription,
+    SubscriptionCreate,
+)
+from .version import __version__
+from .xarray import load_xarray
+
+
+class Client:
+    def __init__(self, env: str = None) -> None:
+        self._api_auth = None
+        self._base_url = (
+            "https://api.cecil.earth" if env is None else f"https://{env}.cecil.earth"
+        )
+
+    def create_aoi(self, geometry: Dict, external_ref: str = "") -> AOI:
+        # TODO: validate geometry
+        res = self._post(
+            url="/v0/aois",
+            model=AOICreate(geometry=geometry, external_ref=external_ref),
+        )
+        return AOI(**res)
+
+    def get_aoi(self, id: str) -> AOI:
+        res = self._get(url=f"/v0/aois/{id}")
+        return AOI(**res)
+
+    def list_aois(self) -> List[AOI]:
+        res = self._get(url="/v0/aois")
+        return [AOI(**record) for record in res["records"]]
+
+    def list_subscriptions(self) -> List[Subscription]:
+        res = self._get(url="/v0/subscriptions")
+        return [Subscription(**record) for record in res["records"]]
+
+    def create_subscription(
+        self, aoi_id: str, dataset_id: str, external_ref: str = ""
+    ) -> Subscription:
+        res = self._post(
+            url="/v0/subscriptions",
+            model=SubscriptionCreate(
+                aoi_id=aoi_id, dataset_id=dataset_id, external_ref=external_ref
+            ),
+        )
+
+        return Subscription(**res)
+
+    def get_subscription(self, id: str) -> Subscription:
+        res = self._get(url=f"/v0/subscriptions/{id}")
+        return Subscription(**res)
+
+    def load_xarray(self, subscription_id: str) -> xarray.Dataset:
+        res = SubscriptionListFiles(
+            **self._get(url=f"/v0/subscriptions/{subscription_id}/files/tiff")
+        )
+        return load_xarray(res)
+
+    def load_dataframe(self, subscription_id: str) -> pd.DataFrame:
+        res = SubscriptionParquetFiles(
+            **self._get(url=f"/v0/subscriptions/{subscription_id}/parquet-files")
+        )
+
+        if not res.files:
+            return pd.DataFrame()
+
+        return pd.concat((pd.read_parquet(f) for f in res.files))
+
+    def recover_api_key(self, email: str) -> RecoverAPIKey:
+        res = self._post(
+            url="/v0/api-key/recover",
+            model=RecoverAPIKeyRequest(email=email),
+            skip_auth=True,
+        )
+
+        return RecoverAPIKey(**res)
+
+    def rotate_api_key(self) -> RotateAPIKey:
+        res = self._post(url=f"/v0/api-key/rotate", model=RotateAPIKeyRequest())
+
+        return RotateAPIKey(**res)
+
+    def create_user(self, first_name: str, last_name: str, email: str) -> User:
+        res = self._post(
+            url="/v0/users",
+            model=UserCreate(
+                first_name=first_name,
+                last_name=last_name,
+                email=email,
+            ),
+        )
+        return User(**res)
+
+    def get_user(self, id: str) -> User:
+        res = self._get(url=f"/v0/users/{id}")
+        return User(**res)
+
+    def list_users(self) -> List[User]:
+        res = self._get(url="/v0/users")
+        return [User(**record) for record in res["records"]]
+
+    def get_organisation_settings(self) -> OrganisationSettings:
+        res = self._get(url="/v0/organisation/settings")
+        return OrganisationSettings(**res)
+
+    def update_organisation_settings(
+        self,
+        *,
+        monthly_subscription_limit,
+    ) -> OrganisationSettings:
+        res = self._post(
+            url="/v0/organisation/settings",
+            model=OrganisationSettings(
+                monthly_subscription_limit=monthly_subscription_limit,
+            ),
+        )
+        return OrganisationSettings(**res)
+
+    def _request(self, method: str, url: str, skip_auth=False, **kwargs) -> Dict:
+
+        if not skip_auth:
+            self._set_auth()
+
+        headers = {"cecil-python-sdk-version": __version__}
+
+        try:
+            r = requests.request(
+                method=method,
+                url=self._base_url + url,
+                auth=self._api_auth,
+                headers=headers,
+                timeout=None,
+                **kwargs,
+            )
+            r.raise_for_status()
+            return r.json()
+
+        except requests.exceptions.ConnectionError:
+            raise Error("failed to connect to the Cecil Platform")
+
+        except requests.exceptions.HTTPError as err:
+            message = f"Request failed with status code {err.response.status_code}"
+            if err.response.text != "":
+                message += f": {err.response.text}"
+
+            match err.response.status_code:
+                case 400:
+                    _handle_bad_request(err.response)
+                case 401:
+                    raise Error("unauthorised")
+                case 404:
+                    _handle_not_found(err.response)
+                case 405:
+                    _handle_method_not_allowed(err.response)
+                case 422:
+                    _handle_unprocessable_entity(err.response)
+                case 429:
+                    _handle_too_many_requests(err.response)
+                case 500:
+                    raise Error("internal server error")
+                case _:
+                    raise Error(
+                        f"request failed with code {err.response.status_code}",
+                        err.response.text,
+                    )
+
+    def _get(self, url: str, **kwargs) -> Dict:
+        return self._request(method="get", url=url, **kwargs)
+
+    def _post(self, url: str, model: BaseModel, skip_auth=False, **kwargs) -> Dict:
+        return self._request(
+            method="post",
+            url=url,
+            json=model.model_dump(by_alias=True),
+            skip_auth=skip_auth,
+            **kwargs,
+        )
+
+    def _set_auth(self) -> None:
+        try:
+            api_key = os.environ["CECIL_API_KEY"]
+            self._api_auth = auth.HTTPBasicAuth(username=api_key, password="")
+        except KeyError:
+            raise ValueError("environment variable CECIL_API_KEY not set") from None

cecil/errors.py

@@ -0,0 +1,85 @@
+import json
+
+
+class Error(Exception):
+    def __init__(self, message: str, details=None):
+        self.message = message
+        self.details = details
+
+        if self.details is not None:
+            super().__init__(f"{self.message} \n{json.dumps(self.details, indent=2)}")
+            return
+
+        super().__init__(self.message)
+
+
+def _format_json_key(value: str):
+    return "".join(["_" + i.lower() if i.isupper() else i for i in value]).lstrip("_")
+
+
+def _is_json(value: str):
+    try:
+        json.loads(value)
+        return True
+    except ValueError:
+        return False
+
+
+def _handle_bad_request(response):
+    if not _is_json(response.text):
+        raise Error("bad request")
+
+    details = {}
+    for key, value in response.json().items():
+        details[_format_json_key(key)] = value
+
+    raise Error("bad request", details)
+
+
+def _handle_method_not_allowed(response):
+    if not _is_json(response.text):
+        raise Error("method not allowed")
+
+    details = {}
+    for key, value in response.json().items():
+        details[_format_json_key(key)] = value
+
+    raise Error("method not allowed", details)
+
+
+def _handle_not_found(response):
+    if not _is_json(response.text):
+        raise Error("resource not found")
+
+    details = {}
+    for key, value in response.json().items():
+        details[_format_json_key(key)] = value
+
+    raise Error("resource not found", details)
+
+
+def _handle_too_many_requests(response):
+    if not _is_json(response.text):
+        raise Error("too many requests")
+
+    details = {}
+
+    for key, value in response.json().items():
+        details[_format_json_key(key)] = value
+
+    raise Error("too many requests", details)
+
+
+def _handle_unprocessable_entity(response):
+    if not _is_json(response.text):
+        raise Error(f"failed to process request")
+
+    res_body = response.json()
+    if "params" not in res_body:
+        raise Error(f"failed to process request")
+
+    details = {}
+    for key, value in res_body["params"].items():
+        details[_format_json_key(key)] = value
+
+    raise Error(f"failed to process request", details)

cecil/models.py

@@ -0,0 +1,122 @@
+import datetime
+from typing import Dict, Optional, List
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+
+class AOI(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    id: str
+    external_ref: str
+    geometry: Optional[Dict] = None
+    hectares: float
+    created_at: datetime.datetime
+    created_by: str
+
+class AOICreate(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    geometry: Dict
+    external_ref: str
+
+
+class OrganisationSettings(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    monthly_subscription_limit: Optional[int]
+
+
+class RecoverAPIKey(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    message: str
+
+
+class RecoverAPIKeyRequest(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    email: str
+
+
+class RotateAPIKey(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    new_api_key: str
+
+
+class RotateAPIKeyRequest(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+
+class User(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    id: str
+    first_name: str
+    last_name: str
+    email: str
+    created_at: datetime.datetime
+    created_by: str
+
+
+class UserCreate(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    first_name: str
+    last_name: str
+    email: str
+
+
+class Bucket(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    name: str
+    prefix: str
+
+
+class BucketCredentials(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    access_key_id: str
+    secret_access_key: str
+    session_token: str
+    region: str
+    expiration: datetime.datetime
+
+
+class Band(BaseModel):
+    number: int
+    name: str
+    dtype: str
+    nodata: Optional[float | int] = None
+
+
+class File(BaseModel):
+    bands: List[Band]
+
+
+class SubscriptionListFiles(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    provider_name: str
+    dataset_id: str
+    dataset_name: str
+    aoi_id: str
+    subscription_id: str
+    bucket: Bucket
+    credentials: BucketCredentials
+    allowed_actions: List
+    file_mapping: Dict[str, File]
+
+
+class SubscriptionParquetFiles(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    files: List[str]
+
+
+class Subscription(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    id: str
+    aoi_id: str
+    dataset_id: str
+    external_ref: str
+    created_at: datetime.datetime
+    created_by: str
+
+
+class SubscriptionCreate(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    aoi_id: str
+    dataset_id: str
+    external_ref: str

cecil/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.3"

cecil/xarray.py

@@ -0,0 +1,131 @@
+import re
+from datetime import datetime
+
+import boto3
+import dask
+import rasterio
+import rasterio.session
+import rioxarray
+import xarray
+import numpy as np
+
+from .models import SubscriptionListFiles
+
+
+def load_xarray(res: SubscriptionListFiles) -> xarray.Dataset:
+    session = boto3.session.Session(
+        aws_access_key_id=res.credentials.access_key_id,
+        aws_secret_access_key=res.credentials.secret_access_key,
+        aws_session_token=res.credentials.session_token,
+        region_name=res.credentials.region,
+    )
+
+    keys = _list_keys(session, res.bucket.name, res.bucket.prefix)
+
+    if not keys:
+        return xarray.Dataset()
+
+    timestamp_pattern = re.compile(r"\d{4}/\d{2}/\d{2}/\d{2}/\d{2}/\d{2}")
+    data_vars = {}
+
+    with rasterio.env.Env(
+        session=rasterio.session.AWSSession(session),
+    ):
+        first_file = rioxarray.open_rasterio(
+            f"s3://{res.bucket.name}/{keys[0]}", chunks="auto"
+        )
+
+    for key in keys:
+        filename = key.split("/")[-1]
+
+        file_info = res.file_mapping.get(filename)
+        if not file_info:
+            continue
+
+        timestamp_str = timestamp_pattern.search(key).group()
+
+        for band_info in file_info.bands:
+            lazy_array = dask.array.from_delayed(
+                dask.delayed(_load_file)(
+                    session, f"s3://{res.bucket.name}/{key}", band_info.number
+                ),
+                shape=(
+                    first_file.rio.height,
+                    first_file.rio.width,
+                ),
+                dtype=band_info.dtype,
+            )
+
+            nodata = band_info.nodata if band_info.nodata is not None else np.nan
+
+            band_da = xarray.DataArray(
+                lazy_array,
+                dims=("y", "x"),
+                coords={
+                    "y": first_file.y.values,
+                    "x": first_file.x.values,
+                },
+                attrs={
+                    "AREA_OR_POINT": first_file.attrs["AREA_OR_POINT"],
+                    "_FillValue": np.dtype(band_info.dtype).type(nodata),
+                    "scale_factor": first_file.attrs["scale_factor"],
+                    "add_offset": first_file.attrs["add_offset"],
+                },
+            )
+            # band_da.encoding = first_file.encoding.copy() # TODO: is it the same for all files?
+            band_da.rio.write_crs(first_file.rio.crs, inplace=True)
+            band_da.rio.write_transform(first_file.rio.transform(), inplace=True)
+
+            band_da.name = band_info.name
+
+            # Dataset with time dimension
+            if timestamp_str != "0000/00/00/00/00/00":
+                t = datetime.strptime(timestamp_str, "%Y/%m/%d/%H/%M/%S")
+                band_da = band_da.expand_dims("time")
+                band_da = band_da.assign_coords(time=[t])
+
+            if band_info.name not in data_vars:
+                data_vars[band_info.name] = []
+
+            data_vars[band_info.name].append(band_da)
+
+    for var_name, time_series in data_vars.items():
+        if "time" in time_series[0].dims:
+            data_vars[var_name] = xarray.concat(time_series, dim="time", join="exact")
+        else:
+            data_vars[var_name] = time_series[0]
+
+    return xarray.Dataset(
+        data_vars=data_vars,
+        attrs={
+            "provider_name": res.provider_name,
+            "dataset_name": res.dataset_name,
+            "dataset_id": res.dataset_id,
+            "aoi_id": res.aoi_id,
+            "subscription_id": res.subscription_id,
+        },
+    )
+
+
+def _load_file(aws_session: boto3.session.Session, url: str, band_num: int):
+    with rasterio.env.Env(
+        session=rasterio.session.AWSSession(aws_session),
+    ):
+        with rasterio.open(url) as src:
+            return src.read(band_num)
+
+
+def _list_keys(session: boto3.session.Session, bucket_name, prefix) -> list[str]:
+    s3_client = session.client("s3")
+    paginator = s3_client.get_paginator("list_objects_v2")
+    page_iterator = paginator.paginate(
+        Bucket=bucket_name,
+        Prefix=prefix,
+    )
+
+    keys = []
+    for page in page_iterator:
+        for obj in page.get("Contents", []):
+            keys.append(obj["Key"])
+
+    return keys

cecil-0.1.3.dist-info/METADATA

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: cecil
+Version: 0.1.3
+Summary: Python SDK for Cecil Earth
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: boto3<2.0.0,>=1.42.0
+Requires-Dist: dask>=2025.9.1
+Requires-Dist: pyarrow<23.0.0,>=22.0.0
+Requires-Dist: pydantic<3.0.0,>=2.11.9
+Requires-Dist: requests<3.0.0,>=2.32.5
+Requires-Dist: rioxarray<1.0.0,>=0.19.0
+Requires-Dist: xarray>=2025.6.1
+Description-Content-Type: text/markdown
+
+# Cecil SDK
+
+Please refer to the Cecil documentation:
+
+https://docs.cecil.earth

cecil-0.1.3.dist-info/RECORD

@@ -0,0 +1,10 @@
+cecil/__init__.py,sha256=AEcRl73BDSAQe6W0d1PDD87IEcumARtREl7dCVa_YQY,86
+cecil/client.py,sha256=qv4Pm3EF3Q-TXBkcD_njYjrCipvgNYhA_tYyut_p5rs,6593
+cecil/errors.py,sha256=EnyYvFfU_JWYTTRax58bdwOndri2f-HzbqyzxtoV8uo,2100
+cecil/models.py,sha256=KpeIjkrQ_9L_84F8wA837pn0tpBopDRT-9jRuBnTAHA,3053
+cecil/version.py,sha256=XEqb2aiIn8fzGE68Mph4ck1FtQqsR_am0wRWvrYPffQ,22
+cecil/xarray.py,sha256=OIYL8PPOA7ZxiJZA6eQLhJi9WvZmdokf6u-_BfPwwiE,4200
+cecil-0.1.3.dist-info/METADATA,sha256=AYJWa9PwH5osacVpBaMH4XXLjWviaij68P5j9c-m_0A,724
+cecil-0.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cecil-0.1.3.dist-info/licenses/LICENSE.txt,sha256=mUexcmfYx3bG1VIzAdQTOf_NzStYw6-QkKVdUY_d4i4,1066
+cecil-0.1.3.dist-info/RECORD,,

cecil-0.1.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cecil-0.1.3.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 cecilearth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.