dynamical-catalog 0.2.0__tar.gz

dynamical_catalog-0.2.0/.github/workflows/integration.yml

@@ -0,0 +1,17 @@
+name: Integration
+
+on:
+  schedule:
+    - cron: "0 6 * * *"  # daily at 06:00 UTC
+  workflow_dispatch:
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/test_integration.py -v -m slow

dynamical_catalog-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Release & Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g. 0.2.0)"
+        required: true
+        type: string
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate version format
+        run: |
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "::error::Invalid version format '$VERSION'. Use semver (e.g. 0.2.0)"
+            exit 1
+          fi
+        env:
+          VERSION: ${{ inputs.version }}
+      - name: Bump version in pyproject.toml
+        run: sed -i "s/^version = \".*\"/version = \"$VERSION\"/" pyproject.toml
+        env:
+          VERSION: ${{ inputs.version }}
+      - name: Commit, tag, and push
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml
+          git diff --cached --quiet || git commit -m "Release v$VERSION"
+          git tag "v$VERSION"
+          git push origin main "v$VERSION"
+        env:
+          VERSION: ${{ inputs.version }}
+      - name: Create GitHub Release
+        run: gh release create "v$VERSION" --generate-notes
+        env:
+          VERSION: ${{ inputs.version }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    needs: release
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: v${{ inputs.version }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

dynamical_catalog-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+      - run: mypy src/dynamical_catalog/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v

dynamical_catalog-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+*.egg
+.DS_Store

dynamical_catalog-0.2.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: dynamical-catalog
+Version: 0.2.0
+Summary: Load dynamical.org weather datasets in one line
+Project-URL: Homepage, https://dynamical.org
+Project-URL: Repository, https://github.com/dynamical-org/dynamical-catalog
+Project-URL: Catalog, https://dynamical.org/catalog/
+Project-URL: Issues, https://github.com/dynamical-org/dynamical-catalog/issues
+Author-email: "dynamical.org" <feedback@dynamical.org>
+License-Expression: MIT
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.11
+Requires-Dist: aiohttp
+Requires-Dist: fsspec
+Requires-Dist: icechunk>=1.0.0
+Requires-Dist: xarray>=2025.1.2
+Requires-Dist: zarr>=3.0.8
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dynamical-catalog
+
+Load [dynamical.org](https://dynamical.org) weather datasets in one line.
+
+## Install
+
+```bash
+pip install dynamical-catalog
+```
+
+## Usage
+
+```python
+import dynamical_catalog
+
+# Optional: let us know who you are so we can improve the catalog!
+dynamical_catalog.identify("you@example.com")
+
+# Open a dataset as xarray (zarr v3)
+ds = dynamical_catalog.open("noaa-gfs-forecast")
+
+# Open via icechunk
+ds = dynamical_catalog.open("noaa-gfs-forecast", engine="icechunk")
+
+# Get the underlying zarr store
+store = dynamical_catalog.get_store("noaa-gfs-forecast")
+
+# Tab-completable catalog
+ds = dynamical_catalog.catalog.noaa_gfs_forecast.open()
+
+# List all available datasets
+dynamical_catalog.list()
+```

dynamical_catalog-0.2.0/README.md

@@ -0,0 +1,33 @@
+# dynamical-catalog
+
+Load [dynamical.org](https://dynamical.org) weather datasets in one line.
+
+## Install
+
+```bash
+pip install dynamical-catalog
+```
+
+## Usage
+
+```python
+import dynamical_catalog
+
+# Optional: let us know who you are so we can improve the catalog!
+dynamical_catalog.identify("you@example.com")
+
+# Open a dataset as xarray (zarr v3)
+ds = dynamical_catalog.open("noaa-gfs-forecast")
+
+# Open via icechunk
+ds = dynamical_catalog.open("noaa-gfs-forecast", engine="icechunk")
+
+# Get the underlying zarr store
+store = dynamical_catalog.get_store("noaa-gfs-forecast")
+
+# Tab-completable catalog
+ds = dynamical_catalog.catalog.noaa_gfs_forecast.open()
+
+# List all available datasets
+dynamical_catalog.list()
+```

dynamical_catalog-0.2.0/examples/01_quickstart.py

@@ -0,0 +1,22 @@
+"""Quickstart: open a dataset and read a single value."""
+
+import dynamical_catalog
+
+dynamical_catalog.identify("dynamical-catalog example")
+
+# Open the GFS analysis dataset (lazily — no data downloaded yet)
+ds = dynamical_catalog.open("noaa-gfs-analysis")
+
+# Read 2m temperature at a specific place and time
+temp = (
+    ds["temperature_2m"]
+    .sel(
+        time="2025-06-01T12",
+        latitude=40.7,  # New York City
+        longitude=-74.0,
+        method="nearest",
+    )
+    .compute()
+)
+
+print(f"Temperature in NYC on 2025-06-01 12Z: {temp.values:.1f} K")

dynamical_catalog-0.2.0/examples/02_list_datasets.py

@@ -0,0 +1,17 @@
+"""Browse the catalog and inspect dataset metadata."""
+
+import dynamical_catalog
+
+dynamical_catalog.identify("dynamical-catalog example")
+
+# List all available dataset IDs
+print("Available datasets:")
+for dataset_id in dynamical_catalog.list():
+    print(f"  {dataset_id}")
+
+# Use tab-completable catalog to inspect a dataset
+entry = dynamical_catalog.catalog.noaa_gfs_forecast
+print(f"\nDataset: {entry.name}")
+print(f"Description: {entry.description}")
+print(f"Zarr URL: {entry.zarr_url}")
+print(f"Icechunk available: {entry.icechunk_config is not None}")

dynamical_catalog-0.2.0/examples/03_get_store.py

@@ -0,0 +1,20 @@
+"""Get the underlying zarr Store for direct access."""
+
+import zarr
+
+import dynamical_catalog
+
+dynamical_catalog.identify("dynamical-catalog example")
+
+# get_store returns a zarr.abc.Store — the primitive underlying open()
+store = dynamical_catalog.get_store("noaa-gfs-forecast")
+
+# Open it with zarr directly
+group = zarr.open_group(store)
+print(f"Variables: {list(group.keys())}")
+
+# Or pass it to xarray yourself with custom options
+import xarray as xr  # noqa: E402
+
+ds = xr.open_zarr(store, chunks={"latitude": 100, "longitude": 100})
+print(ds)

dynamical_catalog-0.2.0/examples/04_forecast.py

@@ -0,0 +1,24 @@
+"""Work with forecast data: init_time and lead_time dimensions."""
+
+import dynamical_catalog
+
+dynamical_catalog.identify("dynamical-catalog example")
+
+# Open the GFS forecast dataset
+ds = dynamical_catalog.open("noaa-gfs-forecast")
+
+# Select one forecast initialization and a location
+forecast = ds["temperature_2m"].sel(
+    init_time="2025-06-01T00",
+    latitude=51.5,  # London
+    longitude=-0.1,
+    method="nearest",
+)
+
+# Get the max temperature across all lead times in this forecast
+max_temp = forecast.max().compute()
+print(f"Max forecast temperature: {max_temp.values:.1f} K")
+
+# Get the full time series for this forecast (lazy until .compute())
+print(f"\nForecast shape: {forecast.sizes}")
+print(f"Lead times: {forecast.lead_time.values[:5]} ...")

dynamical_catalog-0.2.0/examples/05_icechunk.py

@@ -0,0 +1,23 @@
+"""Open a dataset via Icechunk for transactional, versioned access."""
+
+import dynamical_catalog
+
+dynamical_catalog.identify("dynamical-catalog example")
+
+# Open the same dataset through Icechunk instead of Zarr v3
+ds = dynamical_catalog.open("noaa-gfs-forecast", engine="icechunk")
+
+# Usage is identical — it's still an xarray Dataset
+temp = ds["temperature_2m"].sel(
+    init_time="2025-06-01T00",
+    latitude=35.7,  # Tokyo
+    longitude=139.7,
+    method="nearest",
+)
+
+max_temp = temp.max().compute()
+print(f"Max forecast temperature in Tokyo: {max_temp.values:.1f} K")
+
+# Or get the raw icechunk store
+store = dynamical_catalog.get_store("noaa-gfs-forecast", engine="icechunk")
+print(f"Store type: {type(store).__name__}")

dynamical_catalog-0.2.0/examples/06_ensemble.py

@@ -0,0 +1,24 @@
+"""Work with ensemble forecast data (GEFS and ECMWF IFS ENS)."""
+
+import dynamical_catalog
+
+dynamical_catalog.identify("dynamical-catalog example")
+
+# Open the GEFS 35-day ensemble forecast
+ds = dynamical_catalog.open("noaa-gefs-forecast-35-day")
+
+# Select one initialization and location
+forecast = ds["temperature_2m"].sel(
+    init_time="2025-06-01T00",
+    latitude=48.9,  # Paris
+    longitude=2.3,
+    method="nearest",
+)
+
+# Compute the ensemble spread at lead_time = 5 days
+five_day = forecast.sel(lead_time="120h")
+ensemble_mean = five_day.mean(dim="ensemble_member").compute()
+ensemble_std = five_day.std(dim="ensemble_member").compute()
+
+print(f"5-day forecast ensemble mean: {ensemble_mean.values:.1f} K")
+print(f"5-day forecast ensemble std:  {ensemble_std.values:.1f} K")

dynamical_catalog-0.2.0/examples/07_precipitation.py

@@ -0,0 +1,19 @@
+"""Query high-resolution precipitation data from MRMS."""
+
+import dynamical_catalog
+
+dynamical_catalog.identify("dynamical-catalog example")
+
+# Open the MRMS hourly precipitation analysis (~1km resolution, CONUS only)
+ds = dynamical_catalog.open("noaa-mrms-conus-analysis-hourly")
+
+# Get precipitation at a point over a time range
+precip = ds["precipitation_surface"].sel(
+    latitude=39.1,  # Kansas City, MO
+    longitude=-94.6,
+    method="nearest",
+    time=slice("2025-06-01", "2025-06-07"),
+)
+
+total = precip.sum().compute()
+print(f"Total precipitation in Kansas City, June 1-7 2025: {total.values:.1f} mm")

dynamical_catalog-0.2.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dynamical-catalog"
+version = "0.2.0"
+description = "Load dynamical.org weather datasets in one line"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "dynamical.org", email = "feedback@dynamical.org" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = [
+    "xarray>=2025.1.2",
+    "zarr>=3.0.8",
+    "fsspec",
+    "aiohttp",
+    "icechunk>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://dynamical.org"
+Repository = "https://github.com/dynamical-org/dynamical-catalog"
+Catalog = "https://dynamical.org/catalog/"
+Issues = "https://github.com/dynamical-org/dynamical-catalog/issues"
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-mock", "ruff", "mypy"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dynamical_catalog"]
+
+[tool.pytest.ini_options]
+addopts = "-m 'not slow'"
+markers = [
+    "slow: marks tests as slow (hit real network, run with pytest -m slow)",
+]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = ["zarr.*", "icechunk.*", "fsspec.*"]
+ignore_missing_imports = true

dynamical_catalog-0.2.0/src/dynamical_catalog/__init__.py

@@ -0,0 +1,87 @@
+"""dynamical_catalog - Load dynamical.org weather datasets in one line."""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import xarray as xr
+    from zarr.abc.store import Store
+
+from dynamical_catalog._catalog import Catalog
+from dynamical_catalog._stac import clear_cache, load_catalog, set_identifier
+
+__version__ = version("dynamical-catalog")
+
+catalog = Catalog(load_catalog)
+
+
+def identify(identifier: str) -> None:
+    """Set your identity for STAC catalog requests.
+
+    The identifier (typically an email or company name) is included in
+    the User-Agent header: ``dynamical-catalog/0.1.0 (identifier)``.
+
+    Args:
+        identifier: Email or company name, e.g. "marshall@dynamical.org".
+    """
+    set_identifier(identifier)
+
+
+def get_store(dataset_id: str, engine: str = "zarr") -> Store:
+    """Get a zarr Store for a dynamical.org dataset.
+
+    Args:
+        dataset_id: Dataset identifier (e.g. "noaa-gfs-forecast").
+            Underscores are also accepted (e.g. "noaa_gfs_forecast").
+        engine: "zarr" (default) or "icechunk".
+
+    Returns:
+        zarr.abc.Store
+    """
+    from dynamical_catalog._open import _get_store
+
+    return _get_store(_resolve(dataset_id), engine=engine)
+
+
+def open(dataset_id: str, engine: str = "zarr", **kwargs: Any) -> xr.Dataset:
+    """Open a dynamical.org dataset by ID.
+
+    Args:
+        dataset_id: Dataset identifier (e.g. "noaa-gfs-forecast").
+            Underscores are also accepted (e.g. "noaa_gfs_forecast").
+        engine: "zarr" (default) or "icechunk".
+        **kwargs: Passed through to xr.open_zarr().
+
+    Returns:
+        xarray.Dataset
+    """
+    from dynamical_catalog._open import _open_dataset
+
+    return _open_dataset(_resolve(dataset_id), engine=engine, **kwargs)
+
+
+def list() -> list[str]:  # type: ignore[valid-type]
+    """List available dataset IDs."""
+    return sorted(load_catalog().keys())
+
+
+def _resolve(dataset_id: str) -> dict[str, Any]:
+    datasets = load_catalog()
+    normalized_id = dataset_id.replace("_", "-")
+    if normalized_id not in datasets:
+        available = ", ".join(sorted(datasets.keys()))
+        raise ValueError(f"Unknown dataset {dataset_id!r}. Available: {available}")
+    return datasets[normalized_id]
+
+
+__all__ = [
+    "open",
+    "get_store",
+    "list",
+    "identify",
+    "catalog",
+    "clear_cache",
+    "__version__",
+]

dynamical_catalog-0.2.0/src/dynamical_catalog/_catalog.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from dynamical_catalog._dataset_entry import DatasetEntry
+
+
+class Catalog:
+    """Provides attribute-style access to dynamical.org datasets.
+
+    Supports tab-completion in IPython/Jupyter::
+
+        >>> import dynamical_catalog
+        >>> dynamical_catalog.catalog.<TAB>
+        >>> dynamical_catalog.catalog.noaa_gfs_forecast.open()
+    """
+
+    def __init__(self, loader: Callable[[], dict[str, dict[str, Any]]]) -> None:
+        self._loader = loader
+        self._entries: dict[str, DatasetEntry] = {}
+
+    @property
+    def _datasets(self) -> dict[str, dict[str, Any]]:
+        return self._loader()
+
+    def __getattr__(self, name: str) -> DatasetEntry:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        dataset_id = name.replace("_", "-")
+        datasets = self._datasets
+        if dataset_id not in datasets:
+            available = ", ".join(self._dataset_attr_names())
+            raise AttributeError(f"No dataset named {name!r}. Available: {available}")
+        if dataset_id not in self._entries:
+            self._entries[dataset_id] = DatasetEntry(datasets[dataset_id])
+        return self._entries[dataset_id]
+
+    def __dir__(self) -> list[str]:
+        return list(self._dataset_attr_names()) + list(super().__dir__())
+
+    def _dataset_attr_names(self) -> list[str]:
+        return [did.replace("-", "_") for did in self._datasets]
+
+    def __repr__(self) -> str:
+        names = self._dataset_attr_names()
+        return f"Catalog({len(names)} datasets: {', '.join(names)})"

dynamical_catalog-0.2.0/src/dynamical_catalog/_dataset_entry.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import xarray as xr
+    from zarr.abc.store import Store
+
+
+class DatasetEntry:
+    """A single dataset from the dynamical.org catalog."""
+
+    def __init__(self, data: dict[str, Any]) -> None:
+        self._data = data
+
+    @property
+    def id(self) -> str:
+        return self._data["id"]
+
+    @property
+    def name(self) -> str:
+        return self._data["name"]
+
+    @property
+    def description(self) -> str:
+        return self._data["description"]
+
+    @property
+    def zarr_url(self) -> str:
+        return self._data["zarr_url"]
+
+    @property
+    def icechunk_config(self) -> dict[str, str] | None:
+        return self._data.get("icechunk")
+
+    @property
+    def status(self) -> str:
+        return self._data["status"]
+
+    def get_store(self, engine: str = "zarr") -> Store:
+        """Get a zarr Store for this dataset.
+
+        Args:
+            engine: "zarr" (default) or "icechunk".
+
+        Returns:
+            zarr.abc.Store
+        """
+        from dynamical_catalog._open import _get_store
+
+        return _get_store(self._data, engine=engine)
+
+    def open(self, engine: str = "zarr", **kwargs: Any) -> xr.Dataset:
+        """Open this dataset as an xarray Dataset.
+
+        Args:
+            engine: "zarr" (default) or "icechunk".
+            **kwargs: Passed through to xr.open_zarr().
+
+        Returns:
+            xarray.Dataset
+        """
+        from dynamical_catalog._open import _open_dataset
+
+        return _open_dataset(self._data, engine=engine, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"DatasetEntry({self.id!r}, {self.name!r})"