ashare-data-lite 0.1.0__tar.gz

ashare_data_lite-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 ashare-data-lite 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.
+

ashare_data_lite-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md LICENSE
+include docs/api.md
+recursive-include tests *.py
+recursive-include scripts *.py

ashare_data_lite-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: ashare-data-lite
+Version: 0.1.0
+Summary: 使用 Python 标准库直接获取证券行情、基金净值与宏观序列
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zhangjw777/ashare-data-lite
+Project-URL: Repository, https://github.com/zhangjw777/ashare-data-lite
+Project-URL: Documentation, https://github.com/zhangjw777/ashare-data-lite/blob/main/docs/api.md
+Project-URL: Issues, https://github.com/zhangjw777/ashare-data-lite/issues
+Keywords: ashare,stock,etf,market-data,finance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Requires-Dist: PyYAML>=6; extra == "dev"
+Dynamic: license-file
+
+# ashare-data-lite
+
+轻量、免费的 Python 行情工具，提供沪深股票、ETF、指数、基金净值及海外市场数据。Python 3.10+，运行代码使用标准库，采用 MIT 许可证。
+
+## 安装与使用
+
+从 PyPI 安装：
+
+```shell
+pip install ashare-data-lite
+```
+
+```python
+from ashare_data import get_etf_quote, get_etf_history, get_fund_nav_history
+
+quote = get_etf_quote("159941")
+print(quote.name, quote.last, quote.iopv)
+
+bars = get_etf_history("159941", "2026-09-01", "2026-10-23")
+print(bars[-1].timestamp, bars[-1].close, bars[-1].volume)
+
+nav = get_fund_nav_history("159941", "2026-09-01", "2026-10-23")
+print(nav[-1].date, nav[-1].nav)
+```
+
+ETF 指交易所交易基金，IOPV 指基金份额参考净值。查询结果采用 dataclass，支持属性访问和 `to_dict()`。股票数量以股计，ETF 数量以份计；百分率 `2.5` 表示 `2.5%`。
+
+## 支持的数据
+
+| 数据 | 入口 |
+| --- | --- |
+| 股票、ETF、指数实时行情及五档买卖报价 | `get_stock_quote`、`get_etf_quote`、`get_index_quote`，批量方法以 `_quotes` 结尾 |
+| 日线与 5 / 15 / 30 分钟 K 线 | `get_stock_history`、`get_etf_history`、`get_index_history` |
+| 基金历史单位净值 | `get_fund_nav_history` |
+| ETF 目录、上交所 ETF 份额 | `get_etf_catalog`、`get_sse_etf_shares` |
+| FRED 经济序列及 VIX | `get_fred_series`、`get_vix_history` |
+| Twelve Data 海外 K 线 | `get_twelve_bars`、`get_twelve_daily_history` |
+
+沪深行情、基金净值、目录和份额可直接查询。FRED 和 Twelve Data 使用服务商账户密钥，支持环境变量 `FRED_API_KEY`、`TWELVE_DATA_API_KEY`。
+
+## 自动降级
+
+日线默认原始价格，依次尝试腾讯、新浪；基金单位净值依次尝试东方财富移动端、网页。使用默认配置即可查询，也可设置来源优先级：
+
+```python
+bars = get_etf_history(
+    "159941", "2026-10-01", "2026-10-23",
+    sources=["sina", "tencent"],
+)
+```
+
+降级过程保持周期与复权方式一致。分钟线由新浪提供；前复权、后复权日线由腾讯提供。来源的覆盖日期与账户权限决定实际可用数据范围。
+
+## 批量、序列化与异步
+
+```python
+import json
+from ashare_data import get_etf_quotes
+
+quotes = get_etf_quotes(["159941", "513100"])
+for quote in quotes:
+    print(quote.symbol, quote.last, quote.error)
+
+print(json.dumps(quotes[0].to_dict(), ensure_ascii=False))
+```
+
+```python
+import asyncio
+from ashare_data import AsyncMarketClient
+
+async def main():
+    client = AsyncMarketClient(timeout=10)
+    quotes = await client.get_etf_quotes(["159941", "513100"])
+    print(quotes[0].last)
+
+asyncio.run(main())
+```
+
+同步客户端 `MarketClient` 与异步客户端 `AsyncMarketClient` 提供相同的方法和返回类型。完整参数、返回字段、单位及异常见 [API 文档](https://github.com/zhangjw777/ashare-data-lite/blob/main/docs/api.md)。
+
+## 数据来源与使用范围
+
+实时行情来自腾讯；历史 K 线来自腾讯、新浪；基金净值来自东方财富；基金份额来自上交所；经济序列与海外行情来自 FRED、Twelve Data。数据源的覆盖范围、延迟、接口格式及访问额度可能变化，使用方应做好超时处理并校验关键数据。账户接口遵循对应服务商的套餐和调用限制。
+
+本项目的 MIT 许可证适用于程序代码。行情数据的使用、存储和再分发遵循各来源的使用条款；交易分析需要结合其他信息校验，并自行承担决策风险。
+
+## 开发
+
+```shell
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+```
+
+使用案例位于 `examples/`。在线样本检查运行 `python examples/smoke_check.py`，记录保存在 `docs/live-check.json`。GitHub Actions 在 Python 3.10～3.13 执行自动测试。
+
+## 发布新版本
+
+在 `main` 分支审阅并提交功能改动后执行：
+
+```shell
+python scripts/release.py 0.1.1
+```
+
+脚本检查 PyPI 与 Git 标签、更新版本、构建并安装测试，然后推送提交与 `v0.1.1` 标签。GitHub Actions 使用 `pypi` Environment 和 OIDC（开放身份连接）可信发布到 PyPI。工作流运行记录见 [Publish to PyPI](https://github.com/zhangjw777/ashare-data-lite/actions/workflows/publish.yml)。
+
+仅执行发布前验证：`python scripts/release.py 0.1.1 --check-only`。项目内的发布指导位于 [.agents/skills/publish-pypi/SKILL.md](https://github.com/zhangjw777/ashare-data-lite/blob/main/.agents/skills/publish-pypi/SKILL.md)。
+

ashare_data_lite-0.1.0/README.md

@@ -0,0 +1,107 @@
+# ashare-data-lite
+
+轻量、免费的 Python 行情工具，提供沪深股票、ETF、指数、基金净值及海外市场数据。Python 3.10+，运行代码使用标准库，采用 MIT 许可证。
+
+## 安装与使用
+
+从 PyPI 安装：
+
+```shell
+pip install ashare-data-lite
+```
+
+```python
+from ashare_data import get_etf_quote, get_etf_history, get_fund_nav_history
+
+quote = get_etf_quote("159941")
+print(quote.name, quote.last, quote.iopv)
+
+bars = get_etf_history("159941", "2026-09-01", "2026-10-23")
+print(bars[-1].timestamp, bars[-1].close, bars[-1].volume)
+
+nav = get_fund_nav_history("159941", "2026-09-01", "2026-10-23")
+print(nav[-1].date, nav[-1].nav)
+```
+
+ETF 指交易所交易基金，IOPV 指基金份额参考净值。查询结果采用 dataclass，支持属性访问和 `to_dict()`。股票数量以股计，ETF 数量以份计；百分率 `2.5` 表示 `2.5%`。
+
+## 支持的数据
+
+| 数据 | 入口 |
+| --- | --- |
+| 股票、ETF、指数实时行情及五档买卖报价 | `get_stock_quote`、`get_etf_quote`、`get_index_quote`，批量方法以 `_quotes` 结尾 |
+| 日线与 5 / 15 / 30 分钟 K 线 | `get_stock_history`、`get_etf_history`、`get_index_history` |
+| 基金历史单位净值 | `get_fund_nav_history` |
+| ETF 目录、上交所 ETF 份额 | `get_etf_catalog`、`get_sse_etf_shares` |
+| FRED 经济序列及 VIX | `get_fred_series`、`get_vix_history` |
+| Twelve Data 海外 K 线 | `get_twelve_bars`、`get_twelve_daily_history` |
+
+沪深行情、基金净值、目录和份额可直接查询。FRED 和 Twelve Data 使用服务商账户密钥，支持环境变量 `FRED_API_KEY`、`TWELVE_DATA_API_KEY`。
+
+## 自动降级
+
+日线默认原始价格，依次尝试腾讯、新浪；基金单位净值依次尝试东方财富移动端、网页。使用默认配置即可查询，也可设置来源优先级：
+
+```python
+bars = get_etf_history(
+    "159941", "2026-10-01", "2026-10-23",
+    sources=["sina", "tencent"],
+)
+```
+
+降级过程保持周期与复权方式一致。分钟线由新浪提供；前复权、后复权日线由腾讯提供。来源的覆盖日期与账户权限决定实际可用数据范围。
+
+## 批量、序列化与异步
+
+```python
+import json
+from ashare_data import get_etf_quotes
+
+quotes = get_etf_quotes(["159941", "513100"])
+for quote in quotes:
+    print(quote.symbol, quote.last, quote.error)
+
+print(json.dumps(quotes[0].to_dict(), ensure_ascii=False))
+```
+
+```python
+import asyncio
+from ashare_data import AsyncMarketClient
+
+async def main():
+    client = AsyncMarketClient(timeout=10)
+    quotes = await client.get_etf_quotes(["159941", "513100"])
+    print(quotes[0].last)
+
+asyncio.run(main())
+```
+
+同步客户端 `MarketClient` 与异步客户端 `AsyncMarketClient` 提供相同的方法和返回类型。完整参数、返回字段、单位及异常见 [API 文档](https://github.com/zhangjw777/ashare-data-lite/blob/main/docs/api.md)。
+
+## 数据来源与使用范围
+
+实时行情来自腾讯；历史 K 线来自腾讯、新浪；基金净值来自东方财富；基金份额来自上交所；经济序列与海外行情来自 FRED、Twelve Data。数据源的覆盖范围、延迟、接口格式及访问额度可能变化，使用方应做好超时处理并校验关键数据。账户接口遵循对应服务商的套餐和调用限制。
+
+本项目的 MIT 许可证适用于程序代码。行情数据的使用、存储和再分发遵循各来源的使用条款；交易分析需要结合其他信息校验，并自行承担决策风险。
+
+## 开发
+
+```shell
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+```
+
+使用案例位于 `examples/`。在线样本检查运行 `python examples/smoke_check.py`，记录保存在 `docs/live-check.json`。GitHub Actions 在 Python 3.10～3.13 执行自动测试。
+
+## 发布新版本
+
+在 `main` 分支审阅并提交功能改动后执行：
+
+```shell
+python scripts/release.py 0.1.1
+```
+
+脚本检查 PyPI 与 Git 标签、更新版本、构建并安装测试，然后推送提交与 `v0.1.1` 标签。GitHub Actions 使用 `pypi` Environment 和 OIDC（开放身份连接）可信发布到 PyPI。工作流运行记录见 [Publish to PyPI](https://github.com/zhangjw777/ashare-data-lite/actions/workflows/publish.yml)。
+
+仅执行发布前验证：`python scripts/release.py 0.1.1 --check-only`。项目内的发布指导位于 [.agents/skills/publish-pypi/SKILL.md](https://github.com/zhangjw777/ashare-data-lite/blob/main/.agents/skills/publish-pypi/SKILL.md)。
+

ashare_data_lite-0.1.0/docs/api.md

@@ -0,0 +1,228 @@
+# API 参考
+
+所有公开入口均可从 `ashare_data` 导入。调用返回 dataclass 对象或其列表，使用 `obj.field` 读取字段、`obj.to_dict()` 转为适合 JSON 的字典。
+
+## 1. 共同约定
+
+| 项目 | 约定 |
+| --- | --- |
+| 代码 | 字符串，支持 `159941`、`sz159941`、`159941.SZ` |
+| 品种 | `instrument="auto" / "stock" / "etf" / "index"` |
+| 日期参数 | `YYYY-MM-DD` 字符串或 `datetime.date`，起止日均包含；默认从 `1970-01-01` 到中国时区当天 |
+| 代码歧义 | 股票入口 `"000001"` 为平安银行，指数入口为上证指数；混合入口中的指数使用 `"sh000001"`、`"sz399001"` |
+| 时间 | `timestamp` 为带时区的 `datetime`；沪深行情为 UTC+08:00，海外 K 线为 UTC |
+| 日期字段 | `date` 为 `datetime.date`，表示净值所属日、统计日或观测日 |
+| 数量 | 沪深股票按股、ETF 按份；不同来源的上游取整精度可能有差异 |
+| 价格与金额 | 按 `currency` 标价币种；市值与成交额使用基本货币单位，如人民币元 |
+| 百分率 | `*_pct` 为百分数，`2.5` 表示 `2.5%` |
+| 缺失值 | 可选字段为 `None`，成功查询的空区间返回 `[]`；FRED 缺失观测跳过 |
+| 列表顺序 | 历史按时间去重升序；批量行情按首次输入顺序去重 |
+| 对象 | dataclass 为只读对象；`to_dict()` 递归将日期、时间转为 ISO 8601 字符串，将元组转为列表 |
+
+## 2. 实时行情
+
+| 函数 | 参数 | 返回 |
+| --- | --- | --- |
+| `get_stock_quote` / `get_etf_quote` / `get_index_quote` | `code: str` | `Quote` |
+| `get_stock_quotes` / `get_etf_quotes` / `get_index_quotes` | `codes: Sequence[str]` | `list[Quote]` |
+| `get_quote` | `code, *, instrument="auto"` | `Quote` |
+| `get_quotes` | `codes, *, instrument="auto"` | `list[Quote]` |
+
+```python
+from ashare_data import get_etf_quote, get_quotes
+
+quote = get_etf_quote("159941")
+print(quote.last, quote.iopv, quote.premium_rate_pct)
+print(quote.bids[0].price, quote.bids[0].volume)
+
+quotes = get_quotes(["sz159941", "sh600519", "sh000001"])
+```
+
+实时行情采用腾讯。单只查询缺失时抛出 `QuoteNotFoundError`；批量查询的缺失项为 `Quote`，其 `error` 包含原因，其余可选字段为 `None`。整次网络或响应解析失败时抛出对应异常。
+
+### Quote
+
+| 字段 | 类型 | 含义 |
+| --- | --- | --- |
+| `symbol` / `code` | `str` | 带市场前缀的证券标识 / 六位代码 |
+| `instrument` | `str` | `stock`、`etf`、`index`；混合查询缺失项可为 `auto` |
+| `source` | `str` | 本次实际数据来源 |
+| `name` | `str \| None` | 证券名称 |
+| `timestamp` | `datetime \| None` | 行情时间 |
+| `currency` | `str \| None` | 标价币种，例如 `CNY` |
+| `last` / `prev_close` | `float \| None` | 最新价 / 昨收价 |
+| `open` / `high` / `low` | `float \| None` | 当日开盘价 / 最高价 / 最低价 |
+| `change` / `change_pct` | `float \| None` | 相对昨收的涨跌额 / 涨跌幅 |
+| `volume` / `amount` | `float \| None` | 当日累计成交数量 / 成交金额 |
+| `outer_volume` / `inner_volume` | `float \| None` | 外盘 / 内盘成交数量 |
+| `turnover_rate_pct` / `amplitude_pct` | `float \| None` | 换手率 / 振幅 |
+| `market_cap` / `circulating_market_cap` | `float \| None` | 总市值 / 流通市值 |
+| `pe` / `pb` | `float \| None` | 股票市盈率 / 市净率 |
+| `limit_up` / `limit_down` | `float \| None` | 涨停价 / 跌停价 |
+| `volume_ratio` | `float \| None` | 量比 |
+| `order_imbalance` | `float \| None` | 买五档数量合计减卖五档数量合计 |
+| `average_price` | `float \| None` | 当日成交均价 |
+| `is_suspended` | `bool` | 源端停牌标记 |
+| `bids` / `asks` | `tuple[OrderLevel, ...]` | 买 / 卖报价，按一档到五档排列；缺失行情时为空元组 |
+| `iopv` | `float \| None` | ETF 份额参考净值 |
+| `premium_rate_pct` | `float \| None` | ETF 折溢价率；正数为溢价，负数为折价 |
+| `circulating_shares` / `total_shares` | `float \| None` | 流通 / 总股票股数或基金份数 |
+| `error` | `str \| None` | 批量缺失项的错误信息；成功时为 `None` |
+
+`OrderLevel` 表示一档买卖报价。
+
+| 字段 | 类型 | 含义 |
+| --- | --- | --- |
+| `price` | `float \| None` | 该档报价 |
+| `volume` | `float \| None` | 该档委托数量，股或份 |
+
+ETF 专属字段在其他品种上为 `None`；其余可选字段由品种与数据可用性决定。
+
+## 3. 历史 K 线
+
+`get_stock_history`、`get_etf_history`、`get_index_history` 共用以下签名，返回 `list[Bar]`：
+
+```python
+get_etf_history(
+    code, start=None, end=None, *,
+    sources=None, adjust="none", scale=240, datalen=5049, max_pages=100,
+)
+```
+
+`get_history` 使用相同参数，并增加 `instrument="auto"`。
+
+| 参数 | 含义 |
+| --- | --- |
+| `sources` | 按优先级排列的列表；日线默认 `["tencent", "sina"]`，分钟线默认 `["sina"]` |
+| `adjust` | `"none"` 原始价格、`"qfq"` 前复权、`"hfq"` 后复权；指数使用 `"none"` |
+| `scale` | `240` 日线；`5`、`15`、`30` 分钟线 |
+| `datalen` | 新浪最近 K 线数量，1～5049，默认 5049 |
+| `max_pages` | 腾讯历史分页上限，正整数，默认 100 |
+
+来源出错后按顺序尝试下一个兼容来源，成功后返回该来源的结果。选择兼容来源时保持周期和复权方式一致：
+
+| 周期、价格方式 | 可用来源 |
+| --- | --- |
+| 日线，原始价格 | `tencent`、`sina` |
+| 日线，前复权或后复权 | `tencent` |
+| 5 / 15 / 30 分钟线，原始价格 | `sina` |
+
+`sources` 支持调整顺序或仅保留所需来源。新浪提供最近记录；条数上限截断所请求的起始日期时报告来源失败。所有兼容来源失败时抛出 `AllSourcesFailedError`。请求的周期与复权方式缺少兼容来源时抛出 `ConfigurationError`。
+
+```python
+from ashare_data import get_etf_history
+
+daily = get_etf_history("159941", "2026-10-01", "2026-10-23")
+minute = get_etf_history("159941", "2026-10-23", "2026-10-23", scale=5)
+adjusted = get_etf_history("159941", "2026-01-01", "2026-10-23", adjust="qfq")
+preferred = get_etf_history(
+    "159941", "2026-10-01", "2026-10-23", sources=["sina", "tencent"],
+)
+print(daily[-1].close)
+```
+
+### Bar
+
+沪深历史与海外历史共用 `Bar`。
+
+| 字段 | 类型 | 含义 |
+| --- | --- | --- |
+| `symbol` | `str` | 沪深为市场前缀代码，海外为服务商证券代码 |
+| `timestamp` | `datetime` | K 线记录的日期或时间；日线为所属交易日零点 |
+| `interval` | `str` | 周期，如 `1day`、`5min` |
+| `source` | `str` | 本次实际来源 |
+| `adjust` | `str` | 实际价格方式：`none`、`qfq`、`hfq`、`all`、`splits`、`dividends` |
+| `open` / `high` / `low` / `close` | `float \| None` | 开盘 / 最高 / 最低 / 收盘价格；成功记录的收盘价有值 |
+| `volume` | `float \| None` | 该周期成交数量 |
+| `volume_unit` | `str` | 沪深为 `share`：股或份；海外为 `provider`：服务商对该品种定义的成交量单位 |
+| `currency` | `str \| None` | 标价币种；沪深为 `CNY`，海外随品种确定 |
+
+## 4. 基金净值、目录与份额
+
+| 函数 | 签名 | 返回 |
+| --- | --- | --- |
+| `get_fund_nav_history` | `(code, start=None, end=None, *, sources=None)` | `list[FundNav]` |
+| `get_etf_catalog` | `()` | `dict[str, str]`，六位 ETF 代码到名称的映射 |
+| `get_sse_etf_shares` | `(day)`，统计日期 | `list[FundShares]`，上交所 ETF 份额 |
+
+净值的默认来源顺序为 `["eastmoney_mobile", "eastmoney_web"]`，可用 `sources` 调整优先级。移动端失败后，网页接口重新获取完整区间；同一客户端自动管理请求间隔和冷却状态。
+
+```python
+from ashare_data import get_fund_nav_history, get_etf_catalog, get_sse_etf_shares
+
+nav = get_fund_nav_history("159941", "2026-10-01", "2026-10-23")
+print(nav[-1].date, nav[-1].nav)
+catalog = get_etf_catalog()
+shares = get_sse_etf_shares("2026-10-23")
+```
+
+`FundNav` 与 `FundShares` 的字段如下。
+
+| 字段 | 类型 | 所属类型与含义 |
+| --- | --- | --- |
+| `code` | `str` | 两者共用，六位基金代码 |
+| `date` | `date` | 净值所属日 / 份额统计日 |
+| `source` | `str` | 本次实际来源 |
+| `nav` | `float` | FundNav 单位净值，币种随基金份额类别确定 |
+| `shares` | `float \| None` | FundShares 基金份额，单位份 |
+
+## 5. FRED 与海外行情
+
+| 函数 | 签名 | 返回 |
+| --- | --- | --- |
+| `get_fred_series` | `(series_id, start=None, end=None, *, api_key=None)` | `list[Observation]` |
+| `get_vix_history` | `(start=None, end=None, *, api_key=None)` | `list[Observation]`，VIX 日度收盘序列 `VIXCLS` |
+| `get_twelve_bars` | `(symbol, *, interval="1day", outputsize=5000, start=None, end=None, adjust="all", api_key=None)` | 一页 `list[Bar]` |
+| `get_twelve_daily_history` | `(symbol, start=None, end=None, *, adjust="all", api_key=None, max_pages=100)` | 自动分页的 `list[Bar]` |
+
+FRED 密钥环境变量为 `FRED_API_KEY`，Twelve Data 为 `TWELVE_DATA_API_KEY`。密钥优先级：单次 `api_key` → 客户端配置 → 环境变量。
+
+Twelve Data 的 `outputsize` 为 1～5000；`interval` 按账户支持的周期传入；`adjust` 可为 `none`、`splits`、`dividends`、`all`。`get_twelve_bars` 的起止参数可使用日期或日期时间字符串；完整日线的起止参数使用日期。可用市场、历史长度和调用额度由账户权限决定。
+
+```python
+from ashare_data import MarketClient
+
+client = MarketClient(fred_api_key="YOUR_FRED_KEY", twelve_api_key="YOUR_TWELVE_KEY")
+vix = client.get_vix_history("2026-10-01", "2026-10-23")
+spy = client.get_twelve_daily_history("SPY", "2026-01-01", "2026-10-23")
+```
+
+`Observation` 表示序列的单次有效观测。
+
+| 字段 | 类型 | 含义 |
+| --- | --- | --- |
+| `series_id` | `str` | FRED 序列标识 |
+| `date` | `date` | 观测日期 |
+| `value` | `float` | 有效观测值，单位由该 FRED 序列定义 |
+| `source` | `str` | 本次实际来源 |
+
+## 6. 配置、客户端与异常
+
+`configure` 签名为 `(*, timeout=10, retries=1, fred_api_key=None, twelve_api_key=None) -> MarketClient`，设置顶层函数使用的默认客户端。`timeout` 为每次网络请求超时秒数，须大于 0；`retries` 为网络异常及临时网关错误的重试次数，须为非负整数。
+
+`MarketClient` 使用相同配置参数，实例方法与顶层函数同名、同参数、同返回类型。`AsyncMarketClient` 提供对应的 `await` 方法。实例间配置独立；同一客户端复用净值限速和冷却状态。异步取消后，已开始的网络请求由超时约束。
+
+```python
+import asyncio
+from ashare_data import AsyncMarketClient, configure
+
+configure(timeout=10, retries=1)
+
+async def main():
+    client = AsyncMarketClient(timeout=10)
+    quote = await client.get_etf_quote("159941")
+    print(quote.last)
+
+asyncio.run(main())
+```
+
+| 异常 | 含义 |
+| --- | --- |
+| `MarketDataError` | 全部公开行情异常的父类 |
+| `InvalidCodeError` | 代码格式错误 |
+| `ConfigurationError` | 参数、来源能力或密钥配置错误 |
+| `RequestError` | 网络或 HTTP 错误；`status_code` 为 HTTP 状态码，`retry_after` 为建议等待秒数 |
+| `DataFormatError` | 来源响应或分页结果异常 |
+| `QuoteNotFoundError` | 单只证券行情缺失 |
+| `AllSourcesFailedError` | 所有候选来源失败；`errors` 为按尝试顺序排列的 `(来源名, 异常)` 列表 |
+

ashare_data_lite-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ashare-data-lite"
+dynamic = ["version"]
+description = "使用 Python 标准库直接获取证券行情、基金净值与宏观序列"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+keywords = ["ashare", "stock", "etf", "market-data", "finance"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/zhangjw777/ashare-data-lite"
+Repository = "https://github.com/zhangjw777/ashare-data-lite"
+Documentation = "https://github.com/zhangjw777/ashare-data-lite/blob/main/docs/api.md"
+Issues = "https://github.com/zhangjw777/ashare-data-lite/issues"
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "twine>=6", "PyYAML>=6"]
+
+[tool.setuptools.dynamic]
+version = {attr = "ashare_data.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["ashare_data*"]
+
+[tool.setuptools.package-data]
+ashare_data = ["py.typed"]
+

ashare_data_lite-0.1.0/scripts/release.py

@@ -0,0 +1,109 @@
+"""验证发行包并创建不可变版本标签；推送后由 GitHub Actions 发布到 PyPI。"""
+
+import argparse
+import json
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tempfile
+from urllib.error import HTTPError
+from urllib.request import urlopen
+
+from validate_release import ROOT, project_version, validate
+
+
+def git(*args):
+    result = subprocess.run(
+        ["git", *args], cwd=ROOT, text=True, capture_output=True, check=True
+    )
+    return result.stdout.strip()
+
+
+def release(version, check_only=False):
+    if not re.fullmatch(r"(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)", version):
+        raise RuntimeError("版本号使用 X.Y.Z 格式")
+    if git("status", "--porcelain"):
+        raise RuntimeError("请先审阅并提交代码改动，再执行发布命令")
+    branch = git("branch", "--show-current")
+    if branch != "main":
+        raise RuntimeError("发布命令在 main 分支执行")
+    git("fetch", "origin", "--tags")
+    if (
+        not subprocess.run(
+            ["git", "merge-base", "--is-ancestor", "origin/main", "HEAD"], cwd=ROOT
+        ).returncode
+        == 0
+    ):
+        raise RuntimeError("请先整合 origin/main 的最新提交")
+    tag = f"v{version}"
+    if tag in git("tag", "--list").splitlines():
+        raise RuntimeError(f"版本标签已存在：{tag}，请选择新版本")
+    try:
+        with urlopen(
+            "https://pypi.org/pypi/ashare-data-lite/json", timeout=15
+        ) as response:
+            versions = json.load(response)["releases"]
+    except HTTPError as exc:
+        if exc.code != 404:
+            raise
+        versions = {}
+    if version in versions:
+        raise RuntimeError(f"PyPI 版本已存在：{version}")
+    stable = [
+        tuple(map(int, item.split(".")))
+        for item in versions
+        if re.fullmatch(r"\d+\.\d+\.\d+", item)
+    ]
+    if stable and tuple(map(int, version.split("."))) <= max(stable):
+        raise RuntimeError("新版本应高于当前 PyPI 稳定版本")
+    file = ROOT / "src" / "ashare_data" / "__init__.py"
+    previous = file.read_text(encoding="utf-8")
+    changed = version != project_version()
+    if changed:
+        file.write_text(
+            re.sub(
+                r'^__version__ = "[^"]+"',
+                f'__version__ = "{version}"',
+                previous,
+                count=1,
+                flags=re.MULTILINE,
+            ),
+            encoding="utf-8",
+        )
+    try:
+        with tempfile.TemporaryDirectory(prefix="ashare-release-") as directory:
+            validate(Path(directory) / "dist")
+    except BaseException:
+        if changed:
+            file.write_text(previous, encoding="utf-8")
+        raise
+    if check_only:
+        if changed:
+            file.write_text(previous, encoding="utf-8")
+        print("PASS release preflight")
+        return
+    if changed:
+        git("add", "src/ashare_data/__init__.py")
+        git("commit", "-m", f"Release {version}")
+    git("push", "origin", "HEAD:main")
+    git("tag", "-a", tag, "-m", f"ashare-data-lite {version}")
+    git("push", "origin", f"refs/tags/{tag}")
+    print(
+        "已触发发布：https://github.com/zhangjw777/ashare-data-lite/actions/workflows/publish.yml"
+    )
+    print(
+        f"发布后验证：python -m pip install --index-url https://pypi.org/simple ashare-data-lite=={version}"
+    )
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("version")
+    parser.add_argument("--check-only", action="store_true")
+    args = parser.parse_args()
+    try:
+        release(args.version, args.check_only)
+    except (RuntimeError, subprocess.CalledProcessError) as exc:
+        print(f"发布中止：{exc}", file=sys.stderr)
+        raise SystemExit(1)