eolas-data 1.2.0__tar.gz

eolas_data-1.2.0/.github/workflows/catalog-drift.yml

@@ -0,0 +1,101 @@
+name: Catalog drift detector
+
+# Pings when the live eolas.fyi catalog has gained namespaces or grown the
+# dataset count significantly without a corresponding library release. Opens
+# (or updates) a single tracking issue rather than spamming.
+
+on:
+  schedule:
+    - cron: "0 7 * * 1"  # Mondays 07:00 UTC
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Compare live catalog to baseline
+        id: drift
+        run: |
+          python <<'PY'
+          import json, os, urllib.request
+
+          # Baseline = the snapshot we shipped in the last release.
+          # Drift = anything that's changed since.
+          import importlib.util, pathlib
+          spec = importlib.util.spec_from_file_location(
+              "_dataset_names",
+              pathlib.Path("eolas_data/_dataset_names.py"),
+          )
+          module = importlib.util.module_from_spec(spec)
+          spec.loader.exec_module(module)
+          baseline = set(module.ALL_NAMES)
+          baseline_date = module.CATALOG_SNAPSHOT_DATE
+
+          with urllib.request.urlopen("https://api.eolas.fyi/v1/datasets", timeout=30) as r:
+              live = json.load(r)
+          live_names = {d["name"] for d in live}
+          live_namespaces = sorted({d["namespace"] for d in live})
+
+          baseline_namespaces = sorted({n.split("_", 1)[0] for n in baseline})  # crude — better via release-time metadata
+
+          added = sorted(live_names - baseline)
+          removed = sorted(baseline - live_names)
+          new_count = len(live_names)
+          base_count = len(baseline)
+          delta_pct = (new_count - base_count) / max(base_count, 1) * 100
+
+          # Threshold for "interesting" drift
+          significant = (
+              len(added) >= 10
+              or len(removed) >= 1
+              or abs(delta_pct) >= 5.0
+          )
+
+          summary = (
+              f"Baseline (release {baseline_date}): {base_count} datasets\\n"
+              f"Live now: {new_count} datasets ({delta_pct:+.1f}%)\\n\\n"
+              f"Added ({len(added)}): {', '.join(added[:30])}"
+              f"{' ...' if len(added) > 30 else ''}\\n\\n"
+              f"Removed ({len(removed)}): {', '.join(removed) or 'none'}"
+          )
+          print(summary)
+
+          with open(os.environ["GITHUB_OUTPUT"], "a") as f:
+              f.write(f"significant={'true' if significant else 'false'}\n")
+              f.write(f"new_count={new_count}\n")
+              f.write(f"base_count={base_count}\n")
+              f.write("summary<<EOF\n")
+              f.write(summary.replace("\\n", "\n"))
+              f.write("\nEOF\n")
+          PY
+
+      - name: Open or update drift issue
+        if: steps.drift.outputs.significant == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SUMMARY: ${{ steps.drift.outputs.summary }}
+          NEW_COUNT: ${{ steps.drift.outputs.new_count }}
+          BASE_COUNT: ${{ steps.drift.outputs.base_count }}
+        run: |
+          set -euo pipefail
+          TITLE="Catalog drift: ${BASE_COUNT} → ${NEW_COUNT} datasets"
+          BODY=$(printf 'The live API catalog has drifted from the shipped baseline.\n\n%s\n\n---\n\nIf this delta warrants a release: bump version, run `python -m eolas_data._regen_names`, commit, tag, push.\n' "$SUMMARY")
+
+          # Find an existing open drift issue (label `catalog-drift`) and update it; else create.
+          EXISTING=$(gh issue list --label catalog-drift --state open --json number --jq '.[0].number' || true)
+          if [ -n "$EXISTING" ]; then
+            gh issue edit "$EXISTING" --title "$TITLE" --body "$BODY"
+          else
+            gh label create catalog-drift --color BFD4F2 --description "Live catalog has drifted from shipped baseline" 2>/dev/null || true
+            gh issue create --title "$TITLE" --body "$BODY" --label catalog-drift
+          fi

eolas_data-1.2.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install hatchling build
+
+      - name: Build
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

eolas_data-1.2.0/.gitignore

@@ -0,0 +1,27 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Test caches
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Build / dist
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+.DS_Store

