econdash 0.1.0__tar.gz

econdash-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.ipynb_checkpoints/
+.env

econdash-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project are documented here. The project follows
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-10-11
+
+### Added
+- `EconDash` (sync) and `AsyncEconDash` (async) clients on httpx.
+- `search_indicators`, `list_indicators`, `get_indicator`, `get_series`, `list_countries`,
+  `top_countries`, `cite`.
+- Pydantic v2 models: `Indicator`, `Series`, `Point`, `Country`, `TopCountries`, `TopCountry`,
+  `Citation`.
+- Exceptions: `EconDashAuthError`, `EconDashNotFound`, `EconDashRateLimitError` (`retry_after`),
+  `EconDashPaymentRequired` (decoded x402 challenge).
+- Optional x402 pay-per-call (`econdash[x402]`), off by default and capped by `max_usd_per_call`.
+- Free trial works without an API key; `ECONDASH_API_KEY` or `api_key=` for full access.

econdash-0.1.0/CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+message: "If you use this software or EconDash data, please cite it as below. Also cite the original data source shown for each indicator."
+type: software
+title: "econdash: Python client for the EconDash macroeconomic data API"
+abstract: "Python client for EconDash (econdash.org): 750+ macroeconomic indicators for 290+ countries with source, licence and freshness metadata."
+authors:
+  - name: EconDash
+    website: "https://econdash.org"
+version: 0.1.0
+date-released: "2026-10-11"
+license: MIT
+url: "https://econdash.org"
+repository-code: "https://github.com/econdash/econdash-python"
+keywords:
+  - economics
+  - macroeconomics
+  - time series
+  - open data
+  - api client

econdash-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EconDash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

