aquote-router 0.1.0__tar.gz

aquote_router-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 - 2026-06-14
+
+- Initial open-source release.
+- Added pytdx server pool routing with primary, hot backup and backup roles.
+- Added easyquotation Sina and Tencent fallback for realtime APIs.
+- Added pytdx-only minute kline routing.
+- Added source policy, normalized quote model, JSONL audit and SQLite audit.
+- Added CLI, examples, tests, GitHub Actions and release checklist.

aquote_router-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of Conduct
+
+We follow the Contributor Covenant spirit: be respectful, constructive and focused on improving the project.
+
+Harassment, discrimination, spam and abusive behavior are not acceptable in project spaces.
+
+Maintainers may edit, hide or remove content that is hostile, off-topic or unsafe for public collaboration.

aquote_router-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+Thank you for helping improve aquote-router.
+
+## Development
+
+```bash
+python -X utf8 -m pip install -e ".[dev,test]"
+python -X utf8 -m pytest -q
+python -X utf8 scripts/check_release.py
+```
+
+## Rules
+
+- Keep Python source files UTF-8.
+- Use explicit `encoding="utf-8"` for text reads and writes.
+- Default tests must not connect to live quote sources.
+- Live smoke tests must require `ENABLE_LIVE_SMOKE_TEST=1`.
+- Add adapter tests before adding a real data source.
+- Preserve normalized fields and audit schema compatibility.
+- Do not commit private configuration, credentials or local absolute paths.
+
+## Pull Requests
+
+Every pull request should include:
+
+- What changed.
+- Which tests ran.
+- Whether source policy or audit schema changed.
+- Any user-visible compatibility notes.

aquote_router-0.1.0/LICENSE

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

aquote_router-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+include CODE_OF_CONDUCT.md
+include pyproject.toml
+recursive-include config *.json *.yaml
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include scripts *.py *.bat
+recursive-include tests *.py

