eolas-data 1.0.0__py3-none-any.whl

eolas_data/dataset.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import pandas as pd
+
+
+class Dataset(pd.DataFrame):
+    """A pandas DataFrame with eolas dataset metadata.
+
+    Behaves exactly like a DataFrame — all pandas operations work normally.
+    Extra attributes:
+        eolas_name:   Dataset identifier (e.g. ``"nz_cpi"``).
+        eolas_source: Data source label (e.g. ``"Stats NZ"``).
+    """
+
+    _metadata = ["eolas_name", "eolas_source"]
+
+    @property
+    def _constructor(self):
+        return Dataset
+
+    def __repr__(self) -> str:
+        name   = getattr(self, "eolas_name",   "") or ""
+        source = getattr(self, "eolas_source", "") or ""
+        if name:
+            header = f"# Dataset: {name}"
+            if source:
+                header += f" [{source}]"
+            header += f"\n# {len(self)} rows\n"
+            return header + pd.DataFrame.__repr__(self)
+        return pd.DataFrame.__repr__(self)
+
+    # ------------------------------------------------------------------
+    # plot_dataset() was removed in v1.3.0.
+    #
+    # It auto-picked `date` and `value` columns and drew a single matplotlib
+    # line — but datasets with a dimension column (multiple series per date)
+    # produced silent zigzag traces. Rather than ship a helper that has to
+    # know each dataset's shape, plotting is now the caller's responsibility.
+    # `Dataset` subclasses `DataFrame`, so any matplotlib / seaborn / plotly
+    # workflow works straight out of the box:
+    #
+    #     import matplotlib.pyplot as plt
+    #     df.plot(x="date", y="value")
+    #
+    # See README for one-liners.
+    # ------------------------------------------------------------------

eolas_data/exceptions.py

@@ -0,0 +1,20 @@
+class EolasError(Exception):
+    """Base exception for the eolas-data client."""
+
+
+class AuthenticationError(EolasError):
+    pass
+
+
+class RateLimitError(EolasError):
+    pass
+
+
+class NotFoundError(EolasError):
+    pass
+
+
+class APIError(EolasError):
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        super().__init__(f"HTTP {status_code}: {message}")

eolas_data/schedule.py

