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
