spatioClimata 0.1.0__tar.gz

spatioclimata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nethum Perera
+
+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.

spatioclimata-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: spatioClimata
+Version: 0.1.0
+Summary: Copernicus climate and hydrology data pipeline toolkit with analytics-ready outputs.
+Author-email: Nethum Perera <nethumsemithaperera@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/nethumperera/spatioClimata
+Project-URL: Repository, https://github.com/nethumperera/spatioClimata
+Project-URL: Issues, https://github.com/nethumperera/spatioClimata/issues
+Keywords: copernicus,era5,glofas,climate,hydrology,geospatial,xarray,pipeline
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cdsapi>=0.7.3
+Requires-Dist: xarray>=2024.1.0
+Requires-Dist: numpy>=1.25.0
+Requires-Dist: netcdf4>=1.6.0
+Requires-Dist: h5netcdf>=1.3.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: typer>=0.12.3
+Requires-Dist: pydantic>=2.6.0
+Provides-Extra: dask
+Requires-Dist: dask[distributed]>=2024.4.1; extra == "dask"
+Requires-Dist: fsspec>=2024.3.1; extra == "dask"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.9.0; extra == "dev"
+Dynamic: license-file
+
+# spatioClimata
+
+spatioClimata is a Python package for requesting, validating, downloading, and transforming Copernicus climate and hydrology datasets into analytics-ready outputs.
+
+It is designed for ERA5, GloFAS, and extensible CDS/EWDS datasets, with an opinionated data engineering pipeline and optional Dask acceleration.
+
+## Why spatioClimata
+
+- Unified access to CDS and EWDS with one API key workflow.
+- Dataset capability checks before large downloads.
+- Hourly and daily workflows with optional frequency conversion.
+- Resumable, idempotent download pipeline for long-running jobs.
+- Analytics-ready outputs as xarray Dataset with NetCDF/Zarr export.
+- Optional Dask integration for chunked processing at scale.
+
+## Installation
+
+```bash
+pip install spatioClimata
+```
+
+For Dask-enabled workflows:
+
+```bash
+pip install "spatioClimata[dask]"
+```
+
+For development:
+
+```bash
+pip install "spatioClimata[dev,dask]"
+```
+
+## Quick Start
+
+```python
+from spatioclimata import (
+    AreaBBox,
+    TimeRange,
+    FetchRequest,
+    fetch,
+)
+
+request = FetchRequest(
+    dataset="derived-era5-single-levels-daily-statistics",
+    variables=["total_precipitation", "2m_temperature"],
+  time_range=TimeRange.from_strings("2020-01-01", "2020-12-31"),
+  area=AreaBBox.from_sequence([6.22, 80.41, 5.91, 80.64]),
+    frequency="daily",
+    output_dir="./outputs",
+)
+
+result = fetch(request, open_browser_on_missing_key=True)
+print(result.saved_files)
+```
+
+## CLI Usage
+
+Initialize credentials:
+
+```bash
+spatioclimata auth init --open-browser
+```
+
+List datasets:
+
+```bash
+spatioclimata datasets list
+```
+
+Run a download:
+
+```bash
+spatioclimata fetch \
+  --dataset derived-era5-single-levels-daily-statistics \
+  --variables total_precipitation,2m_temperature \
+  --start 2020-01-01 \
+  --end 2020-12-31 \
+  --area 6.22,80.41,5.91,80.64 \
+  --frequency daily \
+  --output-dir ./outputs
+```
+
+## Account and API Key Onboarding
+
+The package needs a Copernicus API key.
+
+- `spatioclimata auth init --open-browser` opens signup and API key pages.
+- Credentials are saved to a local config file with restricted permissions when possible.
+- Environment variables are also supported:
+  - `SPATIOCLIMATA_API_KEY`
+  - `ERA5_Key`
+
+## Project Layout
+
+- `src/spatioclimata/`: package source
+- `tests/`: unit tests
+- `examples/`: runnable usage examples
+- `docs/`: architecture and usage guides
+- `.github/workflows/`: CI
+- `website/`: static project website (GitHub Pages source)
+- `scripts/`: helper scripts for repo bootstrap, website sync, and releases
+
+## Documentation Index
+
+- [Quickstart](docs/quickstart.md)
+- [Architecture](docs/architecture.md)
+- [Pipeline Guide](docs/pipeline.md)
+- [Dataset Support](docs/dataset-support.md)
+- [Release and Deploy](docs/release-deploy.md)
+
+## Status
+
+Current release is an MVP foundation intended to be expanded with additional dataset adapters and transformations.
+
+## Release and Deployment
+
+### PyPI Publish
+
+- Workflow: `.github/workflows/publish-pypi.yml`
+- Trigger: push a version tag (example: `v0.1.0`)
+- Recommended: configure PyPI Trusted Publishing for this repository
+
+### Website Deploy
+
+- Workflow: `.github/workflows/deploy-pages.yml`
+- Source folder: `website/`
+- Trigger: push to `main` when website files change
+- GitHub setting required: enable GitHub Pages with "GitHub Actions" as source
+
+## License
+
+MIT