@@ -0,0 +1,258 @@
+"""Cross-platform scheduling backend for `eolas schedule add|list|remove`.
+
+POSIX (Linux/macOS): edits the user's crontab via `crontab -l` / `crontab -`.
+Windows:             uses `schtasks` to create per-user scheduled tasks.
+
+Both backends only manage entries tagged with a sentinel so the user's other
+cron jobs / scheduled tasks are never touched.
+"""
+from __future__ import annotations
+
+import csv
+import io
+import platform
+import re
+import shlex
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Optional
+
+SENTINEL  = "# eolas-schedule:"
+TASK_PREFIX = "eolas-"  # Windows task name prefix
+
+# Interval shortcut → cron expression (minute hour dom month dow). Daily/weekly/
+# monthly all default to 6am because datasets typically refresh in the early
+# hours; running at 6am gets the freshest data without competing for resources.
+INTERVALS = {
+    "hourly":  "0 * * * *",
+    "daily":   "0 6 * * *",
+    "weekly":  "0 6 * * 1",   # Monday 6am
+    "monthly": "0 6 1 * *",   # 1st of month, 6am
+}
+
+# Windows schtasks /sc value per interval. Custom cron exprs not supported on
+# Windows backend — see _windows_add for the fallback message.
+WIN_SCHED = {
+    "hourly":  ("HOURLY",  None),
+    "daily":   ("DAILY",   "06:00"),
+    "weekly":  ("WEEKLY",  "06:00"),    # default day = today's weekday; we override below
+    "monthly": ("MONTHLY", "06:00"),
+}
+
+CRON_EXPR_RE = re.compile(r"^\s*\S+\s+\S+\s+\S+\s+\S+\s+\S+\s*$")
+
+
+@dataclass
+class ScheduleEntry:
+    name: str
+    schedule: str   # cron expr (POSIX) or human description (Windows)
+    command: str
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Public API — dispatches per OS
+# ────────────────────────────────────────────────────────────────────────────
+
+def is_windows() -> bool:
+    return platform.system() == "Windows"
+
+
+def add(name: str, schedule_expr: str, command: str) -> None:
+    """Register a scheduled task. `schedule_expr` is a cron expression on POSIX
+    or one of {'hourly','daily','weekly','monthly'} on Windows."""
+    if is_windows():
+        _windows_add(name, schedule_expr, command)
+    else:
+        _cron_add(name, schedule_expr, command)
+
+
+def remove(name: str) -> bool:
+    """Remove a managed task. Returns True if removed, False if not found."""
+    if is_windows():
+        return _windows_remove(name)
+    return _cron_remove(name)
+
+
+def list_entries() -> list[ScheduleEntry]:
+    """Return all managed eolas-schedule entries."""
+    if is_windows():
+        return _windows_list()
+    return _cron_list()
+
+
+def interval_to_cron(interval: str) -> str:
+    """Return the cron expression for an interval shortcut. Raises on unknown."""
+    if interval not in INTERVALS:
+        raise ValueError(f"unknown interval {interval!r}; expected one of {list(INTERVALS)}")
+    return INTERVALS[interval]
+
+
+def validate_cron_expr(expr: str) -> None:
+    """Basic shape check on a 5-field cron expression. Raises on invalid."""
+    if not CRON_EXPR_RE.match(expr):
+        raise ValueError(
+            f"invalid cron expression {expr!r}; expected 5 fields "
+            "(minute hour day-of-month month day-of-week)"
+        )
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# POSIX cron backend
+# ────────────────────────────────────────────────────────────────────────────
+
+def _crontab_available() -> bool:
+    return shutil.which("crontab") is not None
+
+
+def _cron_read() -> list[str]:
+    """Read the user's crontab. Returns [] when no crontab is set."""
+    if not _crontab_available():
+        raise RuntimeError(
+            "crontab is not installed on this system. "
+            "On Debian/Ubuntu: sudo apt-get install cron. On Alpine: apk add busybox-suid."
+        )
+    proc = subprocess.run(
+        ["crontab", "-l"], capture_output=True, text=True
+    )
+    if proc.returncode == 0:
+        return proc.stdout.splitlines()
+    # Some implementations exit 1 with "no crontab" — treat as empty.
+    if "no crontab" in (proc.stderr or "").lower():
+        return []
+    raise RuntimeError(f"crontab -l failed: {proc.stderr.strip() or proc.stdout.strip()}")
+
+
+def _cron_write(lines: list[str]) -> None:
+    payload = "\n".join(lines).rstrip() + "\n"
+    proc = subprocess.run(
+        ["crontab", "-"], input=payload, text=True, capture_output=True
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"crontab - failed: {proc.stderr.strip()}")
+
+
+def _cron_format_line(name: str, cron_expr: str, command: str) -> str:
+    return f"{cron_expr} {command}  {SENTINEL} {name}"
+
+
+def _cron_match_name(line: str, name: str) -> bool:
+    return SENTINEL in line and line.rstrip().endswith(name)
+
+
+def _cron_add(name: str, cron_expr: str, command: str) -> None:
+    validate_cron_expr(cron_expr)
+    lines = [l for l in _cron_read() if not _cron_match_name(l, name)]  # idempotent
+    lines.append(_cron_format_line(name, cron_expr, command))
+    _cron_write(lines)
+
+
+def _cron_remove(name: str) -> bool:
+    lines = _cron_read()
+    kept  = [l for l in lines if not _cron_match_name(l, name)]
+    if len(kept) == len(lines):
+        return False
+    _cron_write(kept)
+    return True
+
+
+def _cron_list() -> list[ScheduleEntry]:
+    out: list[ScheduleEntry] = []
+    for line in _cron_read():
+        if SENTINEL not in line:
+            continue
+        head, _, tail = line.partition(SENTINEL)
+        name  = tail.strip()
+        parts = head.strip().split(maxsplit=5)
+        if len(parts) < 6:
+            continue   # malformed; skip silently
+        cron_expr = " ".join(parts[:5])
+        command   = parts[5]
+        out.append(ScheduleEntry(name=name, schedule=cron_expr, command=command))
+    return out
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Windows schtasks backend
+# ────────────────────────────────────────────────────────────────────────────
+
+def _schtasks_available() -> bool:
+    return shutil.which("schtasks") is not None
+
+
+def _windows_add(name: str, interval: str, command: str) -> None:
+    if not _schtasks_available():
+        raise RuntimeError("schtasks not found — required on Windows for scheduling")
+    if interval not in WIN_SCHED:
+        raise ValueError(
+            f"Windows backend supports interval shortcuts only "
+            f"({list(WIN_SCHED)}); got {interval!r}. "
+            "Custom cron expressions aren't translatable; use schtasks GUI for advanced cases."
+        )
+    sc, st = WIN_SCHED[interval]
+    args = [
+        "schtasks", "/create",
+        "/tn", f"{TASK_PREFIX}{name}",
+        "/tr", command,
+        "/sc", sc,
+        "/f",  # overwrite if exists (idempotent add)
+    ]
+    if st:
+        args += ["/st", st]
+    if interval == "weekly":
+        args += ["/d", "MON"]
+    proc = subprocess.run(args, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise RuntimeError(f"schtasks /create failed: {proc.stderr.strip()}")
+
+
+def _windows_remove(name: str) -> bool:
+    proc = subprocess.run(
+        ["schtasks", "/delete", "/tn", f"{TASK_PREFIX}{name}", "/f"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode == 0:
+        return True
+    # schtasks returns non-zero if the task doesn't exist
+    if "cannot find" in (proc.stderr + proc.stdout).lower():
+        return False
+    raise RuntimeError(f"schtasks /delete failed: {proc.stderr.strip()}")
+
+
+def _windows_list() -> list[ScheduleEntry]:
+    proc = subprocess.run(
+        ["schtasks", "/query", "/fo", "CSV", "/v"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"schtasks /query failed: {proc.stderr.strip()}")
+    out: list[ScheduleEntry] = []
+    reader = csv.DictReader(io.StringIO(proc.stdout))
+    for row in reader:
+        task_name = (row.get("TaskName") or "").lstrip("\\").strip()
+        if not task_name.startswith(TASK_PREFIX):
+            continue
+        out.append(ScheduleEntry(
+            name=task_name[len(TASK_PREFIX):],
+            schedule=row.get("Schedule Type") or "",
+            command=row.get("Task To Run") or "",
+        ))
+    return out
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Helpers used by cli.py
+# ────────────────────────────────────────────────────────────────────────────
+
+def build_command(eolas_path: str, dataset: str, out_path: str,
+                  start: Optional[str] = None, end: Optional[str] = None,
+                  fmt: str = "csv") -> str:
+    """Construct the shell command line to put inside the cron entry."""
+    parts = [shlex.quote(eolas_path), "get", shlex.quote(dataset),
+             "--format", shlex.quote(fmt),
+             "--out", shlex.quote(str(out_path))]
+    if start:
+        parts += ["--start", shlex.quote(start)]
+    if end:
+        parts += ["--end", shlex.quote(end)]
+    return " ".join(parts)

eolas_data-1.0.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: eolas-data
+Version: 1.0.0
+Summary: Python client for the eolas.fyi statistical data API (NZ, Australia, OECD)
+Project-URL: Homepage, https://eolas.fyi
+Project-URL: Documentation, https://docs.eolas.fyi/
+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: 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
+
+`Dataset` is a `pandas.DataFrame` subclass — use matplotlib / seaborn / plotly
+directly. No bundled plot helper, because there's no universal "right" plot for
+a tidy dataset (single-series time series vs. wide multi-measure vs. WKT
+geometry all need different code).
+
+```python
+import matplotlib.pyplot as plt
+
+df = client.statsnz("nz_cpi")
+df.plot(x="date", y="value")
+plt.show()
+```
+
+## 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`.
+
+## 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.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+eolas_data/__init__.py,sha256=xiONh2SG6TBa2IylGmqGNfTrdPUGYL9GaIuXD09v-oA,399
+eolas_data/_dataset_names.py,sha256=YaVe6QaeRYh-2xfwQ1mPr2ZsSQRofIfr8rPMsetSiEk,95541
+eolas_data/_regen_names.py,sha256=zpU3_C19DT8LZC09VZuVK_-D9tVGtPa5x8DLEO5flwM,1898
+eolas_data/cli.py,sha256=Vz0R4hBGJlS59XajZi81LT6sxxpOUcAZP4grWpWwETg,27386
+eolas_data/client.py,sha256=KlfEXrbC5cFu8QDgiAauTnKuMYCghBHCcYviHoA36jw,27928
+eolas_data/dataset.py,sha256=XLoNCdA4AHaP-XjYKMQ6LRnAOh4sYyVuveUO5HjRbAw,1661
+eolas_data/exceptions.py,sha256=AJXOgymkMFqQP4Q_zdfkkGs2lrOCUpB_1xbWRquGnec,404
+eolas_data/schedule.py,sha256=3npQ9fWg7pU_Ll1wmsA-z3zLdMCXtQTcW-yF68-k__Q,10106
+eolas_data-1.0.0.dist-info/METADATA,sha256=jAfIWR0xTYW4WS_jNTH9XeYpLV9kCei8oVU9J3irgLU,6571
+eolas_data-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+eolas_data-1.0.0.dist-info/entry_points.txt,sha256=RKhA3k4kfBLH5S7Rvep2j6B_eKiEHlY70MXxJfvVNVo,45
+eolas_data-1.0.0.dist-info/RECORD,,

eolas_data-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

eolas_data-1.0.0.dist-info/entry_points.txt

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