tickplus 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,443 @@
1
+ Metadata-Version: 2.4
2
+ Name: tickplus
3
+ Version: 0.1.0
4
+ Summary: Python SDK for the TickPlus stock market data API
5
+ Project-URL: Homepage, https://github.com/tickplusx/TickPlusSkill
6
+ Project-URL: Repository, https://github.com/tickplusx/TickPlusSkill
7
+ Project-URL: Issues, https://github.com/tickplusx/TickPlusSkill/issues
8
+ Keywords: tickplus,stock,market-data,finance,websocket
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Classifier: Programming Language :: Python :: 3.8
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Office/Business :: Financial :: Investment
20
+ Requires-Python: >=3.8
21
+ Description-Content-Type: text/markdown
22
+ Requires-Dist: requests>=2.28
23
+ Requires-Dist: websocket-client>=1.6
24
+
25
+ # DemoTickPlusPythonSkill
26
+
27
+ TickPlus 股票数据 API Python SDK - 提供沪深京A股、ETF基金、沪深可转债、指数的实时行情和历史数据查询服务,支持 REST API 和 WebSocket 实时推送。
28
+
29
+ ## 📋 项目简介
30
+
31
+ 本项目是 TickPlus 平台的 Python SDK 实现,提供了完整的 API 接口调用封装,支持获取:
32
+
33
+ - **实时行情**: A股、ETF、可转债、指数的实时报价数据
34
+ - **K线数据**: 日线、周线、月线、年线及 1m/5m/15m/30m/1h 分钟线
35
+ - **指标数据**: 行情指标(量比、换手率、市盈率等)、核心财务指标、股本数据
36
+ - **高级数据**: 逐笔交易、买卖五档、集合竞价、异动数据(涨停板股池)
37
+ - **WebSocket 实时推送**: 长连接实时数据推送,支持秒级更新
38
+
39
+ ## ✨ 主要特性
40
+
41
+ - ✅ 支持 16 个 REST API 接口,覆盖基础、专业、专家三个等级
42
+ - ✅ 支持 WebSocket 实时推送,秒级数据更新
43
+ - ✅ 完整的数据类型支持:沪深京A股、ETF基金、沪深可转债、指数
44
+ - ✅ 清晰的权限分级:基础版、高级版、专业版
45
+ - ✅ 简洁的 API 设计,易于集成和使用
46
+ - ✅ 统一的错误处理和日志输出
47
+
48
+ ## 📦 安装依赖
49
+
50
+ ```bash
51
+ pip install tickplus
52
+ ```
53
+
54
+ 也可以从源码仓库安装:
55
+
56
+ ```bash
57
+ pip install git+https://github.com/tickplusx/TickPlusSkill.git
58
+ ```
59
+
60
+ 依赖包:
61
+ - `requests`: HTTP 请求库
62
+ - `websocket-client`: WebSocket 客户端库
63
+ - `pandas`: 数据处理(可选)
64
+
65
+ ## 🚀 快速开始
66
+
67
+ ### 1. 配置 Token
68
+
69
+ 在 [TickPlus官网](http://www.tickplus.org) 注册账号并获取 token,然后修改配置文件:
70
+
71
+ ```python
72
+ # tickplus/scripts/Config.py
73
+ class Config:
74
+ SERVER_URL = "http://api.tickplus.org"
75
+ TOKEN = "your_token_here" # 替换为你的token
76
+ ```
77
+
78
+ ### 2. 基本使用
79
+
80
+ #### REST API 使用
81
+
82
+ ```python
83
+ from tickplus.scripts.api import BasicApi, ProApi, ExpertApi
84
+ from tickplus.scripts.Config import Config
85
+
86
+ token = Config.TOKEN
87
+
88
+ # 获取股票列表(stock/etf/bond/index)
89
+ stocks = BasicApi.getStockList(symbol="stock", token=token)
90
+ print(f"共 {len(stocks)} 只股票")
91
+
92
+ # 获取实时行情
93
+ quotes = BasicApi.getFullQuotes(
94
+ symbol="stock",
95
+ code="000001,000002",
96
+ token=token
97
+ )
98
+
99
+ # 获取日K线数据
100
+ from datetime import datetime, timedelta
101
+ end_date = datetime.now().strftime("%Y-%m-%d")
102
+ start_date = (datetime.now() - timedelta(days=30)).strftime("%Y-%m-%d")
103
+
104
+ kline = BasicApi.getDayKline(
105
+ symbol="stock",
106
+ code="000001",
107
+ period="1d",
108
+ dividend="1",
109
+ startDate=start_date,
110
+ endDate=end_date,
111
+ token=token
112
+ )
113
+ ```
114
+
115
+ #### WebSocket 实时推送使用
116
+
117
+ ```python
118
+ from tickplus.scripts.StockWebSocketClient import StockWebSocketClient
119
+ from tickplus.scripts.Config import Config
120
+ import time
121
+
122
+ token = Config.TOKEN
123
+ ws_url = f"ws://ws.tickplus.org/ws/{token}"
124
+
125
+ # 创建客户端实例
126
+ client = StockWebSocketClient(ws_url)
127
+
128
+ # 建立连接
129
+ if client.connect():
130
+ # 订阅数据(集合竞价 + 个股 tick + 分钟K线)
131
+ auth_codes = ["auction", "000001.SZ", "600000.SH", "minute.hsj"]
132
+ client.subscribe(token, auth_codes)
133
+
134
+ # 等待接收数据
135
+ print("Waiting for data...")
136
+ time.sleep(10)
137
+
138
+ # 取消订阅
139
+ client.unsubscribe(token, auth_codes)
140
+
141
+ # 断开连接
142
+ client.disconnect()
143
+ ```
144
+
145
+ ### 3. 运行完整测试
146
+
147
+ #### 测试 REST API
148
+
149
+ ```bash
150
+ python tickplus/scripts/StockApiClient.py
151
+ # 等价写法(在项目根目录执行)
152
+ python -m tickplus.scripts.StockApiClient
153
+ ```
154
+
155
+ 这将测试所有 16 个 REST API 接口,验证功能是否正常。
156
+
157
+ #### 测试 WebSocket 实时推送
158
+
159
+ ```bash
160
+ python tickplus/scripts/StockWebSocketClient.py
161
+ # 等价写法(在项目根目录执行)
162
+ python -m tickplus.scripts.StockWebSocketClient
163
+ ```
164
+
165
+ 这将测试 WebSocket 连接、订阅、数据接收、取消订阅等功能。
166
+
167
+ #### 从 apidoc.json 重新生成接口文档
168
+
169
+ ```bash
170
+ python tickplus/scripts/generate_apidoc.py <apidoc.json 路径> tickplus/references/apidoc.md
171
+ ```
172
+
173
+ ## 📚 API 接口分类
174
+
175
+ ### WebSocket 实时推送
176
+
177
+ | 功能 | 说明 | 权限 |
178
+ |------|------|------|
179
+ | StockWebSocketClient | WebSocket 客户端 | 按数据类型开通 |
180
+ | connect() | 建立 WebSocket 连接 | 按数据类型开通 |
181
+ | subscribe() | 订阅股票代码/数据类型 | 按数据类型开通 |
182
+ | unsubscribe() | 取消订阅 | 按数据类型开通 |
183
+ | disconnect() | 断开连接 | 按数据类型开通 |
184
+
185
+ **特点**:
186
+ - 长连接,服务器主动推送数据
187
+ - 秒级数据更新
188
+ - 支持文本和二进制(gzip/zip)数据格式
189
+ - 适用于实时性要求高的场景
190
+
191
+ **推送权限与数据类型对应**:
192
+
193
+ | authCode | 数据 | 对应接口(权限) |
194
+ |------|------|------|
195
+ | `000001.SZ` / `600000.SH` | 个股 tick | `/plus/basic/fullquotes`(1、2、3)、`/plus/expert/fivelevel`(3) |
196
+ | `auction` | 集合竞价 | `/plus/expert/fullbid`(3) |
197
+ | `minute.hsj` / `minute.index` / `minute.etf` | 1 分钟 K 线 | `/plus/pro/fullminute`(2、3) |
198
+
199
+ ### Basic Api(基础接口)- 基础版、高级版、专业版可用
200
+
201
+ | 接口 | 说明 | 权限 |
202
+ |------|------|------|
203
+ | getStockList | 获取股票列表 | 基础版+ |
204
+ | getFullQuotes | 实时行情全推 | 基础版+ |
205
+ | getDayKline | 实时日K线数据 | 基础版+ |
206
+ | getFullMetric | 行情指标全推 | 基础版+ |
207
+ | getFinanceCore | 核心财务指标 | 基础版+ |
208
+ | getCapital | 股本数据 | 基础版+ |
209
+ | getUpdateDayKline | 盘后增量数据 | 基础版+ |
210
+
211
+ ### Pro Api(专业接口)- 高级版、专业版可用
212
+
213
+ | 接口 | 说明 | 权限 |
214
+ |------|------|------|
215
+ | getTimeKline | 日内分时数据 | 高级版+ |
216
+ | getGncgf | 题材概念成分股 | 高级版+ |
217
+ | getMinuteKline | 实时分钟K线数据 | 高级版+ |
218
+ | getFullMinute | 盘中分钟K线全推 | 高级版+ |
219
+ | getFullMinuteSnapshot | 盘中分钟快照全推 | 高级版+ |
220
+
221
+ ### Expert Api(专家接口)- 专业版可用
222
+
223
+ | 接口 | 说明 | 权限 |
224
+ |------|------|------|
225
+ | getTransaction | 逐笔交易数据 | 专业版 |
226
+ | getFiveLevel | 买卖五档全推 | 专业版 |
227
+ | getFullBid | 集合竞价全推 | 专业版 |
228
+ | getFluctuation | 异动数据(涨停板股池) | 专业版 |
229
+
230
+ **权限说明**:
231
+ - **基础版 (1)**: 免费注册用户,可访问 Basic Api
232
+ - **高级版 (2)**: 付费升级用户,可访问 Basic Api + Pro Api
233
+ - **专业版 (3)**: 专业级用户,可访问所有接口
234
+ - 权限向下兼容,高级版权限包含基础版,专业版权限包含高级版
235
+
236
+ ## 📖 详细文档
237
+
238
+ - **API 接口文档**: [tickplus/references/apidoc.md](tickplus/references/apidoc.md)
239
+ - **使用技能文档**: [tickplus/SKILL.md](tickplus/SKILL.md)
240
+ - **WebSocket 详细文档**: [tickplus/references/websocket.md](tickplus/references/websocket.md)
241
+ - **GitHub 项目**: https://github.com/tickplusx/TickPlusSkill
242
+ - **在线文档**: http://www.tickplus.org
243
+
244
+ ## 💡 使用示例
245
+
246
+ ### 示例1:批量获取股票行情
247
+
248
+ ```python
249
+ # 获取多只股票的实时行情
250
+ codes = "000001,000002,600000,600519" # 平安银行、万科A、浦发银行、贵州茅台
251
+ quotes = BasicApi.getFullQuotes(symbol="stock", code=codes, token=token)
252
+
253
+ for quote in quotes:
254
+ print(f"{quote['code']}: 最新价={quote['c']}, 昨收={quote['pc']}")
255
+ ```
256
+
257
+ ### 示例2:获取行情指标
258
+
259
+ ```python
260
+ # 行情指标接口没有 symbol 参数
261
+ indicators = BasicApi.getFullMetric(code="000001", token=token)
262
+
263
+ if indicators:
264
+ data = indicators[0]
265
+ print(f"最新价: {data['zxj']}")
266
+ print(f"涨跌幅: {data['zdf']}%")
267
+ print(f"换手率: {data['hsl']}%")
268
+ print(f"市盈率(TTM): {data['ttmsyl']}")
269
+ print(f"总市值: {data['zsz']}")
270
+ ```
271
+
272
+ ### 示例3:获取板块成分股
273
+
274
+ ```python
275
+ # 获取行业板块列表(需要高级版或专业版权限)
276
+ industries = ProApi.getGncgf(symbol="hy", token=token)
277
+
278
+ for industry in industries:
279
+ print(f"板块: {industry['bkname']}")
280
+ print(f"成分股数量: {len(industry['stocks'])}")
281
+ print(f"成分股: {', '.join(industry['stocks'][:5])}...") # 显示前5只
282
+ ```
283
+
284
+ ### 示例4:获取买卖五档
285
+
286
+ ```python
287
+ # 获取买卖五档数据(需要专业版权限,symbol 必填)
288
+ five_level = ExpertApi.getFiveLevel(symbol="stock", code="000001", token=token)
289
+
290
+ if five_level:
291
+ data = five_level[0]
292
+ print("买盘:")
293
+ for i in range(1, 6):
294
+ print(f" 买{i}: {data[f'bp{i}']} x {data[f'bv{i}']}")
295
+
296
+ print("卖盘:")
297
+ for i in range(1, 6):
298
+ print(f" 卖{i}: {data[f'sp{i}']} x {data[f'sv{i}']}")
299
+ ```
300
+
301
+ ### 示例5:获取异动数据(涨停板股池)
302
+
303
+ ```python
304
+ # 需要专业版权限
305
+ fluctuation = ExpertApi.getFluctuation(tradeDate="2026-11-14", token=token)
306
+
307
+ for item in fluctuation:
308
+ print(f"{item['code']} 连续涨停 {item['days']} 天,封板资金 {item['fba']}")
309
+ ```
310
+
311
+ ### 示例6:WebSocket 实时推送
312
+
313
+ **基础用法**:
314
+
315
+ ```python
316
+ from tickplus.scripts.StockWebSocketClient import StockWebSocketClient
317
+ from tickplus.scripts.Config import Config
318
+ import time
319
+
320
+ token = Config.TOKEN
321
+ ws_url = f"ws://ws.tickplus.org/ws/{token}"
322
+
323
+ # 创建客户端实例
324
+ client = StockWebSocketClient(ws_url)
325
+
326
+ # 建立连接
327
+ if client.connect():
328
+ # 订阅集合竞价、个股 tick 和分钟K线
329
+ auth_codes = ["auction", "000001.SZ", "600000.SH", "minute.hsj"]
330
+ client.subscribe(token, auth_codes)
331
+
332
+ # 等待接收数据(服务器会主动推送)
333
+ print("Waiting for real-time data...")
334
+ time.sleep(10)
335
+
336
+ # 取消订阅
337
+ client.unsubscribe(token, auth_codes)
338
+
339
+ # 断开连接
340
+ client.disconnect()
341
+ ```
342
+
343
+ **高级用法**:
344
+
345
+ 关于 WebSocket 的更多高级功能,包括:
346
+ - 自定义消息处理
347
+ - 错误处理和自动重连
348
+ - 数据批处理和过滤
349
+ - 性能优化建议
350
+ - 常见问题解答
351
+
352
+ 请参考完整文档:[tickplus/references/websocket.md](tickplus/references/websocket.md)
353
+
354
+ **获取官方示例代码**:
355
+
356
+ ```bash
357
+ # 从 GitHub 获取最新示例
358
+ git clone https://github.com/tickplusx/TickPlusSkill.git
359
+ cd TickPlusSkill
360
+
361
+ # 运行 WebSocket 测试
362
+ python tickplus/scripts/StockWebSocketClient.py
363
+ ```
364
+
365
+ ## 🔧 项目结构
366
+
367
+ ```
368
+ DemoTickPlusPythonSkill/
369
+ ├── tickplus/
370
+ │ ├── __init__.py
371
+ │ ├── SKILL.md # 使用技能文档
372
+ │ ├── references/
373
+ │ │ ├── apidoc.md # API接口文档(由 apidoc.json 生成)
374
+ │ │ └── websocket.md # WebSocket详细文档
375
+ │ └── scripts/
376
+ │ ├── api/
377
+ │ │ ├── BasicApi.py # 基础API接口(7个)
378
+ │ │ ├── ProApi.py # 专业API接口(5个)
379
+ │ │ └── ExpertApi.py # 专家API接口(4个)
380
+ │ ├── util/
381
+ │ │ └── DataUtil.py # 请求与压缩数据解析工具
382
+ │ ├── Config.py # 配置文件
383
+ │ ├── StockApiClient.py # REST API客户端测试类
384
+ │ ├── StockWebSocketClient.py # WebSocket客户端
385
+ │ ├── CompleteExampleClient.py # WebSocket完整示例
386
+ │ ├── generate_apidoc.py # apidoc.md 生成器
387
+ │ └── __init__.py
388
+ ├── requirements.txt # 依赖包
389
+ └── README.md # 项目说明
390
+ ```
391
+
392
+ ## ⚠️ 注意事项
393
+
394
+ 1. **Token 认证**: 所有接口都需要有效的 token,请在官网注册获取
395
+ 2. **权限等级**:
396
+ - Basic Api: 基础版、高级版、专业版可用
397
+ - Pro Api: 高级版、专业版可用
398
+ - Expert Api: 仅专业版可用
399
+ - WebSocket 推送: 分钟K线推送为高级版+,五档/竞价推送为专业版
400
+ 3. **WebSocket 连接**:
401
+ - WebSocket地址:`ws://ws.tickplus.org/ws/{token}`
402
+ - 支持实时数据推送,数据更新频率为秒级
403
+ - 订阅后服务器会主动推送数据,无需轮询
404
+ - 支持文本和二进制(gzip/zip)两种数据格式
405
+ - 详细文档:[tickplus/references/websocket.md](tickplus/references/websocket.md)
406
+ - 官方示例:https://github.com/tickplusx/TickPlusSkill
407
+ 4. **批量限制**: 批量查询最多支持 100 个股票代码
408
+ 5. **单只限制**: `daykline`、`financecore`、`capital`、`timekline`、`minutekline`、`transaction` 仅支持单个股票代码
409
+ 6. **无 symbol 参数**: `fullmetric`(行情指标)与 `fullbid`(集合竞价)只接受 `code` 与 `token`
410
+ 7. **日期格式**: 统一使用 `YYYY-MM-DD` 格式
411
+ 8. **交易时间**:
412
+ - A股: 09:30-11:30, 13:00-15:00
413
+ - 集合竞价: 09:15-09:25
414
+ 9. **性能建议**:
415
+ - 避免频繁全市场数据请求
416
+ - 批量查询优于多次单次查询
417
+ - 缓存常用数据减少 API 调用
418
+ - 对于实时性要求高的场景,优先使用 WebSocket
419
+
420
+ ## 🤝 贡献指南
421
+
422
+ 欢迎提交 Issue 和 Pull Request!
423
+
424
+ ## 📄 许可证
425
+
426
+ 本项目仅供学习和研究使用。
427
+
428
+ ## 🔗 相关链接
429
+
430
+ - TickPlus 官网: http://www.tickplus.org
431
+ - API 文档: http://www.tickplus.org/doc
432
+ - GitHub 项目: https://github.com/tickplusx/TickPlusSkill
433
+ - WebSocket 文档: [tickplus/references/websocket.md](tickplus/references/websocket.md)
434
+
435
+ ## 📮 联系方式
436
+
437
+ 如有问题或建议,请通过以下方式联系:
438
+
439
+ - Email: tickplus@126.com
440
+
441
+ ---
442
+
443
+ **最后更新**: 2026-11-14