econdash-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.5
+Name: econdash
+Version: 0.1.0
+Summary: Python client for the EconDash macroeconomic data API: 750+ indicators, 290+ countries, sources and licences.
+Project-URL: Homepage, https://econdash.org
+Project-URL: Documentation, https://econdash.org/docs/python
+Project-URL: Repository, https://github.com/econdash/econdash-python
+Project-URL: Issues, https://github.com/econdash/econdash-python/issues
+Project-URL: Changelog, https://github.com/econdash/econdash-python/blob/main/CHANGELOG.md
+Author-email: EconDash <noderguru@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,economics,gdp,imf,inflation,macroeconomics,time-series,world-bank,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+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 :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Provides-Extra: x402
+Requires-Dist: x402[evm]<3,>=2.25; extra == 'x402'
+Description-Content-Type: text/markdown
+
+# econdash
+
+[![PyPI](https://img.shields.io/pypi/v/econdash)](https://pypi.org/project/econdash/)
+[![CI](https://github.com/econdash/econdash-python/actions/workflows/ci.yml/badge.svg)](https://github.com/econdash/econdash-python/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/econdash)](https://pypi.org/project/econdash/)
+
+Python client for the [EconDash](https://econdash.org) macroeconomic data API: 750+ indicators
+(GDP, inflation, debt, trade, labour, money supply, …) for 290+ countries and regions, with
+source, licence and freshness metadata for every series.
+
+```bash
+pip install econdash
+```
+
+```python
+from econdash import EconDash
+
+ed = EconDash()  # free trial, no key needed
+
+ed.search_indicators("inflation")[:3]  # -> list[Indicator]
+ed.get_indicator("gdp-nominal")  # metadata, source, licence, freshness
+s = ed.get_series("gdp-nominal", "USA", start=2000)
+s.data[-1]  # Point(date=2025-01-01, value=3.07e13, ...)
+ed.list_countries()  # -> list[Country]
+ed.top_countries("gdp-nominal", year=2024, limit=10)
+ed.cite(
+    "gdp-nominal", "USA"
+).citation.text  # 'United States GDP nominal was $30.77 tn in 2025 (World Bank, ...)'
+```
+
+Indicators can be addressed by slug (`gdp-nominal`, as in
+`econdash.org/chart/gdp-nominal/USA`) or by code (`world_bank__gdp_nominal`).
+`start`/`end` accept `2000`, `"2000-06"`, `"2000-06-30"` or a `date`.
+
+## Free trial vs API key
+
+Without a key the client works on the **free trial**:
+
+| Limit | Trial |
+|---|---|
+| Requests | 300 per day, 30 per minute (per IP) |
+| Countries | 10: USA, CHN, DEU, JPN, GBR, FRA, IND, BRA, RUS, KOR |
+| Indicators | 50 core series (GDP, CPI, money supply, debt, trade, …) |
+
+Outside the trial the API answers `403` and the client raises `EconDashAuthError`
+("Country ZWE not available in trial"). That is the trial limit, not a bug.
+
+For full access create a key at [econdash.org/dashboard/api-keys](https://econdash.org/dashboard/api-keys)
+([plans](https://econdash.org/api-access)) and pass it:
+
+```python
+ed = EconDash(api_key="ed_...")  # or set ECONDASH_API_KEY
+```
+
+## Async
+
+```python
+from econdash import AsyncEconDash
+
+async with AsyncEconDash() as ed:
+    series = await ed.get_series("cpi-inflation-rate-percent", "DEU", start=2010)
+```
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `EconDashAuthError` | 401/403: bad key, inactive subscription, data outside the trial |
+| `EconDashNotFound` | 404: unknown indicator or country |
+| `EconDashRateLimitError` | 429, `retry_after` in seconds |
+| `EconDashPaymentRequired` | 402, `challenge` holds the x402 payment requirements |
+| `EconDashError` | base class, anything else |
+
+## Pay per call with x402 (for AI agents)
+
+Agents without an account can pay each call in USDC on Base via
+[x402](https://www.x402.org) ($0.02 per call at the time of writing). It is **off by
+default**: the client never spends money unless you turn it on and set a cap.
+
+```bash
+pip install "econdash[x402]"
+```
+
+```python
+import os
+
+from eth_account import Account
+from econdash import EconDash
+
+ed = EconDash(
+    pay_with_x402=True,
+    x402_signer=Account.from_key(os.environ["AGENT_PRIVATE_KEY"]),
+    max_usd_per_call=0.05,  # x402 refuses to sign anything more expensive
+)
+ed.get_series("gdp-nominal", "ZWE")
+```
+
+If the price is above `max_usd_per_call`, nothing is signed and `EconDashPaymentRequired`
+is raised. Keep agent wallets funded with small amounts only.
+
+## Examples
+
+Notebooks in [`examples/`](examples/): search → series → pandas chart, comparing countries,
+a LangChain agent, an agent paying with x402.
+
+## Data and licences
+
+Every `Indicator` carries `source`, `source_url`, `license_name`, `license_url` and
+`attribution_text`. Source licences differ (World Bank CC BY 4.0, IMF, OECD, FRED, …);
+see [econdash.org/data-license](https://econdash.org/data-license). Please keep the
+attribution when you publish charts or numbers.
+
+## Links
+
+- Website: <https://econdash.org>
+- API docs: <https://econdash.org/docs>, OpenAPI: <https://econdash.org/openapi.json>
+- Python docs: <https://econdash.org/docs/python>
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest            # offline tests on recorded API answers
+uv run pytest -m live    # contract tests against the real API
+uv run ruff check . && uv run mypy
+```
+
+Releases are published to PyPI from GitHub Actions on a GitHub Release (trusted publishing).
+
+MIT licence. The data itself is licensed by its original sources.

econdash-0.1.0/README.md

@@ -0,0 +1,130 @@
+# econdash
+
+[![PyPI](https://img.shields.io/pypi/v/econdash)](https://pypi.org/project/econdash/)
+[![CI](https://github.com/econdash/econdash-python/actions/workflows/ci.yml/badge.svg)](https://github.com/econdash/econdash-python/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/econdash)](https://pypi.org/project/econdash/)
+
+Python client for the [EconDash](https://econdash.org) macroeconomic data API: 750+ indicators
+(GDP, inflation, debt, trade, labour, money supply, …) for 290+ countries and regions, with
+source, licence and freshness metadata for every series.
+
+```bash
+pip install econdash
+```
+
+```python
+from econdash import EconDash
+
+ed = EconDash()  # free trial, no key needed
+
+ed.search_indicators("inflation")[:3]  # -> list[Indicator]
+ed.get_indicator("gdp-nominal")  # metadata, source, licence, freshness
+s = ed.get_series("gdp-nominal", "USA", start=2000)
+s.data[-1]  # Point(date=2025-01-01, value=3.07e13, ...)
+ed.list_countries()  # -> list[Country]
+ed.top_countries("gdp-nominal", year=2024, limit=10)
+ed.cite(
+    "gdp-nominal", "USA"
+).citation.text  # 'United States GDP nominal was $30.77 tn in 2025 (World Bank, ...)'
+```
+
+Indicators can be addressed by slug (`gdp-nominal`, as in
+`econdash.org/chart/gdp-nominal/USA`) or by code (`world_bank__gdp_nominal`).
+`start`/`end` accept `2000`, `"2000-06"`, `"2000-06-30"` or a `date`.
+
+## Free trial vs API key
+
+Without a key the client works on the **free trial**:
+
+| Limit | Trial |
+|---|---|
+| Requests | 300 per day, 30 per minute (per IP) |
+| Countries | 10: USA, CHN, DEU, JPN, GBR, FRA, IND, BRA, RUS, KOR |
+| Indicators | 50 core series (GDP, CPI, money supply, debt, trade, …) |
+
+Outside the trial the API answers `403` and the client raises `EconDashAuthError`
+("Country ZWE not available in trial"). That is the trial limit, not a bug.
+
+For full access create a key at [econdash.org/dashboard/api-keys](https://econdash.org/dashboard/api-keys)
+([plans](https://econdash.org/api-access)) and pass it:
+
+```python
+ed = EconDash(api_key="ed_...")  # or set ECONDASH_API_KEY
+```
+
+## Async
+
+```python
+from econdash import AsyncEconDash
+
+async with AsyncEconDash() as ed:
+    series = await ed.get_series("cpi-inflation-rate-percent", "DEU", start=2010)
+```
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `EconDashAuthError` | 401/403: bad key, inactive subscription, data outside the trial |
+| `EconDashNotFound` | 404: unknown indicator or country |
+| `EconDashRateLimitError` | 429, `retry_after` in seconds |
+| `EconDashPaymentRequired` | 402, `challenge` holds the x402 payment requirements |
+| `EconDashError` | base class, anything else |
+
+## Pay per call with x402 (for AI agents)
+
+Agents without an account can pay each call in USDC on Base via
+[x402](https://www.x402.org) ($0.02 per call at the time of writing). It is **off by
+default**: the client never spends money unless you turn it on and set a cap.
+
+```bash
+pip install "econdash[x402]"
+```
+
+```python
+import os
+
+from eth_account import Account
+from econdash import EconDash
+
+ed = EconDash(
+    pay_with_x402=True,
+    x402_signer=Account.from_key(os.environ["AGENT_PRIVATE_KEY"]),
+    max_usd_per_call=0.05,  # x402 refuses to sign anything more expensive
+)
+ed.get_series("gdp-nominal", "ZWE")
+```
+
+If the price is above `max_usd_per_call`, nothing is signed and `EconDashPaymentRequired`
+is raised. Keep agent wallets funded with small amounts only.
+
+## Examples
+
+Notebooks in [`examples/`](examples/): search → series → pandas chart, comparing countries,
+a LangChain agent, an agent paying with x402.
+
+## Data and licences
+
+Every `Indicator` carries `source`, `source_url`, `license_name`, `license_url` and
+`attribution_text`. Source licences differ (World Bank CC BY 4.0, IMF, OECD, FRED, …);
+see [econdash.org/data-license](https://econdash.org/data-license). Please keep the
+attribution when you publish charts or numbers.
+
+## Links
+
+- Website: <https://econdash.org>
+- API docs: <https://econdash.org/docs>, OpenAPI: <https://econdash.org/openapi.json>
+- Python docs: <https://econdash.org/docs/python>
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest            # offline tests on recorded API answers
+uv run pytest -m live    # contract tests against the real API
+uv run ruff check . && uv run mypy
+```
+
+Releases are published to PyPI from GitHub Actions on a GitHub Release (trusted publishing).
+
+MIT licence. The data itself is licensed by its original sources.

econdash-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "econdash"
+dynamic = ["version"]
+description = "Python client for the EconDash macroeconomic data API: 750+ indicators, 290+ countries, sources and licences."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "EconDash", email = "noderguru@gmail.com" }]
+keywords = ["economics", "macroeconomics", "gdp", "inflation", "time-series", "api", "x402", "world-bank", "imf"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Office/Business :: Financial",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.5",
+]
+
+[project.optional-dependencies]
+x402 = ["x402[evm]>=2.25,<3"]
+
+[project.urls]
+Homepage = "https://econdash.org"
+Documentation = "https://econdash.org/docs/python"
+Repository = "https://github.com/econdash/econdash-python"
+Issues = "https://github.com/econdash/econdash-python/issues"
+Changelog = "https://github.com/econdash/econdash-python/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "mypy>=1.10",
+]
+
+[tool.hatch.version]
+path = "src/econdash/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "CHANGELOG.md", "LICENSE", "CITATION.cff"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = ["live: hits the real EconDash API (run with -m live)"]
+addopts = "-m 'not live'"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+
+[tool.mypy]
+strict = true
+packages = ["econdash"]
+
+[[tool.mypy.overrides]]
+module = ["x402", "x402.*"]
+ignore_missing_imports = true

econdash-0.1.0/src/econdash/__init__.py

@@ -0,0 +1,40 @@
+"""Python client for the EconDash macroeconomic data API (https://econdash.org)."""
+
+__version__ = "0.1.0"
+
+from ._client import DEFAULT_BASE_URL, AsyncEconDash, EconDash  # noqa: E402
+from .errors import (  # noqa: E402
+    EconDashAuthError,
+    EconDashError,
+    EconDashNotFound,
+    EconDashPaymentRequired,
+    EconDashRateLimitError,
+)
+from .models import (  # noqa: E402
+    Citation,
+    Country,
+    Indicator,
+    Point,
+    Series,
+    TopCountries,
+    TopCountry,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "AsyncEconDash",
+    "Citation",
+    "Country",
+    "EconDash",
+    "EconDashAuthError",
+    "EconDashError",
+    "EconDashNotFound",
+    "EconDashPaymentRequired",
+    "EconDashRateLimitError",
+    "Indicator",
+    "Point",
+    "Series",
+    "TopCountries",
+    "TopCountry",
+    "__version__",
+]