stormtrack 0.4.0__tar.gz

stormtrack-0.4.0/.github/dependabot.yml

@@ -0,0 +1,28 @@
+version: 2
+updates:
+  # Python dependencies declared in pyproject.toml.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      # One PR for routine minor/patch bumps to keep the noise down.
+      python-minor:
+        update-types: ["minor", "patch"]
+    labels: ["dependencies"]
+    commit-message:
+      prefix: "deps"
+
+  # GitHub Actions used in the workflows (checkout, setup-python, publish, ...).
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      actions:
+        patterns: ["*"]
+    labels: ["ci", "dependencies"]
+    commit-message:
+      prefix: "ci"

stormtrack-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: lint (black + ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0   # tags for hatch-vcs version
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked --extra lint
+      - name: black --check
+        run: uv run black --check .
+      - name: ruff check
+        run: uv run ruff check .
+
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0   # tags for hatch-vcs version
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Sync (locked) with dev extras
+        run: uv sync --locked --extra dev --python ${{ matrix.python-version }}
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=stormtrack --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          flags: py${{ matrix.python-version }}
+          name: py${{ matrix.python-version }}
+          fail_ci_if_error: false
+
+  docs:
+    name: build docs (validation only)
+    runs-on: ubuntu-latest
+    # Only build docs once every other check (tests + lint) is green.
+    needs: [test, lint]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0   # tags for hatch-vcs version
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Sync (locked) with docs extras
+        run: uv sync --locked --extra docs
+      # Build only, to catch broken docs on a push/PR. Nothing is uploaded or
+      # published from here — the hosted docs (incl. per-PR previews) are built
+      # by Read the Docs, not GitHub.
+      - name: Build HTML docs (executes example notebooks)
+        run: uv run sphinx-build -b html -W --keep-going docs docs/_build/html

stormtrack-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,71 @@
+name: Release
+
+# On a new release (a v* tag, or the update-dataset pipeline after it bumps the
+# version), build the distributions and publish them straight to TestPyPI + PyPI.
+# Nothing is uploaded to GitHub: no workflow artifacts, and the GitHub Release
+# carries notes only (no dist files attached).
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      ref:
+        description: "Tag/ref to build and release"
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # create the GitHub Release (notes only)
+      id-token: write   # trusted publishing to PyPI/TestPyPI (OIDC)
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Build distributions
+        run: |
+          uv build                     # sdist + wheel (version from the git tag)
+          uvx twine check dist/*
+
+      - name: Publish to TestPyPI
+        # TestPyPI is a smoke test, not the release — don't let its flakiness
+        # (it times out sometimes) block the real PyPI publish below.
+        continue-on-error: true
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+          # Both publishes share one dist/; let only the PyPI step generate the
+          # PEP 740 attestations, otherwise the second publish errors on the
+          # attestation files the first one left behind.
+          attestations: false
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+      # Marks the release in GitHub with auto-generated notes. No dist files are
+      # attached — the artifacts live on PyPI/TestPyPI.
+      - name: Create GitHub Release (notes only)
+        uses: softprops/action-gh-release@v3
+        with:
+          tag_name: ${{ inputs.ref || github.ref_name }}
+          generate_release_notes: true

stormtrack-0.4.0/.github/workflows/update-dataset.yml

@@ -0,0 +1,104 @@
+name: Update dataset
+
+# Rebuild the committed datasets (IMD workbook + IBTrACS North Indian Ocean) once a month.
+# - If IMD hasn't changed, nothing is committed and no release is made.
+# - If IMD changed and the new file parses + validates, data/ is updated,
+#   committed, the version is bumped + tagged, and a release is published.
+# - If the new file fails to parse or validate, the job FAILS (red X + GitHub's
+#   failure notification email) and the committed dataset is left untouched.
+on:
+  schedule:
+    - cron: "0 6 1 * *"   # 06:00 UTC on the 1st of every month
+  workflow_dispatch:
+    inputs:
+      force:
+        description: "Rebuild even if the IMD source is unchanged"
+        type: boolean
+        default: false
+
+permissions:
+  contents: write   # push the refreshed data/, version bump, and tag
+
+concurrency:
+  group: update-dataset
+  cancel-in-progress: false
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.commit.outputs.changed }}
+      version: ${{ steps.commit.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0   # tags needed so hatch-vcs derives the version
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install package (with pipeline extra)
+        run: uv pip install --system -e ".[all]"
+
+      # If this step exits non-zero (parse/validation failure) the job fails and
+      # no commit happens — the previous dataset stays in place.
+      - name: Rebuild dataset from IMD
+        run: |
+          stormtrack build --data-dir data \
+            ${{ (github.event_name == 'workflow_dispatch' && inputs.force) && '--force' || '' }}
+
+      # Independent fail-safe: a bad IBTrACS file leaves data/ibtracs untouched.
+      - name: Rebuild IBTrACS (North Indian Ocean) dataset
+        run: stormtrack build-ibtracs --data-dir data ${{ (github.event_name == 'workflow_dispatch' && inputs.force) && '--force' || '' }}
+
+      - name: Commit and tag if the dataset changed
+        id: commit
+        run: |
+          if [ -z "$(git status --porcelain data)" ]; then
+            echo "No dataset changes to commit."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # Version comes from the git tag (hatch-vcs): bump the patch of the
+          # latest v* tag. No source file to edit.
+          LATEST="$(git describe --tags --abbrev=0 --match 'v*' 2>/dev/null || echo v0.0.0)"
+          NEW_VERSION="$(python - "$LATEST" <<'PY'
+          import re, sys
+          m = re.match(r"v(\d+)\.(\d+)\.(\d+)", sys.argv[1])
+          major, minor, patch = map(int, m.groups())
+          print(f"v{major}.{minor}.{patch + 1}")
+          PY
+          )"
+
+          git add data
+          git commit -m "data: refresh IMD best tracks and IBTrACS NI (${NEW_VERSION})"
+          git tag "${NEW_VERSION}"
+          git push origin HEAD --follow-tags
+
+          echo "Committed dataset update and tagged ${NEW_VERSION}."
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+          echo "version=${NEW_VERSION}" >> "$GITHUB_OUTPUT"
+
+  # Publish only when the dataset actually changed. Reuses the release pipeline
+  # (build -> TestPyPI -> PyPI -> GitHub Release) against the freshly-created tag.
+  release:
+    needs: update
+    if: needs.update.outputs.changed == 'true'
+    uses: ./.github/workflows/release.yml
+    with:
+      ref: ${{ needs.update.outputs.version }}
+    permissions:
+      contents: write
+      id-token: write
+    secrets: inherit

stormtrack-0.4.0/.gitignore

@@ -0,0 +1,30 @@
+.DS_Store
+src/stormtrack/_version.py
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Docs build artifacts
+docs/_build/
+docs/jupyter_execute/
+docs/**/jupyter_execute/
+.jupyter_cache/
+docs/api/_autosummary/
+*.xlsx
+*.parquet
+.cache/
+
+# ...but the *published* dataset committed by the pipeline must be tracked.
+!data/
+!data/*.parquet
+!data/manifest.json
+!data/ibtracs/
+!data/ibtracs/*.parquet
+!data/ibtracs/manifest.json

stormtrack-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+# Style / syntax gate. Runs on `git commit` and `git push`.
+# Install once:  pre-commit install --hook-type pre-commit --hook-type pre-push
+default_stages: [pre-commit, pre-push]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=2048"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.21
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+
+  - repo: https://github.com/psf/black
+    rev: 26.5.1
+    hooks:
+      - id: black

stormtrack-0.4.0/.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs build configuration
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+formats:
+  - htmlzip

stormtrack-0.4.0/.zenodo.json

@@ -0,0 +1,20 @@
+{
+  "title": "stormtrack: Tropical-cyclone best tracks and forecasts in Python (IMD, IBTrACS, NHC/JTWC)",
+  "description": "A Python library that serves tropical-cyclone best tracks (the India Meteorological Department RSMC New Delhi record and IBTrACS) and real-time NHC/JTWC forecasts as tidy pandas DataFrames and CF-style xarray Datasets, with analysis, comparison and forecast-verification tools. The parsed datasets are kept up to date automatically.",
+  "upload_type": "software",
+  "access_right": "open",
+  "license": "BSD-3-Clause",
+  "creators": [
+    { "name": "Syed, Hamid Ali", "orcid": "0000-0002-7188-2544" }
+  ],
+  "keywords": [
+    "cyclone",
+    "best-track",
+    "IMD",
+    "IBTrACS",
+    "North Indian Ocean",
+    "meteorology",
+    "xarray",
+    "pandas"
+  ]
+}

stormtrack-0.4.0/CITATION.cff

@@ -0,0 +1,36 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+title: "stormtrack: Tropical-cyclone best tracks and forecasts in Python (IMD, IBTrACS, NHC/JTWC)"
+type: software
+authors:
+  - family-names: Syed
+    given-names: Hamid Ali
+    orcid: "https://orcid.org/0000-0002-7188-2544"
+repository-code: "https://github.com/atmospy/stormtrack"
+url: "https://stormtrack.readthedocs.io/"
+license: BSD-3-Clause
+keywords:
+  - cyclone
+  - best-track
+  - IMD
+  - IBTrACS
+  - forecast verification
+  - North Indian Ocean
+  - meteorology
+  - xarray
+  - pandas
+# Zenodo Concept DOI (represents ALL versions and always resolves to the latest,
+# so it never changes between releases — this is the one to cite).
+doi: 10.5281/zenodo.21301659
+# Preferred citation: a release-agnostic reference (year only, no per-release
+# date or version) so citations stay uniform across releases.
+preferred-citation:
+  type: software
+  title: "stormtrack: Tropical-cyclone best tracks and forecasts in Python (IMD, IBTrACS, NHC/JTWC)"
+  authors:
+    - family-names: Syed
+      given-names: Hamid Ali
+      orcid: "https://orcid.org/0000-0002-7188-2544"
+  year: 2026
+  doi: 10.5281/zenodo.21301659
+  url: "https://stormtrack.readthedocs.io/"

stormtrack-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to stormtrack
+
+Thanks for helping! Bug reports, fixes, and features are all welcome via
+[issues](https://github.com/atmospy/stormtrack/issues) and pull requests.
+
+## Development setup ([uv](https://docs.astral.sh/uv/))
+
+[uv](https://docs.astral.sh/uv/) is the fastest way to get a dev environment.
+`uv sync` installs the **exact, locked** dependencies from `uv.lock` into `.venv`:
+
+```bash
+uv sync --extra dev --extra plot --extra docs   # everything, reproducibly
+```
+
+(Plain `pip` works too: `pip install -e ".[dev]"`.) The version is derived from
+git tags by [hatch-vcs](https://github.com/ofek/hatch-vcs), so there's no
+`__version__` to edit. If you change dependencies in `pyproject.toml`, refresh
+the lock with `uv lock` and commit it.
+
+## Checks
+
+```bash
+uv run pytest                     # tests (cartopy plot tests skip without cartopy)
+uv run black . && uv run ruff check .   # format + lint
+```
+
+Install the pre-commit hooks so these run automatically:
+
+```bash
+uv pip install pre-commit
+pre-commit install --hook-type pre-commit --hook-type pre-push
+```
+
+## Workflow
+
+Never push to `main` directly. Create a branch, open a PR, and let CI (lint +
+tests on Python 3.9–3.14 + docs build) go green before merging:
+
+```bash
+git switch -c my-change
+# ... commit ...
+git push -u origin my-change   # then open a PR
+```
+
+## Releases
+
+Releases are cut from a git tag — no source edit. Tag `main` and push:
+
+```bash
+git tag v0.2.6 && git push origin v0.2.6
+```
+
+That triggers the release workflow (build → TestPyPI → PyPI → GitHub Release →
+Zenodo). The dataset in `data/` also auto-updates monthly and cuts its own
+patch release when IMD publishes new data.

stormtrack-0.4.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Hamid Ali Syed
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.