heimdall-mimird 0.2.0__tar.gz

heimdall_mimird-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Sync
+        run: uv sync --extra all --group dev
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format
+        run: uv run ruff format --check .
+      - name: Types
+        run: uv run mypy src/heimdall
+      - name: Test
+        run: uv run pytest -m "not network" -q

heimdall_mimird-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+*.egg-info
+dist
+.venv
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# dev sandbox - keep the folder, ignore experiments and local data
+sandbox/scratch/*
+!sandbox/scratch/.gitkeep
+*.db
+*.duckdb

heimdall_mimird-0.2.0/.python-version

@@ -0,0 +1 @@
+3.11

heimdall_mimird-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+## Dev setup
+
+```bash
+uv sync --extra all --group dev
+```
+
+## Checks (what CI runs)
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src/heimdall
+uv run pytest -m "not network"      # offline suite
+uv run pytest -m network            # hits real FRED / Yahoo; run before releases
+```
+
+## Adding a provider
+
+First-party providers live under `src/heimdall/providers/<name>/` and are
+registered by a module-level `_register(registry)` hook (see the `fred` and
+`yfinance` packages). Their client library goes in a matching
+`[project.optional-dependencies]` extra so `import heimdall` still works without
+it.
+
+Every provider must:
+
+1. Subclass `heimdall.Provider`, set a stable `id` and a `Capabilities`.
+2. Return a `FetchResult` whose `frame` passes `schema.validate()` - reuse
+   `heimdall.schemas.OHLCV_BARS` / `OBSERVATIONS` or define your own `SchemaSpec`.
+3. Raise `heimdall.errors.*` (`RequestError`, `UpstreamError`, `ConfigError`),
+   never bare `ValueError` / `KeyError`.
+4. Pass the conformance suite. Add a test module that subclasses
+   `heimdall.testing.ProviderContractTests` plus a `@pytest.mark.network`
+   smoke test.
+
+`heimdall.testing` needs pytest. It is not part of the base install - an
+out-of-tree provider package gets it with `pip install heimdall-mimird[testing]`.
+Heimdall's own `dev` group already includes pytest.
+
+See `docs/writing-a-provider.md` for a full example.

heimdall_mimird-0.2.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: heimdall-mimird
+Version: 0.2.0
+Summary: A data-provider SDK
+Requires-Python: >=3.11
+Requires-Dist: polars>=1.44.1
+Requires-Dist: ramonavocado-logger>=0.1.3
+Provides-Extra: all
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: pyarrow>=15; extra == 'all'
+Requires-Dist: yfinance>=0.2.40; extra == 'all'
+Provides-Extra: fred
+Requires-Dist: httpx>=0.27; extra == 'fred'
+Provides-Extra: testing
+Requires-Dist: pytest>=8.2; extra == 'testing'
+Provides-Extra: yfinance
+Requires-Dist: pyarrow>=15; extra == 'yfinance'
+Requires-Dist: yfinance>=0.2.40; extra == 'yfinance'
+Description-Content-Type: text/markdown
+
+# Heimdall
+
+A host-agnostic **data-provider SDK**. Finance data first (Yahoo Finance OHLCV,
+FRED economic series), built so that any data source - yours or the community's -
+can plug in behind one small contract.
+
+A provider takes a `FetchRequest` and returns a `FetchResult`: a
+[Polars](https://pola.rs) frame, a `SchemaSpec` that describes and validates it,
+and some metadata. That's the whole surface. Nothing in the core is
+finance-specific; OHLCV bars and economic observations are just two predefined
+schemas.
+
+## Install
+
+```bash
+pip install heimdall-mimird[fred,yfinance]   # or: heimdall-mimird[all]
+```
+
+The core depends only on `polars` (plus a small logging shim). Each provider
+pulls its own client library through an extra, so you install only what you use.
+
+## Quick start
+
+```python
+import heimdall
+
+# string shorthand -> FetchRequest(resource="DGS10")
+result = heimdall.fetch("fred", "DGS10")
+result.schema.validate(result.frame)  # raises SchemaError if it doesn't conform
+print(result.frame.head())
+
+bars = heimdall.fetch("yfinance", "AAPL", interval="1d")
+print(bars.frame.tail())
+print(bars.metadata)  # {"ticker": "AAPL", "interval": "1d", "rows": ...}
+```
+
+`heimdall.list_providers()` shows what's registered. Providers are registered
+automatically when their extra is installed; register your own with
+`heimdall.register(MyProvider)`.
+
+## Writing a provider
+
+Subclass `heimdall.Provider`, set `id` + `capabilities`, implement `fetch`. See
+[docs/writing-a-provider.md](docs/writing-a-provider.md) for a full worked
+example, and run `heimdall.testing.assert_provider_conformance(...)` to check it
+against the contract.
+
+## Status
+
+Early. The provider contract and the two bundled providers are usable today. The
+ingestion/storage layer, entry-point plugin discovery, and retry/rate-limit
+middleware are on the [roadmap](ROADMAP.md).

heimdall_mimird-0.2.0/README.md

@@ -0,0 +1,52 @@
+# Heimdall
+
+A host-agnostic **data-provider SDK**. Finance data first (Yahoo Finance OHLCV,
+FRED economic series), built so that any data source - yours or the community's -
+can plug in behind one small contract.
+
+A provider takes a `FetchRequest` and returns a `FetchResult`: a
+[Polars](https://pola.rs) frame, a `SchemaSpec` that describes and validates it,
+and some metadata. That's the whole surface. Nothing in the core is
+finance-specific; OHLCV bars and economic observations are just two predefined
+schemas.
+
+## Install
+
+```bash
+pip install heimdall-mimird[fred,yfinance]   # or: heimdall-mimird[all]
+```
+
+The core depends only on `polars` (plus a small logging shim). Each provider
+pulls its own client library through an extra, so you install only what you use.
+
+## Quick start
+
+```python
+import heimdall
+
+# string shorthand -> FetchRequest(resource="DGS10")
+result = heimdall.fetch("fred", "DGS10")
+result.schema.validate(result.frame)  # raises SchemaError if it doesn't conform
+print(result.frame.head())
+
+bars = heimdall.fetch("yfinance", "AAPL", interval="1d")
+print(bars.frame.tail())
+print(bars.metadata)  # {"ticker": "AAPL", "interval": "1d", "rows": ...}
+```
+
+`heimdall.list_providers()` shows what's registered. Providers are registered
+automatically when their extra is installed; register your own with
+`heimdall.register(MyProvider)`.
+
+## Writing a provider
+
+Subclass `heimdall.Provider`, set `id` + `capabilities`, implement `fetch`. See
+[docs/writing-a-provider.md](docs/writing-a-provider.md) for a full worked
+example, and run `heimdall.testing.assert_provider_conformance(...)` to check it
+against the contract.
+
+## Status
+
+Early. The provider contract and the two bundled providers are usable today. The
+ingestion/storage layer, entry-point plugin discovery, and retry/rate-limit
+middleware are on the [roadmap](ROADMAP.md).

heimdall_mimird-0.2.0/ROADMAP.md

@@ -0,0 +1,61 @@
+# Roadmap
+
+Legend: `[x]` shipped · `[~]` partially built · `[ ]` planned
+
+## Shipped
+
+- [x] **Core SDK** - `FetchRequest` / `FetchResult` / `SchemaSpec` contract,
+  `Provider` base + `Capabilities`, `ProviderRegistry` with explicit
+  registration, error hierarchy, `heimdall.fetch(...)`.
+- [x] **Bundled providers** - `fred` (public `fredgraph.csv` endpoint, no key)
+  and `yfinance` (OHLCV via the `yfinance` library), each behind an extra.
+- [x] **Provider conformance kit** - `heimdall.testing.assert_provider_conformance`
+  + `ProviderContractTests`, behind the `testing` extra. This is the "testing
+  harness for provider authors" - third parties prove their provider fits the
+  spec by running it.
+- [x] **Tooling** - ruff, mypy, pytest (with a `network` marker), GitHub Actions CI.
+- [x] **Dev sandbox** - `sandbox/` with a `python -m sandbox` runner and example
+  scripts; results print to the terminal and can be dumped to parquet / CSV.
+
+## Planned (next)
+
+- [ ] **Conformance kit polish** - recorded-fixture helpers so third parties can
+  write offline contract tests without hand-rolling mocks.
+- [ ] **Docs** - expand `docs/writing-a-provider.md` with a schema-authoring
+  section.
+
+## Candidate ideas (evaluated, not yet scheduled)
+
+- [~] **Entry-point plugin discovery** - `ProviderRegistry.load_entry_points()`
+  already works; wire a documented `heimdall.providers` entry-point group and add
+  a `@heimdall.provider` decorator so `pip install heimdall-stripe` auto-registers
+  with the core package. Single biggest driver of ecosystem growth (cf. dlt,
+  pytest, SQLAlchemy dialects).
+- [~] **Config & credentials layer** - already have `Provider(config=...)`,
+  `Capabilities.required_config`, and `config_from_env()`. Add `.env` loading and
+  a pluggable secret-source hook (env / file / secret manager) so provider
+  authors don't reinvent it.
+- [~] **Finer error taxonomy** - split `UpstreamError` into `ProviderAuthError` /
+  `ProviderRateLimitError` / `ProviderTransientError` so orchestration code can
+  react generically: retry vs fail vs backoff.
+- [ ] **Rate limiting / backpressure** - a shared limiter providers opt into;
+  make `Capabilities.rate_limit_per_min` enforced rather than advisory. Part of a
+  middleware stack that wraps `fetch()` host-side (retry + rate-limit + cache).
+- [ ] **State / checkpoint store** - a pluggable interface (file / DB / redis) for
+  "last synced cursor", so incremental sync is usable in production. Needs a
+  cursor concept in the contract (`FetchRequest.cursor` + a next-cursor on
+  `FetchResult`). Larger design item.
+- [ ] **Observability hooks** - a logging/metrics callback protocol (records
+  fetched, latency, errors) that plugs into whatever monitoring the host already
+  runs. Overlaps the middleware work.
+- [ ] **`create-provider` scaffolder** - a `heimdall new-provider <name>` command
+  or a cookiecutter template that emits a provider package skeleton plus its
+  conformance test. Directly lowers the bar for third-party contributors.
+- [ ] **`heimdall.ingest`** - persist `FetchResult`s: parquet tiers + a JSON
+  manifest, plus the transform set (`diff_1`, `pct_change_1`, `sma_20`, `sma_50`).
+  Starting point is parked at `docs/legacy/essential.py`.
+- [ ] **FRED official API** - swap/augment the CSV endpoint with
+  `api.stlouisfed.org` (needs `FRED_API_KEY` -> `Capabilities.required_config`),
+  giving vintages, metadata, and pagination.
+- [ ] **Packaging split** - break `heimdall-core` and each provider into separate
+  distributions, if the boundaries hold up.

heimdall_mimird-0.2.0/docs/writing-a-provider.md

@@ -0,0 +1,125 @@
+# Writing a provider
+
+A provider is one class: it turns a `FetchRequest` into a `FetchResult`. You can
+keep it inside your own project or publish it - Heimdall imposes nothing beyond
+the contract.
+
+## The contract
+
+```python
+FetchRequest(resource, interval=None, start=None, end=None, params={})
+FetchResult(frame, schema, provider_id, request, retrieved_at, metadata={})
+```
+
+- **`resource`** is provider-specific: a ticker, a series id, an endpoint key.
+- **`frame`** is a `polars.DataFrame`.
+- **`schema`** is a `SchemaSpec` that must actually validate `frame`. Reuse
+  `heimdall.schemas.OHLCV_BARS` / `OBSERVATIONS`, or define your own.
+
+## A minimal example
+
+A provider that pulls a CSV with `date,value` columns from a URL:
+
+```python
+from datetime import datetime
+from io import StringIO
+
+import httpx
+import polars as pl
+
+import heimdall
+from heimdall import Capabilities, FetchRequest, FetchResult, Provider
+from heimdall.contracts import ColumnSpec, SchemaSpec
+from heimdall.errors import RequestError, UpstreamError
+
+CSV_SERIES = SchemaSpec(
+    name="csv.series",
+    columns=(
+        ColumnSpec("timestamp", pl.Datetime, nullable=False),
+        ColumnSpec("value", pl.Float64, nullable=False),
+    ),
+    time_column="timestamp",
+    primary_key=("timestamp",),
+)
+
+
+class CsvUrlProvider(Provider):
+    id = "csv-url"
+    capabilities = Capabilities(data_kinds=(CSV_SERIES.name,))
+
+    def fetch(self, request: FetchRequest) -> FetchResult:
+        url = request.params.get("url") or request.resource
+        try:
+            resp = httpx.get(url, timeout=30, follow_redirects=True)
+            resp.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise UpstreamError(f"could not fetch {url}: {exc}") from exc
+
+        frame = (
+            pl.read_csv(StringIO(resp.text))
+            .rename({"date": "timestamp", "value": "value"})
+            .with_columns(
+                pl.col("timestamp").str.strptime(pl.Datetime, strict=False),
+                pl.col("value").cast(pl.Float64, strict=False),
+            )
+            .drop_nulls()
+            .sort("timestamp")
+        )
+        if frame.is_empty():
+            raise RequestError(f"no rows returned from {url}")
+
+        CSV_SERIES.validate(frame)
+        return FetchResult(
+            frame=frame,
+            schema=CSV_SERIES,
+            provider_id=self.id,
+            request=request,
+            retrieved_at=heimdall.utcnow(),
+        )
+```
+
+## Register and use it
+
+```python
+import heimdall
+
+heimdall.register(CsvUrlProvider)
+result = heimdall.fetch("csv-url", "https://example.com/rates.csv")
+```
+
+For config/secrets, declare `required_config` in `Capabilities` and pass values
+at registration - never read the environment inside the provider:
+
+```python
+heimdall.register(MyProvider, config=heimdall.config_from_env("HEIMDALL_MYPROVIDER_"))
+```
+
+## Prove it conforms
+
+`heimdall.testing` needs pytest, which the base install does not pull in:
+
+```bash
+pip install heimdall-mimird[testing]
+```
+
+```python
+from heimdall.testing import assert_provider_conformance
+from heimdall import FetchRequest
+
+assert_provider_conformance(
+    CsvUrlProvider(), FetchRequest(resource="https://example.com/rates.csv")
+)
+```
+
+Or in a pytest suite, subclass `heimdall.testing.ProviderContractTests` and
+implement `make_provider()` / `sample_request()`.
+
+## Rules the conformance kit enforces
+
+- `id` is a non-empty string; `capabilities.data_kinds` is non-empty.
+- `fetch()` returns a `FetchResult` with a non-empty frame that passes
+  `schema.validate()`.
+- `result.provider_id == self.id`; `retrieved_at` is timezone-aware.
+- Two identical requests return the same schema and columns.
+- An unsupported `interval` raises `RequestError` (not a bare exception).
+- Missing `required_config` raises `ConfigError` at construction.

heimdall_mimird-0.2.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "heimdall-mimird"
+version = "0.2.0"
+description = "A data-provider SDK"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "polars>=1.44.1",
+    "ramonavocado-logger>=0.1.3",
+]
+
+[project.optional-dependencies]
+fred = ["httpx>=0.27"]
+yfinance = ["yfinance>=0.2.40", "pyarrow>=15"]
+testing = ["pytest>=8.2"]
+all = ["httpx>=0.27", "yfinance>=0.2.40", "pyarrow>=15"]
+
+[dependency-groups]
+# sandbox = ["sqlalchemy>=2"]  # add when the dev sandbox needs a real database
+dev = [
+    "pytest>=8.2",
+    "pytest-cov>=5.0",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/heimdall"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests", "sandbox"]
+extend-exclude = ["sandbox/scratch"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src/heimdall"]
+disallow_untyped_defs = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+no_implicit_optional = true
+
+[[tool.mypy.overrides]]
+module = ["ramonavocado_logger.*", "yfinance.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "network: test hits a real external service (deselect with '-m \"not network\"')",
+]

heimdall_mimird-0.2.0/sandbox/README.md

@@ -0,0 +1,46 @@
+# sandbox/
+
+A dev-only playground for exercising Heimdall providers by hand. **Not shipped** -
+the package build only includes `src/heimdall`.
+
+- **Committed** (`play.py`, `_helpers.py`, `examples/`) - reference material, kept
+  tidy and lint-clean.
+- **`scratch/`** - git-ignored. Put your own throwaway scripts and any generated
+  `.parquet` / `.csv` / `.db` files here.
+
+Run everything from the repo root, after `uv sync --extra all --group dev`.
+
+## The runner
+
+```bash
+uv run python -m sandbox --list
+uv run python -m sandbox fred DGS10
+uv run python -m sandbox yfinance AAPL --interval 1d --rows 5
+uv run python -m sandbox fred DGS10 --start 2020-01-01 --to-parquet --to-csv
+```
+
+It calls `heimdall.fetch(provider, resource, ...)`, prints a header + schema
+check + the frame via `_helpers.show()`, and optionally writes the frame to
+`sandbox/scratch/`. Provider errors print as one line, no traceback.
+
+## The examples
+
+```bash
+uv run python sandbox/examples/01_fred_to_terminal.py
+uv run python sandbox/examples/03_custom_provider.py      # no network
+```
+
+| file | shows |
+|---|---|
+| `01_fred_to_terminal.py` | fetch a FRED series, print it |
+| `02_yfinance_to_terminal.py` | fetch OHLCV bars, print them |
+| `03_custom_provider.py` | define + register a provider inline, then conformance-check it |
+| `04_export_to_files.py` | fetch, write parquet + CSV to `scratch/`, read back |
+| `05_provider_with_config.py` | `required_config`, `config_from_env`, and the `ConfigError` when a key is missing |
+
+## Exporting to a real database
+
+The file sinks (`to_parquet`, `to_csv`) work out of the box. `_helpers.py` has a
+commented `to_database()` using `polars.DataFrame.write_database`; enable it by
+adding a `sandbox` dependency group (`sqlalchemy>=2` + a driver) and setting
+`HEIMDALL_SANDBOX_DB_URL`. Details are in the comment block.

heimdall_mimird-0.2.0/sandbox/__init__.py

@@ -0,0 +1 @@
+"""Dev sandbox for Heimdall"""

heimdall_mimird-0.2.0/sandbox/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for ``python -m sandbox``."""
+
+from __future__ import annotations
+
+from sandbox.play import main
+
+raise SystemExit(main())

heimdall_mimird-0.2.0/sandbox/_helpers.py

@@ -0,0 +1,93 @@
+"""Shared display + file-sink helpers for the sandbox scripts."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+
+import polars as pl
+
+from heimdall.contracts import FetchResult
+
+SCRATCH = Path(__file__).resolve().parent / "scratch"
+
+
+def _slug(text: str) -> str:
+    cleaned = re.sub(r"[^0-9A-Za-z._-]+", "-", text).strip("-")
+    return cleaned or "resource"
+
+
+def _stamp() -> str:
+    return datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+
+
+def show(result: FetchResult, *, rows: int = 10) -> None:
+    """Print a FetchResult to the terminal: header, schema check, then the frame."""
+    frame = result.frame
+    print(f"provider   : {result.provider_id}")
+    print(f"resource   : {result.request.resource}")
+    if result.request.interval:
+        print(f"interval   : {result.request.interval}")
+    print(f"schema     : {result.schema.name}")
+    print(f"shape      : {frame.height} rows x {frame.width} cols")
+    print(f"retrieved  : {result.retrieved_at:%Y-%m-%d %H:%M:%SZ}")
+    print(f"metadata   : {dict(result.metadata)}")
+    try:
+        result.schema.validate(frame)
+        print("validate   : OK")
+    except Exception as exc:  # noqa: BLE001 - sandbox: surface whatever went wrong
+        print(f"validate   : FAIL - {exc}")
+    print()
+    with pl.Config(tbl_rows=rows, tbl_width_chars=120):
+        print(frame.head(rows))
+        if frame.height > rows:
+            print(f"... {frame.height - rows} more rows ...")
+            print(frame.tail(3))
+
+
+def _target(result: FetchResult, ext: str) -> Path:
+    SCRATCH.mkdir(exist_ok=True)
+    name = f"{result.provider_id}_{_slug(result.request.resource)}_{_stamp()}.{ext}"
+    return SCRATCH / name
+
+
+def to_parquet(result: FetchResult) -> Path:
+    """Write ``result.frame`` to ``sandbox/scratch/`` as parquet; return the path."""
+    path = _target(result, "parquet")
+    result.frame.write_parquet(path)
+    print(f"wrote {result.frame.height} rows -> {path}")
+    return path
+
+
+def to_csv(result: FetchResult) -> Path:
+    """Write ``result.frame`` to ``sandbox/scratch/`` as CSV; return the path."""
+    path = _target(result, "csv")
+    result.frame.write_csv(path)
+    print(f"wrote {result.frame.height} rows -> {path}")
+    return path
+
+
+# --- Database sink (not wired yet) -----------------------------------------------
+# Heimdall keeps `fetch()` pure and leaves persistence to the host. To push a
+# FetchResult into a real database from the sandbox:
+#
+#   1. add a dependency group in pyproject.toml, e.g.
+#        [dependency-groups]
+#        sandbox = ["sqlalchemy>=2"]                          # SQLite (driver is stdlib)
+#        # sandbox = ["sqlalchemy>=2", "psycopg[binary]>=3"]  # PostgreSQL
+#      then:  uv sync --group sandbox
+#   2. set HEIMDALL_SANDBOX_DB_URL, e.g. sqlite:///sandbox/scratch/heimdall.db
+#   3. uncomment:
+#
+# import os
+#
+# def to_database(
+#     result: FetchResult, *, url: str | None = None, table: str | None = None
+# ) -> None:
+#     url = url or os.environ.get(
+#         "HEIMDALL_SANDBOX_DB_URL", "sqlite:///sandbox/scratch/heimdall.db"
+#     )
+#     table = table or f"{result.provider_id}_{_slug(result.request.resource)}"
+#     result.frame.write_database(table, url, if_table_exists="replace")
+#     print(f"wrote {result.frame.height} rows -> {table} @ {url}")

heimdall_mimird-0.2.0/sandbox/examples/01_fred_to_terminal.py

@@ -0,0 +1,19 @@
+"""Fetch a FRED series and print it.  Needs `heimdall-mimird[fred]`.
+
+uv run python sandbox/examples/01_fred_to_terminal.py
+"""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+
+# Run-by-path bootstrap: put the repo root on sys.path so `import sandbox` works.
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
+
+from sandbox._helpers import show
+
+import heimdall
+
+result = heimdall.fetch("fred", "DGS10")
+show(result)

heimdall_mimird-0.2.0/sandbox/examples/02_yfinance_to_terminal.py

@@ -0,0 +1,18 @@
+"""Fetch OHLCV bars from Yahoo Finance and print them.  Needs `heimdall-mimird[yfinance]`.
+
+uv run python sandbox/examples/02_yfinance_to_terminal.py
+"""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
+
+from sandbox._helpers import show  # noqa: E402
+
+import heimdall  # noqa: E402
+
+result = heimdall.fetch("yfinance", "AAPL", interval="1d")
+show(result, rows=8)