Metadata-Version: 2.4
Name: ohlcvpy
Version: 0.1.0
Summary: Python reader for DataHub-style sharded OHLCV Arrow datasets
Author: ohlcvpy contributors
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: io
Requires-Dist: pyarrow>=15.0.0; extra == "io"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"

# ohlcvpy

`ohlcvpy` 是一个针对 DataHub 风格数据目录的 Python 包。

## 数据结构（来自 DataHub lib）

- `stock.json`：索引文件，记录 `exchange/symbol/name/arrow_file`
- `stock_XXX.arrow`：分片文件，包含列
  - `exchange: utf8`
  - `symbol: utf8`
  - `name: utf8`
  - `daily: list<struct<date, open, high, low, close, volume, amount>>`

## 安装

```bash
pip install -e ".[io]"
```

## API 设计（极简）

```python
from ohlcvpy import open_store

store = open_store("/path/to/docs/data")

print(store.list_exchanges())
print(store.list_symbols("SSE"))

stock = store.get_stock("600519", exchange="SSE")
bars = store.get_bars("600519", exchange="SSE", limit=20)
bar = store.get_bar("600519", date=20260310, exchange="SSE")

market = store.get_market(date=20260310, exchange="SSE")  # 某一天、某交易所全部股票当日K线

print(store.latest_date())  # e.g. 20260310
```

## Example

运行仓库内示例：

```bash
python examples/api_usage.py \
  --data-dir /Users/10005612/Projects/DataHub/docs/data \
  --exchange SSE \
  --symbol 600519 \
  --date 20260310
```

## 设计要点

- 按分片懒加载，不会在初始化时读全量 Arrow。
- 用 `symbol+exchange` 作为主键，避免跨交易所冲突。
- 查询入口聚焦两个角度：按股票（`get_stock/get_bars/get_bar`）和按日期（`get_market`）。