aquote_router-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: aquote-router
+Version: 0.1.0
+Summary: A-share quote source router with pytdx failover, easyquotation fallback and audit trail
+Author: aquote-router contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aquote-router/aquote-router
+Project-URL: Issues, https://github.com/aquote-router/aquote-router/issues
+Keywords: a-share,quote,router,pytdx,easyquotation
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: easyquotation>=0.7
+Requires-Dist: pytdx>=1.72
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: docs
+Dynamic: license-file
+
+# aquote-router
+
+本项目不提供投资建议，不生成候选股池，不生成买卖点，不接入真实交易。
+
+`aquote-router` 是一个面向 A 股量化研究的轻量行情源路由器，提供 pytdx 服务器池、主备切换、easyquotation 兜底、统一返回模型、source policy 和 JSONL / SQLite 审计追踪。
+
+## 功能
+
+- pytdx 服务器池读取，按 `primary -> hot_backup -> backup` 路由。
+- 同级 pytdx 服务器按 `latency_ms` 升序选择。
+- `realtime_quotes`、`full_realtime_quotes`、`index_realtime` 支持 pytdx 失败后切换到 `easyquotation_sina -> easyquotation_tencent`。
+- `minute_kline` 保持 pytdx-only，所有 pytdx 源失败时抛出明确异常。
+- 统一 `QuoteRecord` 返回模型，包含 `source`、`source_level`、`is_fallback`、`fallback_from`、`trace_id`。
+- JSONL 和 SQLite 双审计，记录每次调用的来源尝试、耗时、结果和错误。
+- 提供 Python API、CLI、示例、单元测试、CI 和发布工作流。
+
+## 不做什么
+
+- 不提供投资建议。
+- 不生成候选股池。
+- 不生成买卖点。
+- 不接入真实交易。
+- 不保存账号、登录态、密钥或 webhook。
+- 不做行情 API 服务端或数据再分发服务。
+
+## 安装
+
+```bash
+python -X utf8 -m pip install aquote-router
+```
+
+本地开发：
+
+```bash
+python -X utf8 -m pip install -e ".[dev,test]"
+```
+
+## 快速开始
+
+```python
+from aquote_router import QuoteRouter
+
+router = QuoteRouter.from_config(
+    pytdx_servers_path="config/pytdx_servers.example.json",
+    source_policy_path="config/source_policy.example.yaml",
+    audit_jsonl_path="logs/aquote_router_audit.jsonl",
+    audit_sqlite_path="logs/aquote_router_audit.sqlite3",
+)
+
+records = router.realtime_quotes(["000001", "600000"])
+for record in records:
+    print(record.to_dict())
+```
+
+公开示例 pytdx 服务器可用性会变化，用户应维护自己的服务器池配置。不要把生产配置、账号信息或本地绝对路径提交到仓库。
+
+## 公共 API
+
+```python
+router.realtime_quotes(["000001", "600000"])
+router.full_realtime_quotes(["000001", "600000"])
+router.index_realtime(["000001", "399001"])
+router.minute_kline("000001", period="1m")
+```
+
+## CLI
+
+```bash
+aquote-router diagnose
+aquote-router realtime 000001 600000
+aquote-router full-realtime 000001 600000
+aquote-router index 000001 399001
+aquote-router minute 000001 --period 1m
+```
+
+常用选项：
+
+```bash
+aquote-router --json diagnose
+aquote-router --config config/source_policy.example.yaml realtime 000001
+aquote-router --audit-jsonl logs/audit.jsonl --audit-sqlite logs/audit.sqlite3 realtime 000001
+```
+
+失败时 CLI 返回非 0 exit code，并输出简洁错误信息。
+
+## Source Policy
+
+`config/source_policy.example.yaml` 定义每个 API 的来源顺序：
+
+- `realtime_quotes`：`pytdx -> easyquotation_sina -> easyquotation_tencent`
+- `full_realtime_quotes`：`pytdx -> easyquotation_sina -> easyquotation_tencent`
+- `index_realtime`：`pytdx -> easyquotation_sina -> easyquotation_tencent`
+- `minute_kline`：`pytdx`
+
+pytdx 内部会按 `primary -> hot_backup -> backup` 选择；同级按 `latency_ms` 升序。
+
+## 审计
+
+每次调用都会生成同一个 `trace_id`，并记录：
+
+- `api_name`
+- `symbols`
+- `started_at` / `finished_at` / `duration_ms`
+- `selected_source` / `selected_source_level`
+- `attempts`
+- `fallback_chain`
+- `success`
+- `error_type` / `error_message`
+- `record_count`
+
+详见 [docs/AUDIT_TRAIL.md](docs/AUDIT_TRAIL.md)。
+
+## Fallback 示例
+
+如果 `realtime_quotes` 的 pytdx primary 和 hot_backup 都失败，backup 成功，则记录：
+
+```text
+selected_source=pytdx
+selected_source_level=backup
+fallback_chain=["pytdx:primary", "pytdx:hot_backup"]
+is_fallback=True
+fallback_from=pytdx:hot_backup
+```
+
+如果所有 pytdx 源失败，路由继续尝试 `easyquotation_sina`，再尝试 `easyquotation_tencent`。
+
+## 为什么 minute_kline 是 pytdx-only
+
+分钟 K 线对字段语义、时间粒度和数据完整性更敏感。第一版只允许 pytdx 提供 `minute_kline`，避免跨来源混用导致不可解释的差异。所有 pytdx 源失败时，库会抛出结构化异常并写入审计记录，不会伪造数据。
+
+## 与常见库的关系
+
+- AKShare：覆盖面广，适合直接获取多类金融数据；本项目只做行情来源路由和审计。
+- efinance：可作为用户侧数据工具；本项目第一版不内置为默认来源。
+- easyquotation：本项目通过它作为 realtime 兜底来源。
+- pytdx：本项目的主行情来源和分钟 K 线来源。
+
+## 贡献
+
+请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。新增真实数据源前，必须先提交 adapter 单元测试和字段标准化测试。默认测试不得联网，真实来源 smoke test 必须显式启用。
+
+## Issue 反馈
+
+请使用 GitHub issue 模板提交：
+
+- Bug report
+- Adapter request
+- Data source failure
+
+报告来源失败时，请提供 API 名称、symbol、时间、配置片段和审计 trace_id。请不要粘贴账号信息或私有配置。
+
+## 风险免责声明
+
+本项目仅用于研究基础设施。行情来源可能延迟、中断或返回异常字段。用户应自行校验数据质量，并遵守数据来源的服务条款和适用法规。
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

