Metadata-Version: 2.4
Name: cn-a-stock-data
Version: 0.1.0
Summary: A Python library for fetching A-share market data from public web data sources.
Project-URL: Homepage, https://github.com/Litton-Lei/OpenStockData
Project-URL: Source, https://github.com/Litton-Lei/OpenStockData
Project-URL: Issues, https://github.com/Litton-Lei/OpenStockData/issues
Author: Litton-Lei
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: a-share,china,eastmoney,finance,stock,tencent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.9
Requires-Dist: lxml>=5.0
Requires-Dist: pandas>=2.0
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: mootdx
Requires-Dist: mootdx>=0.11; extra == 'mootdx'
Description-Content-Type: text/markdown

# OpenStockData

[![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-Apache--2.0-blue?style=flat-square)](LICENSE)
[![Tests](https://img.shields.io/github/actions/workflow/status/Litton-Lei/OpenStockData/tests.yml?branch=main&style=flat-square&label=tests)](https://github.com/Litton-Lei/OpenStockData/actions)
[![Package](https://img.shields.io/badge/package-cn--a--stock--data-00A67E?style=flat-square)](https://pypi.org/project/cn-a-stock-data/)

OpenStockData 是一个面向 A 股研究和量化原型开发的 Python 数据库。它把腾讯行情、东方财富、百度股市通、同花顺、财联社、新浪、巨潮资讯和可选 mootdx 的公开数据源封装成一组清晰、可安装、可测试的 Python API。

项目源自 [simonlin1212/a-stock-data](https://github.com/simonlin1212/a-stock-data) 的数据源思路，并重构为标准 Python 开源库：`src/` 布局、统一客户端、命令行工具、离线测试和真实接口测试。

> 本项目只封装公开网页和公开 API 数据，不提供投资建议。上游接口可能变化，请遵守各数据源服务条款并控制访问频率。

## Highlights

- **开箱即用**：`pip install` 后即可获取行情、资金、公告、新闻、研报和财务数据。
- **七层数据体系**：覆盖行情、研报、信号、资金面/筹码、新闻、基础数据和公告。
- **真实接口验证**：提供默认跳过的 live 测试，发布前可一键打通上游。
- **稳定性兜底**：默认不继承系统代理，部分接口使用可用备用域名或 fallback 数据源。
- **统一代码格式**：支持 `600519`、`sh600519`、`600519.SH` 等常见输入。
- **轻依赖**：核心只依赖 `requests`、`pandas`、`lxml`；通达信能力通过可选依赖启用。

## Install

```bash
pip install cn-a-stock-data
```

本地开发或从 GitHub 安装：

```bash
git clone https://github.com/Litton-Lei/OpenStockData.git
cd OpenStockData
pip install -e ".[dev]"
```

可选通达信能力：

```bash
pip install "cn-a-stock-data[mootdx]"
```

## Quick Start

```python
from openstockdata import StockDataClient

client = StockDataClient()

quote = client.quote("600519")
print(quote["name"], quote["price"], quote["pe_ttm"], quote["pb"])

bars = client.baidu_kline("600519")
print(bars.tail())

news = client.stock_news("600519", page_size=5)
print(news[["time", "source", "title"]])
```

函数式调用也可以：

```python
from openstockdata import realtime_quote, stock_fund_flow_120d, cninfo_announcements

print(realtime_quote("000001"))
print(stock_fund_flow_120d("600519").tail())
print(cninfo_announcements("600519", page_size=5))
```

命令行：

```bash
openstockdata quote 600519
openstockdata bars 600519 --scale 1 --len 60
openstockdata news 600519 --page-size 10
```

## Data Layers

| 层级 | 能力 | 代表函数 |
| --- | --- | --- |
| 行情层 | 实时行情、指数行情、分钟线、K 线 | `realtime_quote`, `realtime_quotes`, `index_quote`, `minute_bars`, `baidu_kline_with_ma` |
| 研报层 | 研报列表、PDF 下载、一致预期、问财语义搜索 | `eastmoney_reports`, `download_report_pdf`, `ths_eps_forecast`, `iwencai_search` |
| 信号层 | 热点题材、北向分钟流、概念归属、资金流 | `ths_hot_reason`, `hsgt_realtime`, `baidu_concept_blocks`, `baidu_fund_flow_history` |
| 资金面/筹码 | 行业排名、龙虎榜、解禁、两融、大宗交易、股东户数、分红 | `industry_comparison`, `daily_dragon_tiger`, `lockup_expiry`, `margin_trading`, `block_trade`, `holder_num_change`, `dividend_history` |
| 新闻层 | 个股新闻、7x24 快讯、财联社电报 | `eastmoney_stock_news`, `global_financial_news`, `cls_telegraph` |
| 基础数据 | 个股信息、财务摘要、新浪三表、mootdx F10 | `stock_info`, `financial_abstract`, `sina_financial_report`, `mootdx_f10` |
| 公告层 | 巨潮公告、东方财富公告数据中心 | `cninfo_announcements`, `announcements` |

## API Examples

### 批量行情

```python
from openstockdata import realtime_quotes

quotes = realtime_quotes(["600519", "000001", "300750"])
for code, quote in quotes.items():
    print(code, quote["name"], quote["price"], quote["change_pct"])
```

### 行业轮动

```python
from openstockdata import industry_comparison

data = industry_comparison(top_n=10)
for row in data["top"]:
    print(row["rank"], row["name"], row["change_pct"], row["leader"])
```

### 财务与估值

```python
from openstockdata import financial_abstract, forward_pe, calc_peg

df = financial_abstract("600519")
print(df.head())

print(forward_pe(price=120, eps_forecast=6))
print(calc_peg(pe=30, cagr=0.25))
```

### 巨潮公告

```python
from openstockdata import cninfo_announcements

df = cninfo_announcements("600519", page_size=10)
print(df[["date", "type", "title", "pdf_url"]])
```

### 问财 OpenAPI

问财接口需要配置 API Key：

```bash
export IWENCAI_API_KEY="your-key"
```

```python
from openstockdata import iwencai_search

reports = iwencai_search("贵州茅台 最新研报", channel="report", size=10)
print(reports.head())
```

## Data Sources

| 数据源 | 用途 | 是否需要 Key |
| --- | --- | --- |
| 腾讯财经 | 实时行情、估值字段、指数/ETF、分钟线 | 否 |
| 东方财富 | 个股信息、资金流、行业、龙虎榜、解禁、两融、分红、研报、新闻 | 否 |
| 百度股市通 | K 线、概念归属、资金流、热榜 | 否 |
| 同花顺 | 题材归因、北向分钟流、一致预期 EPS | 否 |
| 财联社 | 实时电报 | 否 |
| 新浪财经 | 资产负债表、利润表、现金流量表 | 否 |
| 巨潮资讯 | 公告全文检索 | 否 |
| 问财 OpenAPI | 语义搜索、结构化查询 | 是 |
| mootdx | 通达信行情、F10、财务快照 | 否，可选依赖 |

## Network Notes

`requests` 默认不继承系统代理，避免部分国内行情接口在本机代理环境下被断开。如果你确实需要走系统代理：

```python
from openstockdata import StockDataClient

client = StockDataClient(trust_env=True)
```

百度 K 线接口偶尔返回空数据时，`baidu_kline_with_ma()` 会 fallback 到腾讯日 K 线并本地计算 `ma5avgprice`、`ma10avgprice`、`ma20avgprice`。

## Development

```bash
pip install -e ".[dev]"
pytest
```

真实接口测试默认跳过，发布前可运行：

```bash
OPENSTOCKDATA_LIVE=1 PYTHONPATH=src pytest -q tests/test_live_endpoints.py
```

常用质量检查：

```bash
python -m compileall src tests
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src pytest -q
```

## Project Layout

```text
OpenStockData/
├── src/openstockdata/
│   ├── client.py          # 统一客户端
│   ├── tencent.py         # 腾讯行情
│   ├── eastmoney.py       # 东方财富
│   ├── baidu.py           # 百度股市通
│   ├── ths.py             # 同花顺
│   ├── capital.py         # 资金面/筹码
│   ├── fundamentals.py    # 基础数据/财务
│   ├── announcements.py   # 公告
│   └── valuation.py       # 估值工具
├── tests/
└── pyproject.toml
```

## Roadmap

- 增加更多字段标准化和中文列名映射。
- 为常用研究流程提供 higher-level recipe。
- 增加缓存、限速和重试策略。
- 发布到 PyPI。

## Acknowledgements

感谢 [simonlin1212/a-stock-data](https://github.com/simonlin1212/a-stock-data) 对数据源和端点的整理。本项目在其思路基础上做了 Python 包化、模块拆分、测试和发布工程化。

## License

Apache License 2.0. See [LICENSE](LICENSE).
