Metadata-Version: 2.4
Name: jcdata
Version: 0.2.0
Summary: Python client for JCDATA market data and factor APIs
Author: JiceQuant
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://jicequant.com/
Project-URL: Documentation, https://jicequant.com/
Project-URL: Repository, https://pypi.org/project/jcdata/
Keywords: finance,quant,market-data,china,a-share
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24
Requires-Dist: pandas>=1.3
Requires-Dist: pyarrow>=14
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"

# jcdata

连接 JCDATA 数据服务，详情可查看官网：[https://jicequant.com/](https://jicequant.com/)

用户注册后即可在个人中心使用一定额度的数据服务。

## 安装

```bash
pip install jcdata
```

## 配置

访问令牌任选一种方式提供：

```python
import jcdata

jcdata.login("你的访问令牌")
```

或设置环境变量后直接 `jcdata.login()`：

```bash
# Linux / macOS
export JCDATA_TOKEN="你的访问令牌"

# Windows PowerShell
$env:JCDATA_TOKEN="你的访问令牌"
```

服务地址默认为 `https://api.jicequant.com`（可在安装包内 `config.py` 的 `BASE_URL` 修改）。

## 使用

```python
import jcdata

jcdata.login("你的访问令牌")
print(jcdata.whoami())

bars = jcdata.get_market_data("600000.SH", "2025-01-01", "2025-01-31")
df = bars["600000.SH"]
```

## 主要接口

- **行情**：`get_market_data`
- **基础信息**：`get_instrument`、`get_adj_factor`
- **期货/转债**：`get_settlement`、`get_future_contract`
- **股票因子**：`get_valuation`、`get_market_value`、`get_finance`
- **其它**：`get_trade_dates`、`get_all_sectors`、`get_stock_list_by_sector`、`get_option_bars`、`get_option_info`

代码格式为 **`代码.交易所`**，如 `600000.SH`。

## 大批量日 K 流式读取

`get_market_data()` 使用 Arrow IPC + Zstandard 分批传输，并为兼容返回值聚合成完整的 `{symbol: DataFrame}`。它适合常规查询；结果量很大时仍会占用与完整结果相当的客户端内存。

百万/千万行历史数据应使用 `iter_market_data_batches()`。每次迭代只接收、解压并转换一个 TDengine 读取批次；调用方可立即写盘或计算后释放该批次：

```python
import jcdata

jcdata.login("你的访问令牌")
for symbols, frames in jcdata.iter_market_data_batches(
    ["000001.SZ", "600000.SH"],
    "2015-01-01",
    "2025-12-31",
    stream_batch_rows=65_536,
):
    for symbol, frame in frames.items():
        frame.to_parquet(f"{symbol}.parquet", index=False)
```

传输协议为 `POST /api/v1/data/query`，请求 `Accept: application/vnd.jcdata.arrow-zstd`。服务端将日K代码切为最多 60 个代码的 TDengine 分片；有效登录请求始终受理，频率超过配置时仅延迟入队，不返回 `429`/`503`。空闲时一个用户可使用全部流式连接预算；多用户竞争时按用户在分片级轮转。请求排队期间不占 TDengine 连接，客户端读超时应不低于服务端预期排队时间。服务端从 TDengine `fetchmany()` 增量读取并以独立 Arrow IPC Zstd 段发送；Arrow 流不经过 HTTP GZip。`stream_batch_rows` 仅控制单批内存窗口，不限制返回行数；`zstd_level` 默认 3，可显式传入 -7 至 22。客户端承担 Zstd 解压、pandas 转换与按 `symbol` 拆分。

`requests_per_second` 默认 1 次/秒；超过时请求继续保持连接并按用户 FIFO 延迟，而不会被拒绝。设为 0 可显式关闭频率延迟。运行 `python bin/benchmark_jcdata_server.py` 可基于 5、60、300 个代码记录未压缩 Arrow 与 Zstd 流的首字节、总耗时、解码、线上字节、批次数和 RSS 变化。

## 使用限制

- 大批量代码使用 POST body 传输，不受 GET URL 长度影响。
- 取数服务不会添加隐式 SQL `LIMIT`；仅当调用方传入 `row_limit` 时才原样下推。
- `get_market_data()` 会完整物化返回字典；大结果请使用 `iter_market_data_batches()`。