aquote_router-0.1.0/README.md

@@ -0,0 +1,158 @@
+# aquote-router
+
+本项目不提供投资建议，不生成候选股池，不生成买卖点，不接入真实交易。
+
+`aquote-router` 是一个面向 A 股量化研究的轻量行情源路由器，提供 pytdx 服务器池、主备切换、easyquotation 兜底、统一返回模型、source policy 和 JSONL / SQLite 审计追踪。
+
+## 功能
+
+- pytdx 服务器池读取，按 `primary -> hot_backup -> backup` 路由。
+- 同级 pytdx 服务器按 `latency_ms` 升序选择。
+- `realtime_quotes`、`full_realtime_quotes`、`index_realtime` 支持 pytdx 失败后切换到 `easyquotation_sina -> easyquotation_tencent`。
+- `minute_kline` 保持 pytdx-only，所有 pytdx 源失败时抛出明确异常。
+- 统一 `QuoteRecord` 返回模型，包含 `source`、`source_level`、`is_fallback`、`fallback_from`、`trace_id`。
+- JSONL 和 SQLite 双审计，记录每次调用的来源尝试、耗时、结果和错误。
+- 提供 Python API、CLI、示例、单元测试、CI 和发布工作流。
+
+## 不做什么
+
+- 不提供投资建议。
+- 不生成候选股池。
+- 不生成买卖点。
+- 不接入真实交易。
+- 不保存账号、登录态、密钥或 webhook。
+- 不做行情 API 服务端或数据再分发服务。
+
+## 安装
+
+```bash
+python -X utf8 -m pip install aquote-router
+```
+
+本地开发：
+
+```bash
+python -X utf8 -m pip install -e ".[dev,test]"
+```
+
+## 快速开始
+
+```python
+from aquote_router import QuoteRouter
+
+router = QuoteRouter.from_config(
+    pytdx_servers_path="config/pytdx_servers.example.json",
+    source_policy_path="config/source_policy.example.yaml",
+    audit_jsonl_path="logs/aquote_router_audit.jsonl",
+    audit_sqlite_path="logs/aquote_router_audit.sqlite3",
+)
+
+records = router.realtime_quotes(["000001", "600000"])
+for record in records:
+    print(record.to_dict())
+```
+
+公开示例 pytdx 服务器可用性会变化，用户应维护自己的服务器池配置。不要把生产配置、账号信息或本地绝对路径提交到仓库。
+
+## 公共 API
+
+```python
+router.realtime_quotes(["000001", "600000"])
+router.full_realtime_quotes(["000001", "600000"])
+router.index_realtime(["000001", "399001"])
+router.minute_kline("000001", period="1m")
+```
+
+## CLI
+
+```bash
+aquote-router diagnose
+aquote-router realtime 000001 600000
+aquote-router full-realtime 000001 600000
+aquote-router index 000001 399001
+aquote-router minute 000001 --period 1m
+```
+
+常用选项：
+
+```bash
+aquote-router --json diagnose
+aquote-router --config config/source_policy.example.yaml realtime 000001
+aquote-router --audit-jsonl logs/audit.jsonl --audit-sqlite logs/audit.sqlite3 realtime 000001
+```
+
+失败时 CLI 返回非 0 exit code，并输出简洁错误信息。
+
+## Source Policy
+
+`config/source_policy.example.yaml` 定义每个 API 的来源顺序：
+
+- `realtime_quotes`：`pytdx -> easyquotation_sina -> easyquotation_tencent`
+- `full_realtime_quotes`：`pytdx -> easyquotation_sina -> easyquotation_tencent`
+- `index_realtime`：`pytdx -> easyquotation_sina -> easyquotation_tencent`
+- `minute_kline`：`pytdx`
+
+pytdx 内部会按 `primary -> hot_backup -> backup` 选择；同级按 `latency_ms` 升序。
+
+## 审计
+
+每次调用都会生成同一个 `trace_id`，并记录：
+
+- `api_name`
+- `symbols`
+- `started_at` / `finished_at` / `duration_ms`
+- `selected_source` / `selected_source_level`
+- `attempts`
+- `fallback_chain`
+- `success`
+- `error_type` / `error_message`
+- `record_count`
+
+详见 [docs/AUDIT_TRAIL.md](docs/AUDIT_TRAIL.md)。
+
+## Fallback 示例
+
+如果 `realtime_quotes` 的 pytdx primary 和 hot_backup 都失败，backup 成功，则记录：
+
+```text
+selected_source=pytdx
+selected_source_level=backup
+fallback_chain=["pytdx:primary", "pytdx:hot_backup"]
+is_fallback=True
+fallback_from=pytdx:hot_backup
+```
+
+如果所有 pytdx 源失败，路由继续尝试 `easyquotation_sina`，再尝试 `easyquotation_tencent`。
+
+## 为什么 minute_kline 是 pytdx-only
+
+分钟 K 线对字段语义、时间粒度和数据完整性更敏感。第一版只允许 pytdx 提供 `minute_kline`，避免跨来源混用导致不可解释的差异。所有 pytdx 源失败时，库会抛出结构化异常并写入审计记录，不会伪造数据。
+
+## 与常见库的关系
+
+- AKShare：覆盖面广，适合直接获取多类金融数据；本项目只做行情来源路由和审计。
+- efinance：可作为用户侧数据工具；本项目第一版不内置为默认来源。
+- easyquotation：本项目通过它作为 realtime 兜底来源。
+- pytdx：本项目的主行情来源和分钟 K 线来源。
+
+## 贡献
+
+请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。新增真实数据源前，必须先提交 adapter 单元测试和字段标准化测试。默认测试不得联网，真实来源 smoke test 必须显式启用。
+
+## Issue 反馈
+
+请使用 GitHub issue 模板提交：
+
+- Bug report
+- Adapter request
+- Data source failure
+
+报告来源失败时，请提供 API 名称、symbol、时间、配置片段和审计 trace_id。请不要粘贴账号信息或私有配置。
+
+## 风险免责声明
+
+本项目仅用于研究基础设施。行情来源可能延迟、中断或返回异常字段。用户应自行校验数据质量，并遵守数据来源的服务条款和适用法规。
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

