eolas-data 1.2.0__py3-none-any.whl

eolas_data-1.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+eolas_data/__init__.py,sha256=Eyh7hmKgC49Bgld0a5iyIUHOpqyanub_k_cLGCfWJLM,399
+eolas_data/_dataset_names.py,sha256=I02iGDzm96XQtv6_r7yiEJ5BwFoO7K78yZMgMwFeygQ,48831
+eolas_data/_regen_names.py,sha256=zpU3_C19DT8LZC09VZuVK_-D9tVGtPa5x8DLEO5flwM,1898
+eolas_data/cli.py,sha256=xDwTYIbHTKKCijh7Lj-v6px2SwsFcEBdk5lRZonbwPw,26432
+eolas_data/client.py,sha256=2TrJRGqyO6ZbUSMU94N1fEBC2ffAI7oiRDIMssRRhfU,12976
+eolas_data/dataset.py,sha256=Yw7JoiPbuCkDH06HicAkxmseFnZ94Iqia-wyJXk7BlY,2208
+eolas_data/exceptions.py,sha256=AJXOgymkMFqQP4Q_zdfkkGs2lrOCUpB_1xbWRquGnec,404
+eolas_data/schedule.py,sha256=3npQ9fWg7pU_Ll1wmsA-z3zLdMCXtQTcW-yF68-k__Q,10106
+eolas_data-1.2.0.dist-info/METADATA,sha256=t7V4pcupoDWidhpCsxv45Rx3XxwAwAl4AkNLOOiFWy4,7020
+eolas_data-1.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+eolas_data-1.2.0.dist-info/entry_points.txt,sha256=RKhA3k4kfBLH5S7Rvep2j6B_eKiEHlY70MXxJfvVNVo,45
+eolas_data-1.2.0.dist-info/RECORD,,

eolas_data-1.2.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.2.0.dist-info/entry_points.txt

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