hfdatalibrary 0.1.0__tar.gz

hfdatalibrary-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: hfdatalibrary
+Version: 0.1.0
+Summary: Python client for the HF Data Library — free 1-minute OHLCV data for U.S. equities and ETFs
+Author: Ahmed Elkassabgi
+License: MIT
+Project-URL: Homepage, https://hfdatalibrary.com
+Project-URL: Documentation, https://hfdatalibrary.com/pages/docs
+Project-URL: Source, https://github.com/elkassabgi/hfdatalibrary
+Project-URL: Issues, https://github.com/elkassabgi/hfdatalibrary/issues
+Keywords: finance,stock-market,ohlcv,intraday,high-frequency,backtesting,research-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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 :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20
+Requires-Dist: pandas>=1.0
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=6.0; extra == "parquet"
+
+# hfdatalibrary (Python)
+
+Python client for the [HF Data Library](https://hfdatalibrary.com) — free,
+research-grade 1-minute OHLCV data for ~1,391 U.S. equities and ETFs, in
+both `raw` and `clean` versions across eight timeframes.
+
+## Install
+
+```bash
+pip install hfdatalibrary          # add pyarrow for parquet: pip install hfdatalibrary[parquet]
+```
+
+## Authenticate
+
+Get a free API key at <https://hfdatalibrary.com/pages/account>, then:
+
+```python
+import hfdatalibrary as hfdl
+hfdl.set_key("YOUR_API_KEY")        # or set the HFDL_API_KEY environment variable
+```
+
+## Use
+
+```python
+hfdl.symbols()                                   # -> ['A', 'AA', 'AAPL', ...]
+df = hfdl.get("AAPL")                             # clean 1-minute bars (pandas DataFrame)
+df = hfdl.get("AAPL", version="raw", timeframe="daily")
+panel = hfdl.get(["AAPL", "MSFT", "SPY"])         # -> {ticker: DataFrame}
+df = hfdl.get("AAPL", fmt="csv")                  # CSV instead of parquet (no pyarrow needed)
+```
+
+Parameters: `version` ∈ {`clean`, `raw`}; `timeframe` ∈ {`1min`,`5min`,`15min`,`30min`,`hourly`,`daily`,`weekly`,`monthly`}.
+
+## Important: survivorship bias
+
+The universe is a fixed snapshot (~2023) carried back to 2002, so pre-2022
+history is **survivor-conditioned** — companies that delisted before ~2021 are
+absent. Not suitable for survivorship-sensitive backtests over 2002–2021
+without adjustment. See the [methodology docs](https://hfdatalibrary.com/pages/docs)
+for full limitations (including the post-March-2022 IEX-only volume caveat).
+
+## License
+
+MIT (client code). Data is CC BY 4.0 — cite per <https://hfdatalibrary.com/pages/cite>.

hfdatalibrary-0.1.0/README.md

@@ -0,0 +1,44 @@
+# hfdatalibrary (Python)
+
+Python client for the [HF Data Library](https://hfdatalibrary.com) — free,
+research-grade 1-minute OHLCV data for ~1,391 U.S. equities and ETFs, in
+both `raw` and `clean` versions across eight timeframes.
+
+## Install
+
+```bash
+pip install hfdatalibrary          # add pyarrow for parquet: pip install hfdatalibrary[parquet]
+```
+
+## Authenticate
+
+Get a free API key at <https://hfdatalibrary.com/pages/account>, then:
+
+```python
+import hfdatalibrary as hfdl
+hfdl.set_key("YOUR_API_KEY")        # or set the HFDL_API_KEY environment variable
+```
+
+## Use
+
+```python
+hfdl.symbols()                                   # -> ['A', 'AA', 'AAPL', ...]
+df = hfdl.get("AAPL")                             # clean 1-minute bars (pandas DataFrame)
+df = hfdl.get("AAPL", version="raw", timeframe="daily")
+panel = hfdl.get(["AAPL", "MSFT", "SPY"])         # -> {ticker: DataFrame}
+df = hfdl.get("AAPL", fmt="csv")                  # CSV instead of parquet (no pyarrow needed)
+```
+
+Parameters: `version` ∈ {`clean`, `raw`}; `timeframe` ∈ {`1min`,`5min`,`15min`,`30min`,`hourly`,`daily`,`weekly`,`monthly`}.
+
+## Important: survivorship bias
+
+The universe is a fixed snapshot (~2023) carried back to 2002, so pre-2022
+history is **survivor-conditioned** — companies that delisted before ~2021 are
+absent. Not suitable for survivorship-sensitive backtests over 2002–2021
+without adjustment. See the [methodology docs](https://hfdatalibrary.com/pages/docs)
+for full limitations (including the post-March-2022 IEX-only volume caveat).
+
+## License
+
+MIT (client code). Data is CC BY 4.0 — cite per <https://hfdatalibrary.com/pages/cite>.

hfdatalibrary-0.1.0/hfdatalibrary/__init__.py

@@ -0,0 +1,41 @@
+"""hfdatalibrary — Python client for the HF Data Library.
+
+Free, research-grade 1-minute OHLCV data for U.S. equities and ETFs.
+
+Quick start:
+    import hfdatalibrary as hfdl
+    hfdl.set_key("YOUR_API_KEY")          # or set HFDL_API_KEY in the environment
+
+    universe = hfdl.symbols()             # list available tickers
+    df  = hfdl.get("AAPL")               # clean 1-minute bars -> pandas DataFrame
+    df  = hfdl.get("AAPL", version="raw", timeframe="daily")
+    panel = hfdl.get(["AAPL", "MSFT"])    # dict {ticker: DataFrame}
+
+Data is survivorship-biased (constituents fixed ~2023; pre-2022 history is
+survivor-conditioned). See https://hfdatalibrary.com/pages/docs for limitations.
+"""
+from .client import (
+    Client,
+    set_key,
+    symbols,
+    get,
+    VERSIONS,
+    TIMEFRAMES,
+    HFDLError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client", "set_key", "symbols", "get",
+    "VERSIONS", "TIMEFRAMES", "HFDLError", "lab", "__version__",
+]
+
+
+def __getattr__(name):
+    # Lazy access to the recipe layer so `import hfdatalibrary` stays light and
+    # never pulls optional analysis deps at package load. `hfdl.lab` / `from
+    # hfdatalibrary import lab` both work.
+    if name == "lab":
+        import importlib
+        return importlib.import_module("hfdatalibrary.lab")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

hfdatalibrary-0.1.0/hfdatalibrary/client.py

@@ -0,0 +1,172 @@
+"""Core client for the HF Data Library API.
+
+Wraps https://api.hfdatalibrary.com. Auth is via an API key sent in the
+X-API-Key header (get one at https://hfdatalibrary.com/pages/account).
+"""
+from __future__ import annotations
+
+import io
+import os
+import time
+from typing import Dict, List, Optional, Union
+
+import requests
+
+BASE_URL = os.environ.get("HFDL_BASE_URL", "https://api.hfdatalibrary.com")
+VERSIONS = ("clean", "raw")
+TIMEFRAMES = ("1min", "5min", "15min", "30min", "hourly", "daily", "weekly", "monthly")
+
+_DEFAULT_KEY = os.environ.get("HFDL_API_KEY")
+
+
+class HFDLError(Exception):
+    """Raised on API or client errors."""
+
+
+def set_key(api_key: str) -> None:
+    """Set the API key for the module-level default client."""
+    global _DEFAULT_KEY
+    _DEFAULT_KEY = api_key
+
+
+class Client:
+    """A configured HF Data Library client.
+
+    Prefer the module-level functions (hfdl.get, hfdl.symbols) for simple use;
+    instantiate Client directly to hold a key explicitly or tune the session.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = BASE_URL,
+        timeout: int = 120,
+        max_retries: int = 3,
+        session: Optional[requests.Session] = None,
+    ):
+        self.api_key = api_key or _DEFAULT_KEY
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.session = session or requests.Session()
+        self.session.headers.update({"User-Agent": "hfdatalibrary-python/0.1.0"})
+
+    # ---- low-level request with retry/backoff -----------------------------
+    def _request(self, path: str, params: Optional[dict] = None, auth: bool = True) -> requests.Response:
+        url = f"{self.base_url}{path}"
+        headers = {}
+        if auth:
+            if not self.api_key:
+                raise HFDLError(
+                    "No API key set. Call hfdl.set_key('...'), pass api_key=..., "
+                    "or set the HFDL_API_KEY environment variable. "
+                    "Get a key at https://hfdatalibrary.com/pages/account"
+                )
+            headers["X-API-Key"] = self.api_key
+
+        last_exc = None
+        for attempt in range(self.max_retries):
+            try:
+                r = self.session.get(url, params=params, headers=headers, timeout=self.timeout)
+            except requests.RequestException as e:
+                last_exc = e
+                time.sleep(1.5 * (attempt + 1))
+                continue
+            if r.status_code == 200:
+                return r
+            if r.status_code in (401, 403):
+                raise HFDLError(f"Authentication failed ({r.status_code}). Check your API key.")
+            if r.status_code == 404:
+                raise HFDLError(f"Not found: {path} (params={params}). Check the ticker/timeframe/version.")
+            if r.status_code == 429:
+                # rate limited — honor Retry-After if present
+                wait = int(r.headers.get("Retry-After", 5 * (attempt + 1)))
+                time.sleep(wait)
+                continue
+            if 500 <= r.status_code < 600:
+                last_exc = HFDLError(f"Server error {r.status_code}")
+                time.sleep(2.0 * (attempt + 1))
+                continue
+            raise HFDLError(f"HTTP {r.status_code}: {r.text[:200]}")
+        raise HFDLError(f"Request to {path} failed after {self.max_retries} attempts: {last_exc}")
+
+    # ---- public API -------------------------------------------------------
+    def symbols(self) -> List[str]:
+        """Return the list of available ticker symbols (no auth required)."""
+        r = self._request("/v1/symbols", auth=False)
+        data = r.json()
+        syms = data.get("symbols", data) if isinstance(data, dict) else data
+        # symbols may be list[str] or list[dict]; normalize to list[str]
+        out = []
+        for s in syms:
+            out.append(s["ticker"] if isinstance(s, dict) else s)
+        return out
+
+    def get(
+        self,
+        ticker: Union[str, List[str]],
+        version: str = "clean",
+        timeframe: str = "1min",
+        fmt: str = "parquet",
+    ):
+        """Fetch bars for one or many tickers.
+
+        Returns a pandas DataFrame for a single ticker, or a dict
+        {ticker: DataFrame} when `ticker` is a list.
+
+        version:   'clean' (default) or 'raw'
+        timeframe: one of TIMEFRAMES
+        fmt:       'parquet' (default, needs pyarrow) or 'csv'
+        """
+        if version not in VERSIONS:
+            raise HFDLError(f"version must be one of {VERSIONS}")
+        if timeframe not in TIMEFRAMES:
+            raise HFDLError(f"timeframe must be one of {TIMEFRAMES}")
+        if fmt not in ("parquet", "csv"):
+            raise HFDLError("fmt must be 'parquet' or 'csv'")
+
+        if isinstance(ticker, (list, tuple, set)):
+            return {t: self._get_one(t, version, timeframe, fmt) for t in ticker}
+        return self._get_one(ticker, version, timeframe, fmt)
+
+    def _get_one(self, ticker: str, version: str, timeframe: str, fmt: str):
+        params = {"version": version, "timeframe": timeframe, "format": fmt}
+        r = self._request(f"/v1/download/{ticker.upper()}", params=params)
+        content = r.content
+        try:
+            import pandas as pd
+        except ImportError as e:
+            raise HFDLError("pandas is required to return DataFrames: pip install pandas") from e
+
+        if fmt == "csv":
+            return pd.read_csv(io.BytesIO(content))
+        # parquet
+        try:
+            return pd.read_parquet(io.BytesIO(content))
+        except ImportError as e:
+            raise HFDLError(
+                "pyarrow is required to read parquet: pip install pyarrow "
+                "(or call get(..., fmt='csv'))"
+            ) from e
+
+
+# ---- module-level convenience (uses a lazily-built default client) --------
+_default_client: Optional[Client] = None
+
+
+def _client() -> Client:
+    global _default_client
+    # rebuild if key changed via set_key after first use
+    if _default_client is None or _default_client.api_key != _DEFAULT_KEY:
+        _default_client = Client(api_key=_DEFAULT_KEY)
+    return _default_client
+
+
+def symbols() -> List[str]:
+    """Module-level: list available tickers."""
+    return _client().symbols()
+
+
+def get(ticker, version: str = "clean", timeframe: str = "1min", fmt: str = "parquet"):
+    """Module-level: fetch bars. See Client.get."""
+    return _client().get(ticker, version=version, timeframe=timeframe, fmt=fmt)

hfdatalibrary-0.1.0/hfdatalibrary.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: hfdatalibrary
+Version: 0.1.0
+Summary: Python client for the HF Data Library — free 1-minute OHLCV data for U.S. equities and ETFs
+Author: Ahmed Elkassabgi
+License: MIT
+Project-URL: Homepage, https://hfdatalibrary.com
+Project-URL: Documentation, https://hfdatalibrary.com/pages/docs
+Project-URL: Source, https://github.com/elkassabgi/hfdatalibrary
+Project-URL: Issues, https://github.com/elkassabgi/hfdatalibrary/issues
+Keywords: finance,stock-market,ohlcv,intraday,high-frequency,backtesting,research-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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 :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20
+Requires-Dist: pandas>=1.0
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=6.0; extra == "parquet"
+
+# hfdatalibrary (Python)
+
+Python client for the [HF Data Library](https://hfdatalibrary.com) — free,
+research-grade 1-minute OHLCV data for ~1,391 U.S. equities and ETFs, in
+both `raw` and `clean` versions across eight timeframes.
+
+## Install
+
+```bash
+pip install hfdatalibrary          # add pyarrow for parquet: pip install hfdatalibrary[parquet]
+```
+
+## Authenticate
+
+Get a free API key at <https://hfdatalibrary.com/pages/account>, then:
+
+```python
+import hfdatalibrary as hfdl
+hfdl.set_key("YOUR_API_KEY")        # or set the HFDL_API_KEY environment variable
+```
+
+## Use
+
+```python
+hfdl.symbols()                                   # -> ['A', 'AA', 'AAPL', ...]
+df = hfdl.get("AAPL")                             # clean 1-minute bars (pandas DataFrame)
+df = hfdl.get("AAPL", version="raw", timeframe="daily")
+panel = hfdl.get(["AAPL", "MSFT", "SPY"])         # -> {ticker: DataFrame}
+df = hfdl.get("AAPL", fmt="csv")                  # CSV instead of parquet (no pyarrow needed)
+```
+
+Parameters: `version` ∈ {`clean`, `raw`}; `timeframe` ∈ {`1min`,`5min`,`15min`,`30min`,`hourly`,`daily`,`weekly`,`monthly`}.
+
+## Important: survivorship bias
+
+The universe is a fixed snapshot (~2023) carried back to 2002, so pre-2022
+history is **survivor-conditioned** — companies that delisted before ~2021 are
+absent. Not suitable for survivorship-sensitive backtests over 2002–2021
+without adjustment. See the [methodology docs](https://hfdatalibrary.com/pages/docs)
+for full limitations (including the post-March-2022 IEX-only volume caveat).
+
+## License
+
+MIT (client code). Data is CC BY 4.0 — cite per <https://hfdatalibrary.com/pages/cite>.

hfdatalibrary-0.1.0/hfdatalibrary.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+hfdatalibrary/__init__.py
+hfdatalibrary/client.py
+hfdatalibrary.egg-info/PKG-INFO
+hfdatalibrary.egg-info/SOURCES.txt
+hfdatalibrary.egg-info/dependency_links.txt
+hfdatalibrary.egg-info/requires.txt
+hfdatalibrary.egg-info/top_level.txt
+tests/test_backtest.py
+tests/test_coverage.py
+tests/test_panel.py
+tests/test_universe.py

hfdatalibrary-0.1.0/hfdatalibrary.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hfdatalibrary-0.1.0/hfdatalibrary.egg-info/requires.txt

@@ -0,0 +1,5 @@
+requests>=2.20
+pandas>=1.0
+
+[parquet]
+pyarrow>=6.0

hfdatalibrary-0.1.0/hfdatalibrary.egg-info/top_level.txt

@@ -0,0 +1 @@
+hfdatalibrary

hfdatalibrary-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hfdatalibrary"
+version = "0.1.0"
+description = "Python client for the HF Data Library — free 1-minute OHLCV data for U.S. equities and ETFs"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Ahmed Elkassabgi" }]
+keywords = ["finance", "stock-market", "ohlcv", "intraday", "high-frequency", "backtesting", "research-data"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "requests>=2.20",
+    "pandas>=1.0",
+]
+
+[project.optional-dependencies]
+parquet = ["pyarrow>=6.0"]
+
+[project.urls]
+Homepage = "https://hfdatalibrary.com"
+Documentation = "https://hfdatalibrary.com/pages/docs"
+Source = "https://github.com/elkassabgi/hfdatalibrary"
+Issues = "https://github.com/elkassabgi/hfdatalibrary/issues"
+
+[tool.setuptools]
+packages = ["hfdatalibrary"]

hfdatalibrary-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hfdatalibrary-0.1.0/tests/test_backtest.py

@@ -0,0 +1,60 @@
+"""backtest_momentum: runs no-look-ahead, enforces the survivorship hard stop,
+and reports the pre/post-2022 split. Uses synthetic random-walk prices (no key)."""
+import warnings
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from hfdatalibrary.lab import backtest_momentum, BacktestResult, SurvivorshipBiasError
+
+
+def _panel(start, periods, n=20, seed=0):
+    rng = np.random.default_rng(seed)
+    idx = pd.date_range(start, periods=periods, freq="B")
+    rets = rng.normal(0.0003, 0.01, size=(periods, n))
+    prices = 100 * np.exp(np.cumsum(rets, axis=0))
+    cols = [f"T{i:02d}" for i in range(n - 1)] + ["SPY"]
+    return pd.DataFrame(prices, index=idx, columns=cols)
+
+
+def test_post2022_runs_with_split_and_benchmark():
+    p = _panel("2022-02-01", 400)
+    res = backtest_momentum(p, lookback=60, skip=5, top_n=5, optimize="equal",
+                            benchmark="SPY")
+    assert isinstance(res, BacktestResult)
+    assert len(res.equity) > 0
+    for k in ("total_return", "sharpe", "max_drawdown", "ann_vol"):
+        assert k in res.stats
+    assert "pre2022" in res.stats and "post2022" in res.stats
+    assert "benchmark_total_return" in res.stats
+
+
+def test_pre2022_hard_stops_without_ack():
+    p = _panel("2018-01-01", 800)
+    with pytest.raises(SurvivorshipBiasError):
+        backtest_momentum(p, lookback=60, skip=5, top_n=5, optimize="equal")
+
+
+def test_pre2022_runs_with_ack_and_records():
+    p = _panel("2018-01-01", 800)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        res = backtest_momentum(p, lookback=60, skip=5, top_n=5, optimize="equal",
+                                acknowledge_survivorship=True)
+    assert res.coverage.acknowledged
+    assert len(res.equity) > 0
+
+
+def test_no_lookahead_equity_is_clean():
+    p = _panel("2022-02-01", 300)
+    res = backtest_momentum(p, lookback=40, skip=3, top_n=4, optimize="equal")
+    assert res.equity.notna().all()
+    # momentum is price-only -> the IEX *volume* caveat must NOT be raised
+    assert not any("IEX VOLUME" in w for w in res.warnings)
+
+
+def test_inverse_vol_weighting_runs():
+    p = _panel("2022-02-01", 300, seed=3)
+    res = backtest_momentum(p, lookback=40, skip=3, top_n=6, optimize="inverse_vol")
+    assert len(res.weights) > 0

hfdatalibrary-0.1.0/tests/test_coverage.py

@@ -0,0 +1,79 @@
+"""The guardrails must be loud and never silent: survivorship is a HARD STOP for
+cumulative pre-2022 backtests unless acknowledged; the IEX-volume caveat fires
+only when a strategy actually uses volume."""
+import warnings
+
+import pandas as pd
+import pytest
+
+from hfdatalibrary.lab import (
+    audit_panel, enforce_survivorship,
+    CaveatWarning, SurvivorshipBiasError, CoverageReport,
+)
+
+
+def _panel(start, end, n=3):
+    idx = pd.date_range(start, end, freq="B")
+    return pd.DataFrame({f"T{i}": [100.0] * len(idx) for i in range(n)}, index=idx)
+
+
+def test_pre2022_is_severe_and_hard_stops():
+    rep = audit_panel(_panel("2008-01-01", "2020-12-31"))
+    assert rep.survivorship == "severe"
+    assert rep.pre_2022 and not rep.point_in_time_safe
+    with pytest.raises(SurvivorshipBiasError):
+        enforce_survivorship(rep, acknowledge=False, cumulative=True)
+
+
+def test_acknowledge_allows_and_records():
+    rep = audit_panel(_panel("2008-01-01", "2020-12-31"))
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        out = enforce_survivorship(rep, acknowledge=True, cumulative=True)
+    assert out.acknowledged
+    assert any("SURV_ACK" in n for n in out.notes)
+
+
+def test_non_cumulative_does_not_hard_stop():
+    rep = audit_panel(_panel("2008-01-01", "2020-12-31"))
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        enforce_survivorship(rep, acknowledge=False, cumulative=False)  # must not raise
+
+
+def test_post2022_is_clean():
+    rep = audit_panel(_panel("2022-06-01", "2024-01-01"))
+    assert rep.survivorship == "none"
+    assert rep.point_in_time_safe
+    enforce_survivorship(rep)  # no raise
+
+
+def test_iex_volume_warns_only_when_volume_used():
+    with_vol = audit_panel(_panel("2022-06-01", "2023-06-01"), uses_volume=True)
+    assert any("IEX VOLUME" in w for w in with_vol.warnings)
+
+    no_vol = audit_panel(_panel("2022-06-01", "2023-06-01"), uses_volume=False)
+    assert not any("IEX VOLUME" in w for w in no_vol.warnings)
+    assert any("IEX SEGMENT" in n for n in no_vol.notes)
+
+
+def test_source_column_overrides_date_inference():
+    # window is entirely pre-break by date, but the source column says IEX
+    rep = audit_panel(start="2021-01-01", end="2021-06-01", n_tickers=2,
+                      sources={"iex"})
+    assert rep.iex_segment is True
+
+
+def test_missing_tickers_recorded():
+    rep = audit_panel(_panel("2023-01-01", "2023-06-01"),
+                      missing_tickers=["XYZ", "ABC"])
+    assert "XYZ" in rep.missing_tickers
+    assert any("skipped" in n for n in rep.notes)
+
+
+def test_caveat_warning_can_escalate_to_error():
+    rep = audit_panel(_panel("2022-06-01", "2023-06-01"), uses_volume=True)
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", CaveatWarning)
+        with pytest.raises(CaveatWarning):
+            enforce_survivorship(rep, acknowledge=False, cumulative=False)

hfdatalibrary-0.1.0/tests/test_panel.py

@@ -0,0 +1,53 @@
+"""load_panel: pivots many tickers, skips 404s honestly (client RAISES, not None),
+filters dates, and attaches a CoverageReport using the real source column."""
+import pandas as pd
+import pytest
+
+from hfdatalibrary.lab import load_panel
+from hfdatalibrary.client import HFDLError
+
+
+def _ticker_df(start="2022-01-03", periods=200, source="iex", price=100.0):
+    idx = pd.date_range(start, periods=periods, freq="B")
+    return pd.DataFrame({
+        "Date": idx.astype(str),
+        "Open": price, "High": price + 1, "Low": price - 1, "Close": price,
+        "Volume": 1000, "source": source,
+    })
+
+
+def test_pivots_and_skips_missing():
+    data = {"AAA": _ticker_df(price=100), "BBB": _ticker_df(price=50)}
+
+    def getter(t, version="clean", timeframe="daily"):
+        if t == "CCC":
+            raise HFDLError("Not found: CCC")   # the client raises on 404
+        return data[t]
+
+    wide = load_panel(["AAA", "BBB", "CCC"], field="Close", timeframe="daily",
+                      cache=False, throttle=0, getter=getter)
+    assert list(wide.columns) == ["AAA", "BBB"]
+    assert isinstance(wide.index, pd.DatetimeIndex)
+    cov = wide.attrs["coverage"]
+    assert "CCC" in cov.missing_tickers
+    assert cov.iex_segment is True            # source column == 'iex'
+
+
+def test_date_filter():
+    df = _ticker_df(start="2020-01-01", periods=800, source="pitrading")
+
+    def getter(t, **k):
+        return df
+
+    wide = load_panel(["AAA"], cache=False, throttle=0, getter=getter,
+                      start="2021-01-01", end="2021-12-31")
+    assert wide.index.min() >= pd.Timestamp("2021-01-01")
+    assert wide.index.max() <= pd.Timestamp("2021-12-31")
+
+
+def test_all_missing_raises():
+    def getter(t, **k):
+        raise HFDLError("Not found")
+
+    with pytest.raises(HFDLError):
+        load_panel(["X", "Y"], cache=False, throttle=0, getter=getter)

hfdatalibrary-0.1.0/tests/test_universe.py

@@ -0,0 +1,49 @@
+"""Universe counts must match the REAL survivor-snapshot, never the nominal index
+size (reviewer fix #1). Verified from data/ticker_meta.json: sp500=550,
+nasdaq100=81, dow30=30, etf=569, stock=822, total=1391."""
+import warnings
+
+import pytest
+
+from hfdatalibrary.lab import universe, index_coverage, CaveatWarning
+
+
+def test_sp500_count():
+    assert len(universe("sp500")) == 550
+
+
+def test_dow30_count():
+    assert len(universe("dow30")) == 30
+
+
+def test_nasdaq100_count_and_warns():
+    with warnings.catch_warnings(record=True) as rec:
+        warnings.simplefilter("always")
+        u = universe("nasdaq100")
+    assert len(u) == 81
+    assert any(issubclass(w.category, CaveatWarning) and "81 of 100" in str(w.message)
+               for w in rec), "nasdaq100 must warn about the 81-of-100 survivorship gap"
+
+
+def test_type_counts():
+    assert len(universe("etf")) == 569
+    assert len(universe("stock")) == 822
+
+
+def test_all_is_full_snapshot():
+    assert len(universe("all")) == 1391
+
+
+def test_sector():
+    assert len(universe("sector:Healthcare")) > 0
+
+
+def test_unknown_raises():
+    with pytest.raises(ValueError):
+        universe("bogus_index")
+
+
+def test_index_coverage_diagnostic():
+    cov = index_coverage()
+    assert cov["nasdaq100"] == {"present": 81, "nominal": 100}
+    assert cov["dow30"] == {"present": 30, "nominal": 30}