spatioclimata-0.1.0/README.md

@@ -0,0 +1,133 @@
+# spatioClimata
+
+spatioClimata is a Python package for requesting, validating, downloading, and transforming Copernicus climate and hydrology datasets into analytics-ready outputs.
+
+It is designed for ERA5, GloFAS, and extensible CDS/EWDS datasets, with an opinionated data engineering pipeline and optional Dask acceleration.
+
+## Why spatioClimata
+
+- Unified access to CDS and EWDS with one API key workflow.
+- Dataset capability checks before large downloads.
+- Hourly and daily workflows with optional frequency conversion.
+- Resumable, idempotent download pipeline for long-running jobs.
+- Analytics-ready outputs as xarray Dataset with NetCDF/Zarr export.
+- Optional Dask integration for chunked processing at scale.
+
+## Installation
+
+```bash
+pip install spatioClimata
+```
+
+For Dask-enabled workflows:
+
+```bash
+pip install "spatioClimata[dask]"
+```
+
+For development:
+
+```bash
+pip install "spatioClimata[dev,dask]"
+```
+
+## Quick Start
+
+```python
+from spatioclimata import (
+    AreaBBox,
+    TimeRange,
+    FetchRequest,
+    fetch,
+)
+
+request = FetchRequest(
+    dataset="derived-era5-single-levels-daily-statistics",
+    variables=["total_precipitation", "2m_temperature"],
+  time_range=TimeRange.from_strings("2020-01-01", "2020-12-31"),
+  area=AreaBBox.from_sequence([6.22, 80.41, 5.91, 80.64]),
+    frequency="daily",
+    output_dir="./outputs",
+)
+
+result = fetch(request, open_browser_on_missing_key=True)
+print(result.saved_files)
+```
+
+## CLI Usage
+
+Initialize credentials:
+
+```bash
+spatioclimata auth init --open-browser
+```
+
+List datasets:
+
+```bash
+spatioclimata datasets list
+```
+
+Run a download:
+
+```bash
+spatioclimata fetch \
+  --dataset derived-era5-single-levels-daily-statistics \
+  --variables total_precipitation,2m_temperature \
+  --start 2020-01-01 \
+  --end 2020-12-31 \
+  --area 6.22,80.41,5.91,80.64 \
+  --frequency daily \
+  --output-dir ./outputs
+```
+
+## Account and API Key Onboarding
+
+The package needs a Copernicus API key.
+
+- `spatioclimata auth init --open-browser` opens signup and API key pages.
+- Credentials are saved to a local config file with restricted permissions when possible.
+- Environment variables are also supported:
+  - `SPATIOCLIMATA_API_KEY`
+  - `ERA5_Key`
+
+## Project Layout
+
+- `src/spatioclimata/`: package source
+- `tests/`: unit tests
+- `examples/`: runnable usage examples
+- `docs/`: architecture and usage guides
+- `.github/workflows/`: CI
+- `website/`: static project website (GitHub Pages source)
+- `scripts/`: helper scripts for repo bootstrap, website sync, and releases
+
+## Documentation Index
+
+- [Quickstart](docs/quickstart.md)
+- [Architecture](docs/architecture.md)
+- [Pipeline Guide](docs/pipeline.md)
+- [Dataset Support](docs/dataset-support.md)
+- [Release and Deploy](docs/release-deploy.md)
+
+## Status
+
+Current release is an MVP foundation intended to be expanded with additional dataset adapters and transformations.
+
+## Release and Deployment
+
+### PyPI Publish
+
+- Workflow: `.github/workflows/publish-pypi.yml`
+- Trigger: push a version tag (example: `v0.1.0`)
+- Recommended: configure PyPI Trusted Publishing for this repository
+
+### Website Deploy
+
+- Workflow: `.github/workflows/deploy-pages.yml`
+- Source folder: `website/`
+- Trigger: push to `main` when website files change
+- GitHub setting required: enable GitHub Pages with "GitHub Actions" as source
+
+## License
+
+MIT

