jcdata 0.2.0__tar.gz → 0.2.1__tar.gz

jcdata-0.2.1/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: jcdata
+Version: 0.2.1
+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` 是 JCDATA 的 Python 客户端，用于获取市场数据、证券基础信息、因子、财务、ETF、期权、利率和宏观数据
+
+## 安装
+
+```bash
+pip install jcdata
+```
+
+## 认证
+
+使用访问令牌登录。请将令牌保存在环境变量或密钥管理系统中，禁止写入源码、笔记本、日志或版本控制系统。
+
+```python
+import jcdata
+
+login_info = jcdata.login("YOUR_TOKEN")
+if not login_info.get("user_name"):
+    raise PermissionError("令牌无效、已过期或无访问权限")
+
+print(login_info["user_name"])
+print(login_info["cell_quota_remaining"])
+```
+
+也可使用环境变量：
+
+```bash
+# Linux / macOS
+export JCDATA_TOKEN="YOUR_TOKEN"
+```
+
+```powershell
+# Windows PowerShell
+$env:JCDATA_TOKEN = "YOUR_TOKEN"
+```
+
+```python
+jcdata.login()
+```
+
+令牌查找顺序为：`login(token=...)` 参数、`JCDATA_TOKEN` 环境变量、客户端配置。`login()` 返回用户名、接口使用量和剩余配额；认证未通过时这些字段为 `None`。
+
+## 基本使用
+
+```python
+import jcdata
+
+jcdata.login()
+
+bars = jcdata.get_market_data(
+    "600000.SH",
+    "2025-01-02",
+    "2025-01-10",
+    fields=["date", "open", "high", "low", "close", "volume"],
+)
+frame = bars["600000.SH"]
+
+if not frame.empty:
+    print(frame.tail())
+```
+
+多数按证券代码查询的接口返回 `dict[str, pandas.DataFrame]`：字典 key 为请求代码，DataFrame 中不依赖 `symbol` 列分组。没有匹配数据时也会保留对应的空 DataFrame，因此请显式处理 `frame.empty`。
+
+日期参数支持 `YYYY-MM-DD` 或 `YYYYMMDD`，例如 `2025-01-02` 或 `20250102`。
+
+## 常用接口
+
+| 分类 | 接口 |
+|---|---|
+| 日 K | `get_market_data`、`iter_market_data`、`iter_market_data_batches` |
+| 基础信息 | `get_instrument`、`get_adj_factor`、`get_settlement`、`get_future_contract` |
+| 股票扩展 | `get_factors`、`get_valuation`、`get_market_value`、`get_finance`、`get_money_flow`、`get_margin`、`get_leader_board` |
+| 期权 | `get_option_bars`、`get_option_greeks` |
+| ETF | `get_etf_share`、`get_etf_tracking` |
+| 日历与板块 | `get_trade_dates`、`get_all_sectors`、`get_stock_list_by_sector` |
+| 利率与宏观 | `get_interest_rate`、`get_government_yield`、`get_macro_indicators` |
+
+## 批量行情
+
+直接传入代码列表即可查询多标的行情：
+
+```python
+symbols = ["600000.SH", "000001.SZ", "510300.SH"]
+bars = jcdata.get_market_data(symbols, "2025-01-02", "2025-01-10", fields=["date", "close"])
+
+for symbol, frame in bars.items():
+    print(symbol, len(frame))
+```
+
+混合查询不同资产时，各 DataFrame 只返回该资产适用的字段。请按单个 DataFrame 的实际列名处理，不要假设所有资产具有相同字段。
+
+```python
+mixed = jcdata.get_market_data(["600000.SH", "IF2501.CFE"], "2025-01-02", "2025-01-10")
+print(mixed["600000.SH"].columns.tolist())
+print(mixed["IF2501.CFE"].columns.tolist())
+```
+
+## 复权
+
+`get_market_data()` 支持股票、ETF 和可转债复权：
+
+```python
+adjusted = jcdata.get_market_data(
+    "600000.SH",
+    "2024-01-01",
+    "2025-01-31",
+    dividend_type="front",
+    fields=["date", "close"],
+)
+```
+
+可用 `dividend_type`：`none`、`front`、`back`、`point`。使用 `point` 时必须同时传 `adjust_date`。指数不参与复权。
+
+## 大数据读取
+
+代码数量较多但希望按代码处理时，使用 `iter_market_data()`：
+
+```python
+for chunk_symbols, frames in jcdata.iter_market_data(
+    symbols,
+    "2020-01-01",
+    "2025-01-01",
+    chunk_size=60,
+    fields=["date", "close", "volume"],
+):
+    for symbol in chunk_symbols:
+        process(frames[symbol])
+```
+
+超长历史数据使用 `iter_market_data_batches()`，并在循环内及时处理结果：
+
+```python
+for present_symbols, frames in jcdata.iter_market_data_batches(
+    symbols,
+    "2015-01-01",
+    "2025-01-01",
+    fields=["date", "close"],
+    stream_batch_rows=65_536,
+):
+    for symbol in present_symbols:
+        frames[symbol].to_parquet(f"{symbol}.parquet", index=False)
+```
+
+同一代码可能跨多个批次出现。请不要将全部批次累积到内存中。
+
+## 错误处理
+
+```python
+try:
+    jcdata.login()
+    bars = jcdata.get_market_data("600000.SH", "2025-01-02", "2025-01-10")
+except jcdata.CellQuotaExceededError as exc:
+    print("配额已用尽，剩余：", exc.cell_quota_remaining)
+except jcdata.InvalidParameterError as exc:
+    print("参数错误：", exc.param, exc.value)
+except PermissionError as exc:
+    print("认证或授权失败：", exc)
+```
+
+`CellQuotaExceededError` 是 `PermissionError` 的子类，因此应优先捕获。参数问题会引发 `InvalidParameterError`，可通过 `.param` 和 `.value` 定位。对于无效代码或正常无数据区间，按代码查询接口一般返回空 DataFrame，而非异常。
+
+## 更多说明
+
+- 代码格式通常为 `代码.市场后缀`，例如 `600000.SH`、`000001.SZ`、`IF2501.CFE`。
+- 使用 `get_asset_type_by_symbol()` 可识别常见代码的资产类型。
+- 使用 `fields` 限定实际需要的列，可减少传输量和处理成本。
+- 有访问频率或配额限制时，请避免无上限并发和紧密重试；应控制并发、缩小查询范围并保存任务进度。

jcdata-0.2.1/README.md

@@ -0,0 +1,168 @@
+# jcdata
+
+`jcdata` 是 JCDATA 的 Python 客户端，用于获取市场数据、证券基础信息、因子、财务、ETF、期权、利率和宏观数据
+
+## 安装
+
+```bash
+pip install jcdata
+```
+
+## 认证
+
+使用访问令牌登录。请将令牌保存在环境变量或密钥管理系统中，禁止写入源码、笔记本、日志或版本控制系统。
+
+```python
+import jcdata
+
+login_info = jcdata.login("YOUR_TOKEN")
+if not login_info.get("user_name"):
+    raise PermissionError("令牌无效、已过期或无访问权限")
+
+print(login_info["user_name"])
+print(login_info["cell_quota_remaining"])
+```
+
+也可使用环境变量：
+
+```bash
+# Linux / macOS
+export JCDATA_TOKEN="YOUR_TOKEN"
+```
+
+```powershell
+# Windows PowerShell
+$env:JCDATA_TOKEN = "YOUR_TOKEN"
+```
+
+```python
+jcdata.login()
+```
+
+令牌查找顺序为：`login(token=...)` 参数、`JCDATA_TOKEN` 环境变量、客户端配置。`login()` 返回用户名、接口使用量和剩余配额；认证未通过时这些字段为 `None`。
+
+## 基本使用
+
+```python
+import jcdata
+
+jcdata.login()
+
+bars = jcdata.get_market_data(
+    "600000.SH",
+    "2025-01-02",
+    "2025-01-10",
+    fields=["date", "open", "high", "low", "close", "volume"],
+)
+frame = bars["600000.SH"]
+
+if not frame.empty:
+    print(frame.tail())
+```
+
+多数按证券代码查询的接口返回 `dict[str, pandas.DataFrame]`：字典 key 为请求代码，DataFrame 中不依赖 `symbol` 列分组。没有匹配数据时也会保留对应的空 DataFrame，因此请显式处理 `frame.empty`。
+
+日期参数支持 `YYYY-MM-DD` 或 `YYYYMMDD`，例如 `2025-01-02` 或 `20250102`。
+
+## 常用接口
+
+| 分类 | 接口 |
+|---|---|
+| 日 K | `get_market_data`、`iter_market_data`、`iter_market_data_batches` |
+| 基础信息 | `get_instrument`、`get_adj_factor`、`get_settlement`、`get_future_contract` |
+| 股票扩展 | `get_factors`、`get_valuation`、`get_market_value`、`get_finance`、`get_money_flow`、`get_margin`、`get_leader_board` |
+| 期权 | `get_option_bars`、`get_option_greeks` |
+| ETF | `get_etf_share`、`get_etf_tracking` |
+| 日历与板块 | `get_trade_dates`、`get_all_sectors`、`get_stock_list_by_sector` |
+| 利率与宏观 | `get_interest_rate`、`get_government_yield`、`get_macro_indicators` |
+
+## 批量行情
+
+直接传入代码列表即可查询多标的行情：
+
+```python
+symbols = ["600000.SH", "000001.SZ", "510300.SH"]
+bars = jcdata.get_market_data(symbols, "2025-01-02", "2025-01-10", fields=["date", "close"])
+
+for symbol, frame in bars.items():
+    print(symbol, len(frame))
+```
+
+混合查询不同资产时，各 DataFrame 只返回该资产适用的字段。请按单个 DataFrame 的实际列名处理，不要假设所有资产具有相同字段。
+
+```python
+mixed = jcdata.get_market_data(["600000.SH", "IF2501.CFE"], "2025-01-02", "2025-01-10")
+print(mixed["600000.SH"].columns.tolist())
+print(mixed["IF2501.CFE"].columns.tolist())
+```
+
+## 复权
+
+`get_market_data()` 支持股票、ETF 和可转债复权：
+
+```python
+adjusted = jcdata.get_market_data(
+    "600000.SH",
+    "2024-01-01",
+    "2025-01-31",
+    dividend_type="front",
+    fields=["date", "close"],
+)
+```
+
+可用 `dividend_type`：`none`、`front`、`back`、`point`。使用 `point` 时必须同时传 `adjust_date`。指数不参与复权。
+
+## 大数据读取
+
+代码数量较多但希望按代码处理时，使用 `iter_market_data()`：
+
+```python
+for chunk_symbols, frames in jcdata.iter_market_data(
+    symbols,
+    "2020-01-01",
+    "2025-01-01",
+    chunk_size=60,
+    fields=["date", "close", "volume"],
+):
+    for symbol in chunk_symbols:
+        process(frames[symbol])
+```
+
+超长历史数据使用 `iter_market_data_batches()`，并在循环内及时处理结果：
+
+```python
+for present_symbols, frames in jcdata.iter_market_data_batches(
+    symbols,
+    "2015-01-01",
+    "2025-01-01",
+    fields=["date", "close"],
+    stream_batch_rows=65_536,
+):
+    for symbol in present_symbols:
+        frames[symbol].to_parquet(f"{symbol}.parquet", index=False)
+```
+
+同一代码可能跨多个批次出现。请不要将全部批次累积到内存中。
+
+## 错误处理
+
+```python
+try:
+    jcdata.login()
+    bars = jcdata.get_market_data("600000.SH", "2025-01-02", "2025-01-10")
+except jcdata.CellQuotaExceededError as exc:
+    print("配额已用尽，剩余：", exc.cell_quota_remaining)
+except jcdata.InvalidParameterError as exc:
+    print("参数错误：", exc.param, exc.value)
+except PermissionError as exc:
+    print("认证或授权失败：", exc)
+```
+
+`CellQuotaExceededError` 是 `PermissionError` 的子类，因此应优先捕获。参数问题会引发 `InvalidParameterError`，可通过 `.param` 和 `.value` 定位。对于无效代码或正常无数据区间，按代码查询接口一般返回空 DataFrame，而非异常。
+
+## 更多说明
+
+- 代码格式通常为 `代码.市场后缀`，例如 `600000.SH`、`000001.SZ`、`IF2501.CFE`。
+- 使用 `get_asset_type_by_symbol()` 可识别常见代码的资产类型。
+- 使用 `fields` 限定实际需要的列，可减少传输量和处理成本。
+- 有访问频率或配额限制时，请避免无上限并发和紧密重试；应控制并发、缩小查询范围并保存任务进度。

{jcdata-0.2.0 → jcdata-0.2.1}/__init__.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 """
-JCDATA 客户端：连接数据服务后取历史行情与因子数据。
+JCDATA Python 客户端：用于查询市场数据和相关数据集。
 
 使用前调用 ``jcdata.login("...")``（或设置环境变量 ``JCDATA_TOKEN``）::
 
@@ -15,10 +15,13 @@ from ._http import current_user, login, whoami
 from .errors import CellQuotaExceededError, ErrorCode, InvalidParameterError, RowQuotaExceededError
 from .data import (
     get_adj_factor,
+    get_asset_type_by_symbol,
     get_etf_share,
     get_etf_tracking,
     get_finance,
+    get_factors,
     get_future_contract,
+    get_government_yield,
     get_instrument,
     get_interest_rate,
     get_leader_board,
@@ -27,9 +30,10 @@ from .data import (
     iter_market_data,
     iter_market_data_batches,
     get_market_value,
+    get_macro_indicators,
     get_money_flow,
     get_option_bars,
-    get_option_info,
+    get_option_greeks,
     get_settlement,
     get_all_sectors,
     get_stock_list_by_sector,
@@ -37,7 +41,7 @@ from .data import (
     get_valuation,
 )
 
-__version__ = "0.1.6"
+__version__ = "0.2.1"
 
 __all__ = [
     "__version__",
@@ -49,6 +53,7 @@ __all__ = [
     "InvalidParameterError",
     "RowQuotaExceededError",
     "get_market_data",
+    "get_asset_type_by_symbol",
     "iter_market_data",
     "iter_market_data_batches",
     "get_instrument",
@@ -57,12 +62,15 @@ __all__ = [
     "get_future_contract",
     "get_valuation",
     "get_market_value",
+    "get_government_yield",
+    "get_macro_indicators",
     "get_finance",
+    "get_factors",
     "get_trade_dates",
     "get_all_sectors",
     "get_stock_list_by_sector",
     "get_option_bars",
-    "get_option_info",
+    "get_option_greeks",
     "get_money_flow",
     "get_margin",
     "get_leader_board",

{jcdata-0.2.0 → jcdata-0.2.1}/_http.py

@@ -77,24 +77,28 @@ def _resolve_timeout(timeout_sec: float | None) -> float:
     return timeout_sec if timeout_sec is not None else config.TIMEOUT_SEC
 
 
+def _login_result(body: dict[str, Any] | None = None) -> dict[str, Any]:
+    """构造 login 的稳定返回结构。"""
+    body = body or {}
+    return {
+        "user_name": body.get("user_name"),
+        "api_usage_week": body.get("api_usage_week"),
+        "api_usage_month": body.get("api_usage_month"),
+        "cell_quota_remaining": body.get("cell_quota_remaining"),
+    }
+
+
 def login(
     token: str | None = None,
     *,
     port: int | None = None,
     timeout_sec: float | None = None,
-) -> None:
+) -> dict[str, Any]:
     """
-    连接数据服务并校验访问令牌。
-
-    参数:
-        token: 访问令牌，优先级：参数 > 环境变量 JCDATA_TOKEN > config.TOKEN
-        port: API 服务端口，优先级：参数 > 环境变量 JCDATA_PORT > config.PORT
-        timeout_sec: 请求超时时间（秒），默认使用 config.TIMEOUT_SEC
+    连接数据服务并校验访问令牌，返回当前用户和数据用量信息。
 
-    服务地址读取 config.BASE_URL；修改请编辑 jcdata/config.py。
-
-    示例:
-        >>> jcdata.login("your_token")
+    返回值固定含有 ``user_name``、``api_usage_week``、``api_usage_month``、
+    ``cell_quota_remaining`` 四个键。令牌未通过认证时，各值均为 ``None``。
     """
     global _client, _user_name, _authenticated
 
@@ -102,21 +106,27 @@ def login(
     key = _resolve_token(token)
     resolved_port = _resolve_port(port)
     to = _resolve_timeout(timeout_sec)
-
-    headers = {
-        "Authorization": f"Bearer {key}",
-        "X-Api-Key": key,
-    }
+    headers = {"Authorization": f"Bearer {key}", "X-Api-Key": key}
 
     if _client is not None:
         _client.close()
 
     final_url = _build_base_url(url, resolved_port)
     _client = httpx.Client(base_url=final_url, timeout=to, headers=headers)
-
-    _user_name, _authenticated = _whoami_request()
-    if not _authenticated:
-        raise PermissionError("令牌校验未通过，请检查访问令牌")
+    response = _client.get("/api/v1/auth/whoami")
+    if response.status_code in (401, 403):
+        _user_name = None
+        _authenticated = False
+        return _login_result()
+    response.raise_for_status()
+    body = response.json()
+    if not isinstance(body, dict) or not body.get("user_name"):
+        _user_name = None
+        _authenticated = False
+        return _login_result()
+    _user_name = str(body["user_name"])
+    _authenticated = True
+    return _login_result(body)
 
 
 def whoami() -> str | None:
@@ -141,7 +151,8 @@ def _whoami_request() -> tuple[str | None, bool]:
         raise PermissionError("令牌无效或已过期")
     r.raise_for_status()
     body = r.json()
-    return body.get("user_name"), bool(body.get("authenticated"))
+    user_name = body.get("user_name")
+    return user_name, bool(user_name)
 
 
 def _client_or_raise() -> httpx.Client:
@@ -177,9 +188,14 @@ def _raise_for_detail(status_code: int, detail: dict | str | None) -> None:
                 param=detail.get("param"),
                 value=detail.get("value"),
             )
-    if status_code == 400:
+    if status_code in (400, 422):
         if isinstance(detail, dict):
-            raise InvalidParameterError(str(detail.get("message") or "请求参数不合法"))
+            raise InvalidParameterError(
+                str(detail.get("message") or "请求参数不合法"),
+                code=str(detail.get("code") or ErrorCode.INVALID_PARAMETER),
+                param=detail.get("param"),
+                value=detail.get("value"),
+            )
         raise InvalidParameterError(str(detail) if detail else "请求参数不合法")
     if status_code == 401:
         raise PermissionError("未授权，请先 jcdata.login()")
@@ -208,7 +224,7 @@ def _retry_after_seconds(r: httpx.Response, detail: dict | str | None) -> float:
 
 def _raise_http_error(r: httpx.Response) -> None:
     detail = _parse_error_detail(r)
-    if r.status_code in (400, 401, 403, 429):
+    if r.status_code in (400, 401, 403, 422, 429):
         _raise_for_detail(r.status_code, detail)
     r.raise_for_status()
 
@@ -368,7 +384,7 @@ def _post_query(
 
 
 def iter_stream_bars(params: dict[str, Any]) -> Iterator[dict[str, pd.DataFrame]]:
-    """以 HTTP 流逐段读取 Zstd Arrow 日 K，不缓冲完整响应体。"""
+    """逐批读取日 K 数据，不缓冲完整响应体。"""
     from ._arrow import ARROW_ZSTD_MEDIA_TYPE, iter_zstd_arrow_by_symbol
 
     client = _client_or_raise()

jcdata-0.2.1/config.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""jcdata 客户端默认配置。
+
+生产环境请通过环境变量或 ``jcdata.login(token=...)`` 提供访问令牌。
+不要将访问令牌写入源码、配置文件或版本控制系统。
+"""
+
+from __future__ import annotations
+
+# 服务地址。一般无需修改；私有部署可按本单位要求覆盖。
+BASE_URL = "https://api.jicequant.com"
+PORT = None
+
+# 单次请求超时（秒）。
+TIMEOUT_SEC = 3600.0
+
+# 不在发行包中保存令牌。此变量仅保留配置兼容性；优先使用
+# login(token=...) 或环境变量 JCDATA_TOKEN。
+TOKEN = ""
+
+# 多代码查询的客户端行为配置。
+USE_POST_BULK = True
+POST_MIN_SYMBOLS = 2