cecil 0.0.7__tar.gz

cecil-0.0.7/.gitignore

@@ -0,0 +1,6 @@
+.idea
+.venv
+__pycache__
+dist/*
+venv
+*.ipynb

cecil-0.0.7/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+## Development installation
+
+Install packaging/distribution tools:
+
+```shell
+pip install hatch twine
+```
+
+Install linter
+
+```shell
+pip install black
+```
+
+From top-level repo directory, install the package in editable mode:
+
+```shell
+pip install -e .
+```
+
+Local edits to the package will immediately take effect.

cecil-0.0.7/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.

cecil-0.0.7/Makefile

@@ -0,0 +1,33 @@
+HL = @printf "\033[36m>> $1\033[0m\n"
+
+default: help
+
+.PHONY: help
+help:
+	@echo "Usage: make <target>\n"
+	@grep -E ".+:\s.*?##" $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?##"}; {printf "\033[36m%-24s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: build
+build: clean test ## Build package
+	$(call HL,build)
+	hatch build
+
+.PHONY: clean
+clean: ## Clean dist
+	$(call HL,clean)
+	hatch clean
+
+.PHONY: publish-test
+publish-test: build ## Publish package to testpypi
+	$(call HL,publish-test)
+	twine upload --repository testpypi dist/*
+
+.PHONY: publish-prod
+publish-prod: build ## Publish package to pypi
+	$(call HL,publish-prod)
+	twine upload --repository pypi dist/*
+
+.PHONY: test
+test: ## Run tests
+	$(call HL,test)
+	hatch test -v

cecil-0.0.7/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.3
+Name: cecil
+Version: 0.0.7
+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.8
+Requires-Dist: pydantic
+Requires-Dist: requests
+Requires-Dist: snowflake-connector-python[pandas]
+Description-Content-Type: text/markdown
+
+# Cecil SDK
+
+[![PyPI - Version](https://img.shields.io/pypi/v/cecil-sdk.svg)](https://pypi.org/project/cecil-sdk)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cecil-sdk.svg)](https://pypi.org/project/cecil-sdk)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Authentication](#authentication)
+- [License](#license)
+- [Examples](#examples)
+
+## Installation
+
+```shell
+pip install cecil
+```
+
+## Authentication
+
+Set `CECIL_API_KEY` environment variable to your Cecil API key.
+
+## Examples
+
+### Create an AOI and data request using the Cecil client
+
+```python
+import cecil
+
+client = cecil.Client()
+
+my_aoi = client.create_aoi(
+    name="My AOI",
+    geometry={
+        "type": "Polygon",
+        "coordinates": [
+            [
+                [145.410408835, -42.004083838],
+                [145.410408835, -42.004203978],
+                [145.410623191, -42.004203978],
+                [145.410623191, -42.004083838],
+                [145.410408835, -42.004083838],
+            ]
+        ],
+    },
+)
+
+# Get dataset ID from docs.cecil.earth -> Datasets
+planet_forest_carbon_diligence_id = "c2dd4f55-56f6-4d05-aae3-ba7c1dcd812f"
+
+my_data_request = client.create_data_request(
+    aoi_id=my_aoi.id,
+    dataset_id=planet_forest_carbon_diligence_id,
+)
+
+print(client.get_data_request(my_data_request.id).status)
+```
+
+### Create a reprojection using the Cecil client (once data request is completed)
+
+```python
+my_reprojection = client.create_reprojection(
+    data_request_id=my_data_request.id,
+    crs="EPSG:4326",
+    resolution=0.005,
+)
+
+print(client.get_reprojection(my_reprojection.id).status)
+```
+
+### Query data (once reprojection is completed)
+
+```python
+df = client.query(f'''
+    SELECT *
+    FROM 
+        planet.forest_carbon_diligence
+    WHERE
+        reprojection_id = '{my_reprojection.id}'
+''')
+```
+
+### Other client methods:
+
+```python
+client.list_aois()
+
+client.get_aoi(my_aoi.id)
+
+client.list_data_requests()
+
+client.get_data_request(my_data_request.id)
+
+client.list_reprojections()
+
+client.get_reprojection(my_reprojection.id)
+```
+
+## License
+
+`cecil` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

cecil-0.0.7/README.md

@@ -0,0 +1,103 @@
+# Cecil SDK
+
+[![PyPI - Version](https://img.shields.io/pypi/v/cecil-sdk.svg)](https://pypi.org/project/cecil-sdk)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cecil-sdk.svg)](https://pypi.org/project/cecil-sdk)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Authentication](#authentication)
+- [License](#license)
+- [Examples](#examples)
+
+## Installation
+
+```shell
+pip install cecil
+```
+
+## Authentication
+
+Set `CECIL_API_KEY` environment variable to your Cecil API key.
+
+## Examples
+
+### Create an AOI and data request using the Cecil client
+
+```python
+import cecil
+
+client = cecil.Client()
+
+my_aoi = client.create_aoi(
+    name="My AOI",
+    geometry={
+        "type": "Polygon",
+        "coordinates": [
+            [
+                [145.410408835, -42.004083838],
+                [145.410408835, -42.004203978],
+                [145.410623191, -42.004203978],
+                [145.410623191, -42.004083838],
+                [145.410408835, -42.004083838],
+            ]
+        ],
+    },
+)
+
+# Get dataset ID from docs.cecil.earth -> Datasets
+planet_forest_carbon_diligence_id = "c2dd4f55-56f6-4d05-aae3-ba7c1dcd812f"
+
+my_data_request = client.create_data_request(
+    aoi_id=my_aoi.id,
+    dataset_id=planet_forest_carbon_diligence_id,
+)
+
+print(client.get_data_request(my_data_request.id).status)
+```
+
+### Create a reprojection using the Cecil client (once data request is completed)
+
+```python
+my_reprojection = client.create_reprojection(
+    data_request_id=my_data_request.id,
+    crs="EPSG:4326",
+    resolution=0.005,
+)
+
+print(client.get_reprojection(my_reprojection.id).status)
+```
+
+### Query data (once reprojection is completed)
+
+```python
+df = client.query(f'''
+    SELECT *
+    FROM 
+        planet.forest_carbon_diligence
+    WHERE
+        reprojection_id = '{my_reprojection.id}'
+''')
+```
+
+### Other client methods:
+
+```python
+client.list_aois()
+
+client.get_aoi(my_aoi.id)
+
+client.list_data_requests()
+
+client.get_data_request(my_data_request.id)
+
+client.list_reprojections()
+
+client.get_reprojection(my_reprojection.id)
+```
+
+## License
+
+`cecil` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

cecil-0.0.7/__about__.py

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

cecil-0.0.7/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cecil"
+dynamic = ["version"]
+description = 'Python SDK for Cecil Earth'
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pydantic",
+    "requests",
+    "snowflake-connector-python[pandas]"
+]
+
+[tool.hatch.version]
+path = "__about__.py"
+
+[tool.hatch.envs.hatch-test]
+extra-dependencies = [
+    "responses"
+]

cecil-0.0.7/src/cecil/__init__.py

@@ -0,0 +1 @@
+from .client import Client

cecil-0.0.7/src/cecil/client.py

@@ -0,0 +1,131 @@
+import os
+from pydantic import BaseModel
+from typing import Dict, List
+import requests
+
+from requests import auth
+
+import snowflake.connector
+
+from .models import (
+    AOI,
+    AOICreate,
+    DataRequest,
+    DataRequestCreate,
+    Reprojection,
+    ReprojectionCreate,
+    SnowflakeCredentials,
+)
+
+# TODO: Documentation (Google style)
+# TODO: Add HTTP retries
+
+
+class Client:
+    def __init__(self, env="dev"):
+        self._api_auth = None
+        self._base_url = f"https://{env}-api.cecil.earth"  # TODO: hard-code to prod URL
+        self._snowflake_creds = None
+
+    def create_aoi(self, name: str, geometry: Dict) -> AOI:
+        # TODO: validate geometry
+        res = self._post(url="/v0/aois", model=AOICreate(name=name, geometry=geometry))
+        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 create_data_request(self, aoi_id: str, dataset_id: str) -> DataRequest:
+        res = self._post(
+            url="/v0/data-requests",
+            model=DataRequestCreate(aoi_id=aoi_id, dataset_id=dataset_id),
+        )
+        return DataRequest(**res)
+
+    def get_data_request(self, id: str) -> DataRequest:
+        res = self._get(url=f"/v0/data-requests/{id}")
+        return DataRequest(**res)
+
+    def list_data_requests(self):
+        res = self._get(url="/v0/data-requests")
+        return [DataRequest(**record) for record in res["records"]]
+
+    def create_reprojection(
+        self, data_request_id: str, crs: str, resolution: float
+    ) -> Reprojection:
+        # TODO: check if data request is completed before creating reprojection
+        res = self._post(
+            url="/v0/reprojections",
+            model=ReprojectionCreate(
+                data_request_id=data_request_id,
+                crs=crs,
+                resolution=resolution,
+            ),
+        )
+        return Reprojection(**res)
+
+    def get_reprojection(self, id: str) -> Reprojection:
+        res = self._get(url=f"/v0/reprojections/{id}")
+        return Reprojection(**res)
+
+    def list_reprojections(self) -> List[Reprojection]:
+        res = self._get(url="/v0/reprojections")
+        return [Reprojection(**record) for record in res["records"]]
+
+    def query(self, sql):
+        if self._snowflake_creds is None:
+            res = self._get(url="/v0/data-access-credentials")
+            self._snowflake_creds = SnowflakeCredentials(**res)
+
+        with snowflake.connector.connect(
+            account=self._snowflake_creds.account.get_secret_value(),
+            user=self._snowflake_creds.user.get_secret_value(),
+            password=self._snowflake_creds.password.get_secret_value(),
+        ) as conn:
+            df = conn.cursor().execute(sql).fetch_pandas_all()
+            df.columns = [x.lower() for x in df.columns]
+
+            return df
+
+    def _request(self, method: str, url: str, **kwargs) -> Dict:
+
+        self._set_auth()
+
+        try:
+            r = requests.request(
+                method=method,
+                url=self._base_url + url,
+                auth=self._api_auth,
+                timeout=None,
+                **kwargs,
+            )
+            r.raise_for_status()
+            return r.json()
+
+        except requests.exceptions.ConnectionError as err:
+            raise ValueError("Connection error") from err
+        except requests.exceptions.HTTPError as err:
+            if err.response.status_code == 403:
+                raise ValueError("Authentication error") from err
+            else:
+                raise
+
+    def _get(self, url: str, **kwargs) -> Dict:
+        return self._request(method="get", url=url, **kwargs)
+
+    def _post(self, url: str, model: BaseModel, **kwargs) -> Dict:
+        return self._request(
+            method="post", url=url, json=model.model_dump(by_alias=True), **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-0.0.7/src/cecil/models.py

@@ -0,0 +1,80 @@
+import datetime
+from enum import Enum
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, SecretStr
+from pydantic.alias_generators import to_camel
+
+
+class SubRequestStatus(str, Enum):
+    COMPLETED = "completed"
+    FAILED = "failed"
+    PROCESSING = "processing"
+
+
+class DataRequestStatus(str, Enum):
+    COMPLETED = "completed"
+    FAILED = "failed"
+    PROCESSING = "processing"
+
+
+class AOI(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    id: str
+    name: str
+    geometry: Dict
+    hectares: float
+    created: datetime.datetime
+
+
+class AOICreate(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    name: str
+    geometry: Dict
+
+
+class SubRequest(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    external_id: str
+    description: str
+    status: SubRequestStatus
+    error_message: Optional[str]
+
+
+class DataRequest(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    id: str
+    aoi_id: str
+    dataset_id: str
+    sub_requests: List[SubRequest]
+    status: DataRequestStatus
+    created: datetime.datetime
+
+
+class DataRequestCreate(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    aoi_id: str
+    dataset_id: str
+
+
+class Reprojection(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    id: str
+    data_request_id: str
+    crs: str
+    resolution: float
+    created: datetime.datetime
+
+
+class ReprojectionCreate(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    data_request_id: str
+    crs: str
+    resolution: float
+
+
+class SnowflakeCredentials(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    account: SecretStr
+    user: SecretStr
+    password: SecretStr

cecil-0.0.7/tests/test_client.py

@@ -0,0 +1,90 @@
+import responses
+
+from src.cecil.client import Client
+from src.cecil.models import DataRequest, DataRequestStatus
+
+FROZEN_TIME = "2024-01-01T00:00:00.000Z"
+
+
+def test_client_class():
+    client = Client()
+    assert client._base_url == "https://dev-api.cecil.earth"
+
+
+@responses.activate
+def test_client_create_data_request():
+    responses.add(
+        responses.POST,
+        "https://dev-api.cecil.earth/v0/data-requests",
+        json={
+            "id": "id",
+            "aoiId": "aoi_id",
+            "datasetId": "dataset_id",
+            "subRequests": [],
+            "status": "processing",
+            "created": FROZEN_TIME,
+        },
+        status=201,
+    )
+
+    client = Client()
+    res = client.create_data_request("aoi_id", "dataset_id")
+
+    assert res == DataRequest(
+        id="id",
+        aoiId="aoi_id",
+        datasetId="dataset_id",
+        subRequests=[],
+        status="processing",
+        created="2024-01-01T00:00:00.000Z",
+    )
+
+
+@responses.activate
+def test_client_list_data_requests():
+    responses.add(
+        responses.GET,
+        "https://dev-api.cecil.earth/v0/data-requests",
+        json={
+            "records": [
+                {
+                    "id": "data_request_id_1",
+                    "aoiId": "aoi_id",
+                    "datasetId": "dataset_id",
+                    "subRequests": [],  # TODO: Add some SubRequests
+                    "status": "processing",
+                    "created": "2024-09-19T04:45:57.561Z",
+                },
+                {
+                    "id": "data_request_id_2",
+                    "aoiId": "aoi_id",
+                    "datasetId": "dataset_id",
+                    "subRequests": [],  # TODO: Add some SubRequests
+                    "status": "completed",
+                    "created": "2024-09-19T04:54:38.252Z",
+                },
+            ]
+        },
+    )
+
+    client = Client()
+    data_requests = client.list_data_requests()
+
+    assert data_requests == [
+        DataRequest(
+            id="data_request_id_1",
+            aoiId="aoi_id",
+            datasetId="dataset_id",
+            subRequests=[],
+            status=DataRequestStatus.PROCESSING,
+            created="2024-09-19T04:45:57.561Z",
+        ),
+        DataRequest(
+            id="data_request_id_2",
+            aoiId="aoi_id",
+            datasetId="dataset_id",
+            subRequests=[],
+            status=DataRequestStatus.COMPLETED,
+            created="2024-09-19T04:54:38.252Z",
+        ),
+    ]