climagrid 0.1.0__tar.gz

climagrid-0.1.0/.dockerignore

@@ -0,0 +1,17 @@
+.git/
+.github/
+tests/
+docs/
+examples/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+*.parquet
+*.csv

climagrid-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check src/ tests/
+
+      - name: Run tests (no live APIs)
+        run: pytest tests/ -m "not integration" -q --tb=short
+
+      - name: Upload coverage report
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false

climagrid-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,26 @@
+name: Docs
+
+# Validate that the Sphinx build is clean on every PR to main
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-docs:
+    name: Build Sphinx docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install docs dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Build docs (warnings = errors)
+        run: sphinx-build -W -b html docs/ docs/_build/html

climagrid-0.1.0/.github/workflows/media.yml

@@ -0,0 +1,122 @@
+name: Regenerate README media
+
+# Runs on every published release (tag) OR manually from the Actions tab.
+# Generates:
+#   docs/assets/demo.gif       — animated terminal demo
+#   docs/assets/quickstart_map.png — notebook map screenshot
+# and commits both back to the default branch.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  # ─────────────────────────────────────────────────────────────────────────
+  # Job 1: animated demo gif
+  # ─────────────────────────────────────────────────────────────────────────
+  demo-gif:
+    name: Generate demo gif
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main        # always update main, not the tag
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install climagrid and demo dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Generate asciinema cast file
+        run: python docs/make_cast.py
+
+      - name: Install agg (asciinema gif renderer)
+        run: |
+          curl -sL https://github.com/asciinema/agg/releases/latest/download/agg-x86_64-unknown-linux-musl \
+               -o /usr/local/bin/agg
+          chmod +x /usr/local/bin/agg
+          agg --version
+
+      - name: Render cast to gif
+        run: |
+          agg docs/assets/demo.cast docs/assets/demo.gif \
+              --font-size 14 \
+              --speed 1.5 \
+              --theme monokai
+
+      - name: Upload gif as workflow artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: demo-gif
+          path: docs/assets/demo.gif
+          retention-days: 7
+
+      - name: Commit gif to main
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/assets/demo.cast docs/assets/demo.gif
+          git diff --cached --quiet && echo "No changes." || \
+            git commit -m "chore: regenerate demo gif [skip ci]" && git push
+
+
+  # ─────────────────────────────────────────────────────────────────────────
+  # Job 2: notebook screenshot
+  # ─────────────────────────────────────────────────────────────────────────
+  notebook-screenshot:
+    name: Generate quickstart map screenshot
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install climagrid and notebook dependencies
+        run: pip install -e ".[dev]" matplotlib
+
+      - name: Execute notebook headlessly
+        run: |
+          jupyter nbconvert \
+            --to notebook \
+            --execute \
+            --ExecutePreprocessor.timeout=300 \
+            --output /tmp/quickstart_executed.ipynb \
+            examples/quickstart.ipynb
+        env:
+          # Notebook saves map PNG to docs/assets/ via relative path
+          # No credentials needed — uses NASA POWER (public)
+          PYTHONPATH: src
+
+      - name: Verify PNG was generated
+        run: |
+          ls -lh docs/assets/quickstart_map.png
+          file docs/assets/quickstart_map.png
+
+      - name: Upload screenshot as workflow artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: quickstart-map
+          path: docs/assets/quickstart_map.png
+          retention-days: 7
+
+      - name: Commit screenshot to main
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/assets/quickstart_map.png
+          git diff --cached --quiet && echo "No changes." || \
+            git commit -m "chore: regenerate quickstart map screenshot [skip ci]" && git push

climagrid-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,95 @@
+name: Publish to PyPI
+
+# Triggered only when a version tag is pushed (e.g. v0.1.0)
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: read
+  # Required for OIDC Trusted Publisher authentication with PyPI
+  id-token: write
+
+jobs:
+  # ── 1. Run the full test suite before publishing ──────────────────────────
+  test:
+    name: Test before publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests (no live APIs)
+        run: pytest tests/ -m "not integration" -q --tb=short
+
+  # ── 2. Build the distribution ─────────────────────────────────────────────
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # ── 3. Publish to TestPyPI (dry-run) ──────────────────────────────────────
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/climagrid
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  # ── 4. Publish to PyPI (production) ───────────────────────────────────────
+  publish-pypi:
+    name: Publish to PyPI
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/climagrid
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

climagrid-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.hypothesis/
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+
+# Sphinx build output
+docs/_build/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Data / output files (user-generated, not committed)
+*.parquet
+*.nc
+

climagrid-0.1.0/.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false

climagrid-0.1.0/CITATION.cff

@@ -0,0 +1,39 @@
+cff-version: 1.2.0
+message: "If you use climagrid in your research or engineering work, please cite it as below."
+type: software
+title: climagrid
+abstract: >
+  Open-source Python toolkit that converts public NOAA, NASA, USDA, and U.S. Forest Service environmental data into standardized predictive-maintenance input features for electric utility grid resilience systems. Designed for rural electric cooperatives and municipal utilities serving approximately 42 million Americans.
+authors:
+  - family-names: Adesiji
+    given-names: Temidire
+    email: temidireadesiji@gmail.com
+repository-code: "https://github.com/TemidireAdesiji/climagrid"
+url: "https://climagrid.readthedocs.io"
+license: Apache-2.0
+version: "0.1.0"
+date-released: "2026-05-16"
+keywords:
+  - NOAA
+  - NASA
+  - USDA
+  - electric utility
+  - predictive maintenance
+  - grid resilience
+  - rural cooperative
+  - climate
+  - weather
+  - environmental data
+references:
+  - type: standard
+    title: "IEEE Standard for Calculating the Current-Temperature Relationship of Bare Overhead Conductors"
+    authors:
+      - name: "IEEE"
+    number: "738-2012"
+    year: 2012
+  - type: standard
+    title: "IEEE Guide for Loading Mineral-Oil-Immersed Transformers"
+    authors:
+      - name: "IEEE"
+    number: "C57.91-2011"
+    year: 2011