eolas_data-1.2.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: eolas-data
+Version: 1.2.0
+Summary: Python client for the eolas.fyi statistical data API (NZ, Australia, OECD)
+Project-URL: Homepage, https://eolas.fyi
+Project-URL: Documentation, https://phildonovan.github.io/vswarehouse-docs/
+Project-URL: Repository, https://github.com/phildonovan/eolas-data
+Project-URL: Bug Tracker, https://github.com/phildonovan/eolas-data/issues
+Author-email: Virtus Solutions <phil@virtus-solutions.io>
+License: MIT
+Keywords: api,australia,economics,eolas,new-zealand,statistics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: pandas>=1.5
+Requires-Dist: requests>=2.28
+Provides-Extra: cli
+Requires-Dist: rich>=13; extra == 'cli'
+Requires-Dist: typer>=0.12; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: geopandas>=0.14; extra == 'dev'
+Requires-Dist: pandas; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: responses; extra == 'dev'
+Requires-Dist: rich>=13; extra == 'dev'
+Requires-Dist: shapely>=2.0; extra == 'dev'
+Requires-Dist: typer>=0.12; extra == 'dev'
+Provides-Extra: geo
+Requires-Dist: geopandas>=0.14; extra == 'geo'
+Requires-Dist: shapely>=2.0; extra == 'geo'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5; extra == 'plot'
+Provides-Extra: polars
+Requires-Dist: polars>=0.20; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# eolas-data
+
+Python client for the [eolas.fyi](https://eolas.fyi) statistical data API — 717+ datasets across NZ, Australia, OECD, and more, served as tidy `pandas` DataFrames (or `polars` / `geopandas` if you prefer).
+
+```bash
+pip install eolas-data
+```
+
+## Quickstart
+
+```python
+from eolas_data import Client
+
+client = Client("your_api_key")   # or set EOLAS_API_KEY in env
+
+# Generic
+df = client.get("nz_cpi", start="2020-01-01")
+
+# Source-specific (sets the `eolas_source` metadata)
+df = client.statsnz("nz_cpi")
+df = client.oecd("nz_gdp_production_annual")
+
+# Discovery
+all_datasets = client.list()
+nz_only      = client.list("Stats NZ")
+meta         = client.info("nz_cpi")
+```
+
+Get an API key at <https://eolas.fyi/signup>. Free plan is 10 requests/month; Starter is 100; Pro is unlimited.
+
+## Command-line interface
+
+`pip install eolas-data[cli]` adds an `eolas` command for browsing, fetching, and
+scheduling — useful for shell scripts, cron jobs, and AI-agent workflows. Output
+auto-detects piping: rich tables in a terminal, newline-delimited JSON when
+stdout is piped.
+
+```bash
+# one-time setup
+eolas auth set-key
+eolas health
+
+# discover
+eolas datasets list --source "Stats NZ"
+eolas datasets list --search cpi --json | jq '.[].name'
+eolas datasets info nz_cpi
+eolas datasets preview nz_cpi --limit 5
+
+# fetch (verb matches the Python lib's client.get())
+eolas get nz_cpi --format csv > cpi.csv
+eolas get nz_cpi --start 2020-01-01 --format json | jq '.[].value'
+eolas get sa2_2023 --format parquet --out sa2.parquet
+```
+
+### Scheduling
+
+Set up recurring fetches without touching crontab/Task Scheduler syntax. Works
+on Linux, macOS (cron), and Windows (Task Scheduler).
+
+```bash
+eolas schedule add nz_cpi --daily   --out ~/data/cpi.csv
+eolas schedule add nz_gdp --weekly  --out ~/data/gdp.csv
+eolas schedule add nzd_usd --cron "0 */6 * * *" --out ~/data/fx.csv   # POSIX only
+
+eolas schedule list
+eolas schedule remove nz_cpi
+```
+
+Daily is the default. Pre-flight check refuses to install a schedule unless
+your API key is configured (otherwise the job would fail silently forever).
+
+### Integrations (Enterprise plan)
+
+Generate ready-to-run connector configs for popular data-pipeline tools — eolas
+becomes a one-command source for Meltano, Fivetran, or Azure Data Factory.
+
+```bash
+eolas integrate meltano             --datasets nz_cpi,nz_gdp --output ./my-pipeline/
+eolas integrate fivetran            --datasets nz_cpi
+eolas integrate azure-data-factory  --datasets nz_cpi,nz_gdp
+```
+
+The generated directory has everything needed to plug into your destination
+warehouse: `meltano.yml`, `fivetran.yml`, or ADF JSON resources, plus a `README.md`
+walking through the rest of the setup. Non-Enterprise users see a clear
+upgrade pointer; the gating lives server-side so the capability is bypass-proof.
+
+### Exit codes
+
+Distinct exit codes per error class, for shell scripts and agents:
+
+| Code | Meaning |
+|---|---|
+| `0`  | Success |
+| `1`  | Generic error |
+| `2`  | Auth (`AuthenticationError`, including Enterprise-gate 403) |
+| `3`  | Rate limit hit |
+| `4`  | Dataset / resource not found |
+| `5`  | Other API error |
+| `64` | Bad usage (mirrors `sysexits.h`) |
+
+## Geospatial
+
+Datasets with a `geometry_wkt` column auto-convert to `geopandas.GeoDataFrame` if `geopandas` is installed:
+
+```bash
+pip install eolas-data[geo]
+```
+
+```python
+gdf = client.get("nz_addresses")                  # GeoDataFrame
+df  = client.get("nz_addresses", as_geo=False)    # plain DataFrame, WKT preserved
+```
+
+## Polars
+
+```bash
+pip install eolas-data[polars]
+```
+
+```python
+df = client.get("nz_cpi", engine="polars")
+```
+
+## Plotting
+
+```bash
+pip install eolas-data[plot]
+```
+
+```python
+df = client.statsnz("nz_cpi")
+df.plot_dataset()
+```
+
+## Type stubs
+
+Dataset names are exposed as a `Literal` so IDEs autocomplete the catalog:
+
+```python
+from eolas_data import Client
+
+client = Client()
+client.get("nz_")    # autocomplete shows nz_cpi, nz_gdp_production_annual, ...
+```
+
+The list is regenerated from the live API at release time. Passing a name not in the snapshot still works at runtime — the type hint just won't autocomplete it. Catalog snapshot date is exposed as `eolas_data._dataset_names.CATALOG_SNAPSHOT_DATE`.
+
+## Migrating from `vswarehouse`
+
+The previous package name was `vswarehouse`. Direct equivalents:
+
+| `vswarehouse` | `eolas_data` |
+|---|---|
+| `from vswarehouse import Client, VSeries` | `from eolas_data import Client, Dataset` |
+| `df.vs_name`, `df.vs_source` | `df.eolas_name`, `df.eolas_source` |
+| `df.plot_series()` | `df.plot_dataset()` |
+| `VS_API_KEY` env var | `EOLAS_API_KEY` (legacy `VS_API_KEY` still honoured) |
+
+The API surface is otherwise identical. The default base URL is now `https://api.eolas.fyi` (the old `https://api.virtus-solutions.io` still 301-redirects and works fine — but uses the legacy endpoint shape).
+
+## Releasing
+
+See [`docs/clients.md`](https://github.com/phildonovan/eolas/blob/master/docs/clients.md) in the eolas data repo for the tagged-release flow and PyPI token rotation.
+
+Before each release: `python -m eolas_data._regen_names` to refresh the dataset name stubs from the live API, commit the change, then tag and push.
+
+## License
+
+MIT

eolas_data-1.2.0/README.md

@@ -0,0 +1,170 @@
+# eolas-data
+
+Python client for the [eolas.fyi](https://eolas.fyi) statistical data API — 717+ datasets across NZ, Australia, OECD, and more, served as tidy `pandas` DataFrames (or `polars` / `geopandas` if you prefer).
+
+```bash
+pip install eolas-data
+```
+
+## Quickstart
+
+```python
+from eolas_data import Client
+
+client = Client("your_api_key")   # or set EOLAS_API_KEY in env
+
+# Generic
+df = client.get("nz_cpi", start="2020-01-01")
+
+# Source-specific (sets the `eolas_source` metadata)
+df = client.statsnz("nz_cpi")
+df = client.oecd("nz_gdp_production_annual")
+
+# Discovery
+all_datasets = client.list()
+nz_only      = client.list("Stats NZ")
+meta         = client.info("nz_cpi")
+```
+
+Get an API key at <https://eolas.fyi/signup>. Free plan is 10 requests/month; Starter is 100; Pro is unlimited.
+
+## Command-line interface
+
+`pip install eolas-data[cli]` adds an `eolas` command for browsing, fetching, and
+scheduling — useful for shell scripts, cron jobs, and AI-agent workflows. Output
+auto-detects piping: rich tables in a terminal, newline-delimited JSON when
+stdout is piped.
+
+```bash
+# one-time setup
+eolas auth set-key
+eolas health
+
+# discover
+eolas datasets list --source "Stats NZ"
+eolas datasets list --search cpi --json | jq '.[].name'
+eolas datasets info nz_cpi
+eolas datasets preview nz_cpi --limit 5
+
+# fetch (verb matches the Python lib's client.get())
+eolas get nz_cpi --format csv > cpi.csv
+eolas get nz_cpi --start 2020-01-01 --format json | jq '.[].value'
+eolas get sa2_2023 --format parquet --out sa2.parquet
+```
+
+### Scheduling
+
+Set up recurring fetches without touching crontab/Task Scheduler syntax. Works
+on Linux, macOS (cron), and Windows (Task Scheduler).
+
+```bash
+eolas schedule add nz_cpi --daily   --out ~/data/cpi.csv
+eolas schedule add nz_gdp --weekly  --out ~/data/gdp.csv
+eolas schedule add nzd_usd --cron "0 */6 * * *" --out ~/data/fx.csv   # POSIX only
+
+eolas schedule list
+eolas schedule remove nz_cpi
+```
+
+Daily is the default. Pre-flight check refuses to install a schedule unless
+your API key is configured (otherwise the job would fail silently forever).
+
+### Integrations (Enterprise plan)
+
+Generate ready-to-run connector configs for popular data-pipeline tools — eolas
+becomes a one-command source for Meltano, Fivetran, or Azure Data Factory.
+
+```bash
+eolas integrate meltano             --datasets nz_cpi,nz_gdp --output ./my-pipeline/
+eolas integrate fivetran            --datasets nz_cpi
+eolas integrate azure-data-factory  --datasets nz_cpi,nz_gdp
+```
+
+The generated directory has everything needed to plug into your destination
+warehouse: `meltano.yml`, `fivetran.yml`, or ADF JSON resources, plus a `README.md`
+walking through the rest of the setup. Non-Enterprise users see a clear
+upgrade pointer; the gating lives server-side so the capability is bypass-proof.
+
+### Exit codes
+
+Distinct exit codes per error class, for shell scripts and agents:
+
+| Code | Meaning |
+|---|---|
+| `0`  | Success |
+| `1`  | Generic error |
+| `2`  | Auth (`AuthenticationError`, including Enterprise-gate 403) |
+| `3`  | Rate limit hit |
+| `4`  | Dataset / resource not found |
+| `5`  | Other API error |
+| `64` | Bad usage (mirrors `sysexits.h`) |
+
+## Geospatial
+
+Datasets with a `geometry_wkt` column auto-convert to `geopandas.GeoDataFrame` if `geopandas` is installed:
+
+```bash
+pip install eolas-data[geo]
+```
+
+```python
+gdf = client.get("nz_addresses")                  # GeoDataFrame
+df  = client.get("nz_addresses", as_geo=False)    # plain DataFrame, WKT preserved
+```
+
+## Polars
+
+```bash
+pip install eolas-data[polars]
+```
+
+```python
+df = client.get("nz_cpi", engine="polars")
+```
+
+## Plotting
+
+```bash
+pip install eolas-data[plot]
+```
+
+```python
+df = client.statsnz("nz_cpi")
+df.plot_dataset()
+```
+
+## Type stubs
+
+Dataset names are exposed as a `Literal` so IDEs autocomplete the catalog:
+
+```python
+from eolas_data import Client
+
+client = Client()
+client.get("nz_")    # autocomplete shows nz_cpi, nz_gdp_production_annual, ...
+```
+
+The list is regenerated from the live API at release time. Passing a name not in the snapshot still works at runtime — the type hint just won't autocomplete it. Catalog snapshot date is exposed as `eolas_data._dataset_names.CATALOG_SNAPSHOT_DATE`.
+
+## Migrating from `vswarehouse`
+
+The previous package name was `vswarehouse`. Direct equivalents:
+
+| `vswarehouse` | `eolas_data` |
+|---|---|
+| `from vswarehouse import Client, VSeries` | `from eolas_data import Client, Dataset` |
+| `df.vs_name`, `df.vs_source` | `df.eolas_name`, `df.eolas_source` |
+| `df.plot_series()` | `df.plot_dataset()` |
+| `VS_API_KEY` env var | `EOLAS_API_KEY` (legacy `VS_API_KEY` still honoured) |
+
+The API surface is otherwise identical. The default base URL is now `https://api.eolas.fyi` (the old `https://api.virtus-solutions.io` still 301-redirects and works fine — but uses the legacy endpoint shape).
+
+## Releasing
+
+See [`docs/clients.md`](https://github.com/phildonovan/eolas/blob/master/docs/clients.md) in the eolas data repo for the tagged-release flow and PyPI token rotation.
+
+Before each release: `python -m eolas_data._regen_names` to refresh the dataset name stubs from the live API, commit the change, then tag and push.
+
+## License
+
+MIT

eolas_data-1.2.0/eolas_data/__init__.py

@@ -0,0 +1,16 @@
+"""eolas-data — Python client for the eolas.fyi statistical data API."""
+from .client import Client
+from .dataset import Dataset
+from .exceptions import APIError, AuthenticationError, EolasError, NotFoundError, RateLimitError
+
+__version__ = "1.2.0"
+
+__all__ = [
+    "Client",
+    "Dataset",
+    "EolasError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "APIError",
+]