aquote_router-0.1.0/SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+Please report security concerns through GitHub private vulnerability reporting when available, or by contacting the maintainers through the repository owner profile.
+
+Do not paste credentials, private configuration, personal account details, or full local paths into public issues.
+
+This project is a research infrastructure library. It does not connect to personal accounts and does not execute orders.

aquote_router-0.1.0/aquote_router/__init__.py

@@ -0,0 +1,8 @@
+"""Public API for aquote-router."""
+
+from .models import QuoteRecord
+from .router import QuoteRouter
+
+__version__ = "0.1.0"
+
+__all__ = ["QuoteRecord", "QuoteRouter", "__version__"]

aquote_router-0.1.0/aquote_router/adapters/__init__.py

@@ -0,0 +1,11 @@
+"""Quote source adapters."""
+
+from .easyquotation_sina_adapter import EasyQuotationSinaAdapter
+from .easyquotation_tencent_adapter import EasyQuotationTencentAdapter
+from .pytdx_adapter import PytdxAdapter
+
+__all__ = [
+    "EasyQuotationSinaAdapter",
+    "EasyQuotationTencentAdapter",
+    "PytdxAdapter",
+]

aquote_router-0.1.0/aquote_router/adapters/base.py

@@ -0,0 +1,88 @@
+"""Base adapter contracts and shared helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from aquote_router.exceptions import AdapterError
+from aquote_router.models import QuoteRecord
+
+
+@dataclass(frozen=True)
+class PytdxServer:
+    """One pytdx server configuration entry."""
+
+    host: str
+    port: int
+    role: str
+    latency_ms: int
+    enabled: bool = True
+
+
+class BaseQuoteAdapter:
+    """Synchronous quote adapter interface."""
+
+    source: str = "unknown"
+    source_level: str | None = None
+
+    def realtime_quotes(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        raise AdapterError(f"{self.source} does not support realtime_quotes")
+
+    def full_realtime_quotes(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self.realtime_quotes(symbols, include_raw=include_raw)
+
+    def index_realtime(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self.realtime_quotes(symbols, include_raw=include_raw)
+
+    def minute_kline(
+        self,
+        symbol: str,
+        *,
+        period: str = "1m",
+        count: int = 240,
+        include_raw: bool = False,
+    ) -> list[QuoteRecord]:
+        raise AdapterError(f"{self.source} does not support minute_kline")
+
+
+def as_float(value: Any) -> float | None:
+    """Best-effort conversion to float with empty values mapped to None."""
+
+    if value is None or value == "":
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def first_value(row: dict[str, Any], keys: tuple[str, ...]) -> Any:
+    """Return the first present value for a tuple of candidate keys."""
+
+    for key in keys:
+        if key in row and row[key] not in (None, ""):
+            return row[key]
+    return None
+
+
+def market_for_symbol(symbol: str) -> int:
+    """Return pytdx market id for a common A-share symbol."""
+
+    if symbol.startswith(("5", "6", "9")):
+        return 1
+    return 0
+
+
+def source_id(source: str, source_level: str | None) -> str:
+    """Return a compact source identifier for fallback chains."""
+
+    if source_level:
+        return f"{source}:{source_level}"
+    return source

aquote_router-0.1.0/aquote_router/adapters/easyquotation_sina_adapter.py

@@ -0,0 +1,82 @@
+"""easyquotation Sina adapter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aquote_router.adapters.base import BaseQuoteAdapter, as_float, first_value
+from aquote_router.exceptions import AdapterError, SourceUnavailableError
+from aquote_router.models import QuoteRecord
+
+
+class EasyQuotationSinaAdapter(BaseQuoteAdapter):
+    """Adapter for easyquotation's Sina provider."""
+
+    source = "easyquotation_sina"
+    provider = "sina"
+
+    def realtime_quotes(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self._stocks(symbols, include_raw=include_raw)
+
+    def full_realtime_quotes(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self._stocks(symbols, include_raw=include_raw)
+
+    def index_realtime(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self._stocks(symbols, include_raw=include_raw)
+
+    def _stocks(self, symbols: list[str], *, include_raw: bool) -> list[QuoteRecord]:
+        if not symbols:
+            return []
+
+        quotation = self._quotation()
+        data = quotation.stocks(symbols)
+        if not data:
+            raise SourceUnavailableError(f"{self.source} returned no quote records")
+
+        records: list[QuoteRecord] = []
+        for symbol in symbols:
+            row = data.get(symbol) or data.get(symbol.lower()) or data.get(symbol.upper())
+            if row:
+                records.append(self._normalize(symbol, row, include_raw=include_raw))
+        if not records:
+            raise SourceUnavailableError(f"{self.source} returned no requested symbols")
+        return records
+
+    def _quotation(self) -> Any:
+        try:
+            import easyquotation
+        except Exception as exc:  # pragma: no cover - depends on user env
+            raise AdapterError("easyquotation package is not available") from exc
+        return easyquotation.use(self.provider)
+
+    def _normalize(
+        self, symbol: str, row: dict[str, Any], *, include_raw: bool
+    ) -> QuoteRecord:
+        date_value = first_value(row, ("date",))
+        time_value = first_value(row, ("time",))
+        if date_value and time_value:
+            dt_value = f"{date_value} {time_value}"
+        else:
+            dt_value = str(first_value(row, ("datetime", "time")) or "") or None
+
+        return QuoteRecord(
+            symbol=symbol,
+            name=first_value(row, ("name",)),
+            price=as_float(first_value(row, ("now", "price", "close"))),
+            open=as_float(first_value(row, ("open",))),
+            high=as_float(first_value(row, ("high",))),
+            low=as_float(first_value(row, ("low",))),
+            pre_close=as_float(first_value(row, ("close", "pre_close", "last_close"))),
+            volume=as_float(first_value(row, ("volume", "vol"))),
+            amount=as_float(first_value(row, ("turnover", "amount"))),
+            datetime=dt_value,
+            source=self.source,
+            source_level=self.source_level,
+            raw=dict(row) if include_raw else None,
+        )

aquote_router-0.1.0/aquote_router/adapters/easyquotation_tencent_adapter.py

@@ -0,0 +1,10 @@
+"""easyquotation Tencent adapter."""
+
+from aquote_router.adapters.easyquotation_sina_adapter import EasyQuotationSinaAdapter
+
+
+class EasyQuotationTencentAdapter(EasyQuotationSinaAdapter):
+    """Adapter for easyquotation's Tencent provider."""
+
+    source = "easyquotation_tencent"
+    provider = "tencent"