pyqauto 0.3.0

A-share quote source router with pytdx failover, easyquotation fallback and audit trail

pyqauto

pyqauto 是一个面向 A 股行情获取的 Python 行情源自动选择工具，支持 pytdx 主备切换、easyquotation fallback、实时行情、分钟K线、日K、统一 kline 接口、source policy 和 JSONL / SQLite 审计追踪。

Python A-share quote auto-selector with pytdx failover, easyquotation fallback, K-line APIs and audit trail.

python -X utf8 -m pip install pyqauto -i https://pypi.org/simple

from pyqauto import QuoteRouter

pyqauto realtime 000001 600000
pyqauto kline 000001 --period 15m --count 10
pyqauto probe-pytdx --json

本项目不提供投资建议，不生成候选股池，不生成买卖点，不接入真实交易，不保证公开免费行情源 100% 准确、实时、完整、可用。

It is designed for research scripts that need A股行情, A股实时行情, A股K线, 分钟K线, 15分钟K线, 日K, source policy, 数据源 fallback, 行情审计, trace_id, JSONL, and SQLite audit records in one small Python package. Realtime routing uses pytdx first, then easyquotation Sina and Tencent fallback according to policy.

Boundary: this project is data access infrastructure only. It does not provide investment advice, account login, order execution, screening, timing signals, or performance claims.

中文文档

• 中文快速开始：README.zh-CN.md
• 新手从这里开始：docs/NEW_USER_START_HERE.md
• K线使用指南：docs/KLINE_GUIDE.md
• 数据源说明：docs/DATA_SOURCES.md
• 常见问题排查：docs/TROUBLESHOOTING.md

English start here: docs/NEW_USER_START_HERE.md

Data source policy: docs/DATA_SOURCES.md

Issue guide: docs/ISSUE_GUIDE.md

Examples: realtime, 15m K-line, and daily K-line

Install

python -X utf8 -m pip install pyqauto

Minimal Realtime Quote

import pyqauto as aq

record = aq.quote("000001")
print(record.to_dict())

Default source policy and pytdx server config are bundled in the package. Import and call functions directly. No local config files are required.

Minimal 15m K-line

bars = aq.kline("000001", period="15m", count=120)
print(bars[0].to_dict())

K-line Timeout Check

K-line APIs are pytdx-only. If a K-line call times out, first probe the pytdx server pool for the current network:

pyqauto probe-pytdx --json --output config/pytdx_servers.active.local.json

Then pass the active local pool explicitly:

pyqauto kline 000001 --period 15m --count 10 \
  --pytdx-servers config/pytdx_servers.active.local.json --json

config/pytdx_servers.active.local.json is a local diagnostic result and should not be committed.

Features

• realtime_quotes, full_realtime_quotes, and index_realtime route through pytdx -> easyquotation_sina -> easyquotation_tencent.
• minute_kline, daily_kline, and unified kline are pytdx-only.
• pytdx servers are ordered by primary -> hot_backup -> backup, then by latency_ms.
• probe-pytdx can generate a local active pytdx server pool for diagnostics.
• Return models include source, source_level, is_fallback, fallback_from, and trace_id.
• JSONL and SQLite audit logs record attempts, fallback_chain, selected_source, duration, record count, and final error details.
• The default test suite is offline. Live smoke checks require explicit opt-in.

Local development:

python -X utf8 -m pip install -e ".[dev,test]"

Quick Start

import pyqauto as aq

aq.configure(
    audit_jsonl_path="logs/pyqauto_audit.jsonl",
    audit_sqlite_path="logs/pyqauto_audit.sqlite3",
)

records = aq.quotes(["000001", "600000"])
for record in records:
    print(record.to_dict())

K-line examples:

aq.minute("000001", period="15m", count=120)
aq.daily("000001", count=120)
aq.kline("000001", period="1d", count=120)

Public API

aq.quote("000001")
aq.quotes(["000001", "600000"])
aq.full_quotes(["000001", "600000"])
aq.index(["000001", "399001"])
aq.minute("000001", period="15m", count=120)
aq.daily("000001", count=120)
aq.kline("000001", period="1d", count=120)
aq.diagnose()

For advanced use, from pyqauto import QuoteRouter remains available.

CLI

pyqauto realtime 000001 600000
pyqauto full 000001 600000
pyqauto full-realtime 000001 600000
pyqauto index 000001 399001
pyqauto minute 000001 --period 15m --count 120
pyqauto daily 000001 --count 120
pyqauto kline 000001 --period 15m --count 120
pyqauto kline 000001 --period 1d --count 120
pyqauto probe-pytdx --json --output config/pytdx_servers.active.local.json
pyqauto diagnose --json

Use --json for complete output, especially when table columns are too wide. CLI failures return a non-zero exit code and a structured project error code.

When K-line calls time out, first refresh a local pytdx pool:

pyqauto probe-pytdx --json --output config/pytdx_servers.active.local.json

Then pass the active local pool explicitly:

pyqauto kline 000001 --period 15m --count 10 \
  --pytdx-servers config/pytdx_servers.active.local.json --json

config/pytdx_servers.active.local.json is an observed local diagnostic result and should not be committed. Free pytdx server availability changes by network, region, and time; this project does not promise that every environment can connect at every time.

Source Policy

Default realtime routing:

realtime_quotes: pytdx -> easyquotation_sina -> easyquotation_tencent
full_realtime_quotes: pytdx -> easyquotation_sina -> easyquotation_tencent
index_realtime: pytdx -> easyquotation_sina -> easyquotation_tencent

Default K-line routing:

minute_kline: pytdx only
daily_kline: pytdx only
kline: pytdx only

K-line APIs never fall back to easyquotation and never fabricate bars. Realtime APIs may fall back to easyquotation_sina or easyquotation_tencent after pytdx failures, but K-line APIs do not use easyquotation fallback.

Core Docs

• Quickstart
• Start here
• API reference
• K-line guide
• Data sources
• Issue guide
• Return fields
• CLI reference
• Troubleshooting
• Error codes
• Symbol rules
• Units
• Source policy
• Audit trail
• Time and trading day
• Upstream license and risk
• Roadmap
• Contributor adapter guide
• Maintainer checklist

Audit Trail

Each routed call receives a trace_id. Audit records include:

• api_name
• symbols
• started_at, finished_at, duration_ms
• selected_source, selected_source_level
• attempts
• fallback_chain
• success
• error_type, error_message
• record_count

See docs/AUDIT_TRAIL.md.

Risk Notice

This package does not produce market data. It calls upstream public Python libraries and their public interfaces. Upstream data may be delayed, unavailable, incomplete, or structurally changed. Users are responsible for validating data quality and following the terms of each upstream project.

License

MIT License. See LICENSE.