climagrid-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,43 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in the climagrid community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the project in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainer at temidireadesiji@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

climagrid-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to climagrid
+
+Thank you for helping improve grid resilience tooling for rural electric cooperatives.
+
+## Quick start
+
+```bash
+git clone https://github.com/TemidireAdesiji/climagrid.git
+cd climagrid
+uv pip install -e ".[dev]"
+uv run pytest tests/ -m "not integration" -q
+```
+
+## Adding a new data source
+
+1. Create `src/climagrid/sources/your_source.py` subclassing `BaseEnvironmentalSource`.
+2. Name columns using the `source_variable_unit` convention (e.g. `yourapi_temperature_2m`).
+3. Add column definitions to `src/climagrid/schema.py`.
+4. Add `"your_source"` to `_SOURCE_MAP` in `src/climagrid/pipeline/orchestrator.py`.
+5. Write unit tests with `responses` mocking. No live API calls in `tests/`.
+
+## Adding a new stress feature
+
+1. Create `src/climagrid/features/your_feature.py` with a class that has a `.compute(df) -> pd.DataFrame` method.
+2. The method must accept arbitrary extra columns and return a copy with the new `feat_` column added.
+3. Add the column spec to `FEATURE_COLUMNS` in `schema.py`.
+4. Add it to `_FEATURE_MAP` in `orchestrator.py`.
+
+## Code style
+
+- `ruff check src/ tests/` must pass (enforced in CI).
+- No live API calls in unit tests. Use the `responses` library for HTTP mocking.
+- All new columns must be defined in `schema.py` before being emitted.
+
+## Pull request process
+
+1. Fork and branch from `main`.
+2. Run `uv run pytest tests/ -m "not integration"` locally.
+3. Open a PR against `main` with a clear description of the change.
+4. A maintainer will review within 5 business days.
+
+## Reporting bugs
+
+Open an issue at https://github.com/TemidireAdesiji/climagrid/issues with:
+- Python version and OS
+- Minimal reproducible example
+- Full traceback
+
+## License
+
+By contributing, you agree your contributions will be licensed under the Apache 2.0 License.

climagrid-0.1.0/Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.12-slim
+
+LABEL maintainer="Temidire Adesiji <temidireadesiji@gmail.com>" \
+      description="climagrid — climate data, grid-ready" \
+      license="Apache-2.0"
+
+WORKDIR /app
+
+# Copy package manifest first so the install layer is cached when only src/ changes
+COPY pyproject.toml README.md LICENSE ./
+COPY src/ ./src/
+
+RUN pip install --no-cache-dir --upgrade pip \
+ && pip install --no-cache-dir --root-user-action=ignore .
+
+# Run as non-root
+RUN useradd --create-home appuser
+USER appuser
+
+ENTRYPOINT ["climagrid"]
+CMD ["--help"]

climagrid-0.1.0/GOVERNANCE.md

@@ -0,0 +1,39 @@
+# climagrid Governance
+
+## Project status
+
+climagrid is an open-source project released under the Apache 2.0 License with the explicit goal of being freely usable by any electric utility, rural cooperative, researcher, or regulator in the United States and worldwide.
+
+The Apache 2.0 license will never change. Patent grants and freedom from royalties are permanent.
+
+## Current model: Benevolent Dictator For Now (BDFN)
+
+The project is currently maintained by its author. Major decisions (API changes, new data source additions, schema column additions or renames) are made by the maintainer with input from the community via GitHub issues and discussions.
+
+## Commit rights
+
+Commit rights are granted to contributors who have:
+
+1. Submitted at least two accepted pull requests
+2. Demonstrated familiarity with the column schema conventions in `schema.py`
+3. Written tests that pass in CI without live API calls
+
+Request commit rights by opening a GitHub issue titled "Commit access request".
+
+## Decision process
+
+For non-breaking changes (new source adapters, new feature modules, documentation): a pull request with a passing CI and one maintainer approval is sufficient.
+
+For breaking changes (schema column renames, removed public API): a 14-day comment period on the relevant GitHub issue is required before merging.
+
+## Roadmap
+
+The roadmap is maintained at [docs/roadmap.md](docs/roadmap.md) and discussed in GitHub Discussions. Community members are encouraged to propose new data sources and feature modules through the issue tracker.
+
+## Evolution
+
+As the contributor base grows, governance will evolve toward a Steering Committee model with representatives from rural cooperatives and utility research organizations. Governance changes themselves require a 30-day comment period and consensus among existing committers.
+
+## Security
+
+Report security issues privately to temidireadesiji@gmail.com. Do not open public issues for security vulnerabilities. We aim to respond within 72 hours and publish an advisory within 14 days of a confirmed vulnerability.