spatioclimata-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spatioClimata"
+version = "0.1.0"
+description = "Copernicus climate and hydrology data pipeline toolkit with analytics-ready outputs."
+readme = "README.md"
+authors = [
+  { name = "Nethum Perera", email = "nethumsemithaperera@gmail.com" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["copernicus", "era5", "glofas", "climate", "hydrology", "geospatial", "xarray", "pipeline"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Atmospheric Science",
+  "Topic :: Scientific/Engineering :: Hydrology",
+]
+dependencies = [
+  "cdsapi>=0.7.3",
+  "xarray>=2024.1.0",
+  "numpy>=1.25.0",
+  "netcdf4>=1.6.0",
+  "h5netcdf>=1.3.0",
+  "python-dotenv>=1.0.1",
+  "typer>=0.12.3",
+  "pydantic>=2.6.0",
+]
+
+[project.optional-dependencies]
+dask = [
+  "dask[distributed]>=2024.4.1",
+  "fsspec>=2024.3.1",
+]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-cov>=5.0.0",
+  "ruff>=0.4.0",
+  "mypy>=1.9.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/nethumperera/spatioClimata"
+Repository = "https://github.com/nethumperera/spatioClimata"
+Issues = "https://github.com/nethumperera/spatioClimata/issues"
+
+[project.scripts]
+spatioclimata = "spatioclimata.cli:app"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E501"]

spatioclimata-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spatioclimata-0.1.0/src/spatioClimata.egg-info/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: spatioClimata
+Version: 0.1.0
+Summary: Copernicus climate and hydrology data pipeline toolkit with analytics-ready outputs.
+Author-email: Nethum Perera <nethumsemithaperera@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/nethumperera/spatioClimata
+Project-URL: Repository, https://github.com/nethumperera/spatioClimata
+Project-URL: Issues, https://github.com/nethumperera/spatioClimata/issues
+Keywords: copernicus,era5,glofas,climate,hydrology,geospatial,xarray,pipeline
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cdsapi>=0.7.3
+Requires-Dist: xarray>=2024.1.0
+Requires-Dist: numpy>=1.25.0
+Requires-Dist: netcdf4>=1.6.0
+Requires-Dist: h5netcdf>=1.3.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: typer>=0.12.3
+Requires-Dist: pydantic>=2.6.0
+Provides-Extra: dask
+Requires-Dist: dask[distributed]>=2024.4.1; extra == "dask"
+Requires-Dist: fsspec>=2024.3.1; extra == "dask"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.9.0; extra == "dev"
+Dynamic: license-file
+
+# spatioClimata
+
+spatioClimata is a Python package for requesting, validating, downloading, and transforming Copernicus climate and hydrology datasets into analytics-ready outputs.
+
+It is designed for ERA5, GloFAS, and extensible CDS/EWDS datasets, with an opinionated data engineering pipeline and optional Dask acceleration.
+
+## Why spatioClimata
+
+- Unified access to CDS and EWDS with one API key workflow.
+- Dataset capability checks before large downloads.
+- Hourly and daily workflows with optional frequency conversion.
+- Resumable, idempotent download pipeline for long-running jobs.
+- Analytics-ready outputs as xarray Dataset with NetCDF/Zarr export.
+- Optional Dask integration for chunked processing at scale.
+
+## Installation
+
+```bash
+pip install spatioClimata
+```
+
+For Dask-enabled workflows:
+
+```bash
+pip install "spatioClimata[dask]"
+```
+
+For development:
+
+```bash
+pip install "spatioClimata[dev,dask]"
+```
+
+## Quick Start
+
+```python
+from spatioclimata import (
+    AreaBBox,
+    TimeRange,
+    FetchRequest,
+    fetch,
+)
+
+request = FetchRequest(
+    dataset="derived-era5-single-levels-daily-statistics",
+    variables=["total_precipitation", "2m_temperature"],
+  time_range=TimeRange.from_strings("2020-01-01", "2020-12-31"),
+  area=AreaBBox.from_sequence([6.22, 80.41, 5.91, 80.64]),
+    frequency="daily",
+    output_dir="./outputs",
+)
+
+result = fetch(request, open_browser_on_missing_key=True)
+print(result.saved_files)
+```
+
+## CLI Usage
+
+Initialize credentials:
+
+```bash
+spatioclimata auth init --open-browser
+```
+
+List datasets:
+
+```bash
+spatioclimata datasets list
+```
+
+Run a download:
+
+```bash
+spatioclimata fetch \
+  --dataset derived-era5-single-levels-daily-statistics \
+  --variables total_precipitation,2m_temperature \
+  --start 2020-01-01 \
+  --end 2020-12-31 \
+  --area 6.22,80.41,5.91,80.64 \
+  --frequency daily \
+  --output-dir ./outputs
+```
+
+## Account and API Key Onboarding
+
+The package needs a Copernicus API key.
+
+- `spatioclimata auth init --open-browser` opens signup and API key pages.
+- Credentials are saved to a local config file with restricted permissions when possible.
+- Environment variables are also supported:
+  - `SPATIOCLIMATA_API_KEY`
+  - `ERA5_Key`
+
+## Project Layout
+
+- `src/spatioclimata/`: package source
+- `tests/`: unit tests
+- `examples/`: runnable usage examples
+- `docs/`: architecture and usage guides
+- `.github/workflows/`: CI
+- `website/`: static project website (GitHub Pages source)
+- `scripts/`: helper scripts for repo bootstrap, website sync, and releases
+
+## Documentation Index
+
+- [Quickstart](docs/quickstart.md)
+- [Architecture](docs/architecture.md)
+- [Pipeline Guide](docs/pipeline.md)
+- [Dataset Support](docs/dataset-support.md)
+- [Release and Deploy](docs/release-deploy.md)
+
+## Status
+
+Current release is an MVP foundation intended to be expanded with additional dataset adapters and transformations.
+
+## Release and Deployment
+
+### PyPI Publish
+
+- Workflow: `.github/workflows/publish-pypi.yml`
+- Trigger: push a version tag (example: `v0.1.0`)
+- Recommended: configure PyPI Trusted Publishing for this repository
+
+### Website Deploy
+
+- Workflow: `.github/workflows/deploy-pages.yml`
+- Source folder: `website/`
+- Trigger: push to `main` when website files change
+- GitHub setting required: enable GitHub Pages with "GitHub Actions" as source
+
+## License
+
+MIT

spatioclimata-0.1.0/src/spatioClimata.egg-info/SOURCES.txt

@@ -0,0 +1,26 @@
+LICENSE
+README.md
+pyproject.toml
+src/spatioClimata.egg-info/PKG-INFO
+src/spatioClimata.egg-info/SOURCES.txt
+src/spatioClimata.egg-info/dependency_links.txt
+src/spatioClimata.egg-info/entry_points.txt
+src/spatioClimata.egg-info/requires.txt
+src/spatioClimata.egg-info/top_level.txt
+src/spatioclimata/__init__.py
+src/spatioclimata/__main__.py
+src/spatioclimata/api.py
+src/spatioclimata/auth.py
+src/spatioclimata/catalog.py
+src/spatioclimata/cli.py
+src/spatioclimata/exceptions.py
+src/spatioclimata/io.py
+src/spatioclimata/models.py
+src/spatioclimata/pipeline.py
+src/spatioclimata/request_builder.py
+src/spatioclimata/transforms.py
+src/spatioclimata/validation.py
+tests/test_models.py
+tests/test_request_builder.py
+tests/test_transforms.py
+tests/test_validation.py

spatioclimata-0.1.0/src/spatioClimata.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

spatioclimata-0.1.0/src/spatioClimata.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spatioclimata = spatioclimata.cli:app

spatioclimata-0.1.0/src/spatioClimata.egg-info/requires.txt

@@ -0,0 +1,18 @@
+cdsapi>=0.7.3
+xarray>=2024.1.0
+numpy>=1.25.0
+netcdf4>=1.6.0
+h5netcdf>=1.3.0
+python-dotenv>=1.0.1
+typer>=0.12.3
+pydantic>=2.6.0
+
+[dask]
+dask[distributed]>=2024.4.1
+fsspec>=2024.3.1
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=5.0.0
+ruff>=0.4.0
+mypy>=1.9.0

spatioclimata-0.1.0/src/spatioClimata.egg-info/top_level.txt

@@ -0,0 +1 @@
+spatioclimata

spatioclimata-0.1.0/src/spatioclimata/__init__.py

@@ -0,0 +1,18 @@
+"""spatioClimata public API."""
+
+from .api import fetch, init_auth, list_datasets, list_frequencies, list_variables
+from .models import AreaBBox, FetchRequest, FetchResult, TimeRange
+
+__all__ = [
+    "AreaBBox",
+    "TimeRange",
+    "FetchRequest",
+    "FetchResult",
+    "list_datasets",
+    "list_variables",
+    "list_frequencies",
+    "init_auth",
+    "fetch",
+]
+
+__version__ = "0.1.0"

spatioclimata-0.1.0/src/spatioclimata/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()