index-constitution 0.1.0__tar.gz

index_constitution-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+.uv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store
+uv.lock
+
+# Generated at build time from history/ and latest/ CSVs.
+src/index_constitution/_data/

index_constitution-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 index-constitution contributors
+
+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.

index_constitution-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: index-constitution
+Version: 0.1.0
+Summary: Point-in-time and current constituents for major stock indices (CSI 300, S&P 500, NASDAQ-100), packaged as pandas DataFrames.
+Project-URL: Homepage, https://github.com/unliftedq/index-constitution
+Project-URL: Repository, https://github.com/unliftedq/index-constitution
+Author: index-constitution contributors
+License: MIT License
+        
+        Copyright (c) 2026 index-constitution contributors
+        
+        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.
+License-File: LICENSE
+Keywords: backtesting,constituents,csi300,finance,index,nasdaq100,sp500,stocks
+Classifier: Development Status :: 4 - Beta
+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 :: Only
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Requires-Dist: pandas>=1.5
+Description-Content-Type: text/markdown
+
+# Index Constitution
+
+[中文](README.zh.md)
+
+## Purpose
+
+This repository was created to make it easier to train quantitative models on major stock indices. Reliable historical index composition data (constituent additions and removals over time) is notoriously hard to obtain — vendors often charge for it, official sources are scattered across PDFs and announcements, and free APIs rarely expose point-in-time membership. Without this data, backtests suffer from survivorship bias and lookahead bias.
+
+This repo collects and normalizes that information into plain CSV files so it can be consumed directly by research and modeling pipelines.
+
+## Datasets
+
+| Index | Description | Source |
+| --- | --- | --- |
+| CSI 300 | Top 300 A-share stocks listed on the Shanghai and Shenzhen exchanges | Official announcements from China Securities Index Co. (csindex.com.cn) |
+| S&P 500 | 500 leading large-cap U.S. companies listed on U.S. exchanges | [Wikipedia: List of S&P 500 companies](https://en.wikipedia.org/wiki/List_of_S%26P_500_companies) |
+| NASDAQ-100 | 100 largest non-financial companies listed on the Nasdaq Stock Market | [Wikipedia: NASDAQ-100](https://en.wikipedia.org/wiki/Nasdaq-100) |
+
+## Structure
+
+```text
+src/index_constitution/_data/
+    history/
+        csi300.csv
+        nasdaq100.csv
+        sp500.csv
+    latest/
+        csi300.csv
+        nasdaq100.csv
+        sp500.csv
+```
+
+## Python package
+
+This repo also ships a small Python library that embeds the CSVs and exposes
+them as pandas DataFrames.
+
+Install:
+
+```bash
+pip install index-constitution
+```
+
+Usage:
+
+```python
+import index_constitution as ic
+
+ic.list_indices()                    # ['csi300', 'sp500', 'nasdaq100']
+
+ic.latest("sp500")                   # current S&P 500 members
+ic.history("csi300")                 # full CSI 300 history with opt-in/opt-out
+ic.constituents_at("sp500", "2015-06-30")   # point-in-time membership
+ic.is_member("sp500", "AAPL", "2020-01-02") # True
+```
+
+## Use Cases
+
+- Check the current constituents of an index
+- Reconstruct point-in-time index membership for backtesting
+- Avoid survivorship bias when training quantitative models
+- Keep a consistent structure for adding more indices later

index_constitution-0.1.0/README.md

@@ -0,0 +1,62 @@
+# Index Constitution
+
+[中文](README.zh.md)
+
+## Purpose
+
+This repository was created to make it easier to train quantitative models on major stock indices. Reliable historical index composition data (constituent additions and removals over time) is notoriously hard to obtain — vendors often charge for it, official sources are scattered across PDFs and announcements, and free APIs rarely expose point-in-time membership. Without this data, backtests suffer from survivorship bias and lookahead bias.
+
+This repo collects and normalizes that information into plain CSV files so it can be consumed directly by research and modeling pipelines.
+
+## Datasets
+
+| Index | Description | Source |
+| --- | --- | --- |
+| CSI 300 | Top 300 A-share stocks listed on the Shanghai and Shenzhen exchanges | Official announcements from China Securities Index Co. (csindex.com.cn) |
+| S&P 500 | 500 leading large-cap U.S. companies listed on U.S. exchanges | [Wikipedia: List of S&P 500 companies](https://en.wikipedia.org/wiki/List_of_S%26P_500_companies) |
+| NASDAQ-100 | 100 largest non-financial companies listed on the Nasdaq Stock Market | [Wikipedia: NASDAQ-100](https://en.wikipedia.org/wiki/Nasdaq-100) |
+
+## Structure
+
+```text
+src/index_constitution/_data/
+    history/
+        csi300.csv
+        nasdaq100.csv
+        sp500.csv
+    latest/
+        csi300.csv
+        nasdaq100.csv
+        sp500.csv
+```
+
+## Python package
+
+This repo also ships a small Python library that embeds the CSVs and exposes
+them as pandas DataFrames.
+
+Install:
+
+```bash
+pip install index-constitution
+```
+
+Usage:
+
+```python
+import index_constitution as ic
+
+ic.list_indices()                    # ['csi300', 'sp500', 'nasdaq100']
+
+ic.latest("sp500")                   # current S&P 500 members
+ic.history("csi300")                 # full CSI 300 history with opt-in/opt-out
+ic.constituents_at("sp500", "2015-06-30")   # point-in-time membership
+ic.is_member("sp500", "AAPL", "2020-01-02") # True
+```
+
+## Use Cases
+
+- Check the current constituents of an index
+- Reconstruct point-in-time index membership for backtesting
+- Avoid survivorship bias when training quantitative models
+- Keep a consistent structure for adding more indices later

index_constitution-0.1.0/README.zh.md

@@ -0,0 +1,37 @@
+# Index Constitution
+
+[English](README.md)
+
+## 项目目的
+
+本仓库的初衷是为训练量化模型提供方便、可靠的指数成分股数据。可靠的指数历史仓位（即各时点的成分纳入与剔除记录）通常很难获取——商业数据厂商往往收费昂贵，官方来源分散在各类 PDF 和公告中，免费 API 也极少提供按时点回溯的成分股名单。缺少这类数据，量化回测就容易受到幸存者偏差和前视偏差的影响。
+
+本仓库将这些信息整理为统一格式的 CSV 文件，方便研究和建模流程直接使用。
+
+## 数据说明
+
+| 指数 | 说明 | 来源 |
+| --- | --- | --- |
+| 沪深 300 | 沪深两市规模最大、流动性最好的 300 只 A 股 | 中证指数有限公司官方公告（csindex.com.cn） |
+| 标普 500 | 美股市场 500 家大型上市公司 | [维基百科：List of S&P 500 companies](https://en.wikipedia.org/wiki/List_of_S%26P_500_companies) |
+| 纳斯达克 100 | 纳斯达克交易所 100 家最大的非金融上市公司 | [维基百科：NASDAQ-100](https://en.wikipedia.org/wiki/Nasdaq-100) |
+
+## 目录结构
+
+```text
+history/
+    csi300.csv
+    nasdaq100.csv
+    sp500.csv
+latest/
+    csi300.csv
+    nasdaq100.csv
+    sp500.csv
+```
+
+## 使用场景
+
+- 查询主要股指的当前成分股名单
+- 还原任意时点的指数成分，用于量化回测
+- 在训练量化模型时规避幸存者偏差
+- 为后续扩展更多指数成分数据提供统一结构

index_constitution-0.1.0/build_data.py

@@ -0,0 +1,51 @@
+"""Convert top-level CSVs into pickled DataFrames embedded in the package.
+
+Used both by the Hatch build hook (during ``uv build`` / ``pip install``) and
+by the test suite (via ``conftest.py``) to materialize ``_data/*.pkl`` files
+inside the installed package.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+INDICES = ("csi300", "sp500", "nasdaq100")
+FLAVORS = ("latest", "history")
+PKL_PROTOCOL = 4  # readable by Python 3.4+
+
+
+def _load_csv(csv_path: Path) -> pd.DataFrame:
+    df = pd.read_csv(csv_path)
+    for col in ("opt-in", "opt-out"):
+        if col in df.columns:
+            df[col] = pd.to_datetime(df[col], errors="coerce")
+    return df
+
+
+def build_pickles(project_root: Path, out_dir: Path) -> list[Path]:
+    """Read CSVs from ``project_root/{flavor}/{index}.csv`` and write pickles
+    to ``out_dir/{flavor}/{index}.pkl``. Returns the list of written paths.
+    """
+    written: list[Path] = []
+    for flavor in FLAVORS:
+        flavor_out = out_dir / flavor
+        flavor_out.mkdir(parents=True, exist_ok=True)
+        for index in INDICES:
+            csv_path = project_root / flavor / f"{index}.csv"
+            if not csv_path.exists():
+                raise FileNotFoundError(f"Missing source CSV: {csv_path}")
+            df = _load_csv(csv_path)
+            pkl_path = flavor_out / f"{index}.pkl"
+            df.to_pickle(pkl_path, protocol=PKL_PROTOCOL)
+            written.append(pkl_path)
+    return written
+
+
+if __name__ == "__main__":
+    root = Path(__file__).resolve().parent
+    out = root / "src" / "index_constitution" / "_data"
+    paths = build_pickles(root, out)
+    for p in paths:
+        print(p.relative_to(root))

index_constitution-0.1.0/hatch_build.py

@@ -0,0 +1,31 @@
+"""Hatch custom build hook: regenerate embedded pickle data from top-level CSVs."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class PickleDataBuildHook(BuildHookInterface):
+    PLUGIN_NAME = "pickle-data"
+
+    def initialize(self, version: str, build_data: dict) -> None:  # noqa: D401
+        root = Path(self.root)
+        # Make build_data.py importable without polluting sys.path globally.
+        sys.path.insert(0, str(root))
+        try:
+            from build_data import build_pickles  # type: ignore
+        finally:
+            sys.path.pop(0)
+
+        out_dir = root / "src" / "index_constitution" / "_data"
+        written = build_pickles(root, out_dir)
+
+        # Force-include each generated pickle into the wheel under the package.
+        force_include = build_data.setdefault("force_include", {})
+        pkg_prefix = Path("index_constitution") / "_data"
+        for pkl in written:
+            rel = pkl.relative_to(out_dir)
+            force_include[str(pkl)] = str(pkg_prefix / rel)