Metadata-Version: 2.5
Name: finctx
Version: 0.3.7
Summary: Finctx SDK for the Finctx Data API
Project-URL: Homepage, https://finctx.cn
Author: Finctx
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: certifi>=2026.10.19
Requires-Dist: requests<3,>=2.33.0
Requires-Dist: urllib3<3,>=2.8.0
Requires-Dist: websocket-client<1.9,>=1.8
Provides-Extra: arrow
Requires-Dist: pyarrow>=14.0.1; extra == 'arrow'
Provides-Extra: marketdb
Requires-Dist: duckdb<1.6,>=1.4.2; extra == 'marketdb'
Provides-Extra: test
Requires-Dist: duckdb<1.6,>=1.4.2; extra == 'test'
Requires-Dist: pyarrow>=14.0.1; extra == 'test'
Requires-Dist: pytest<10,>=8; extra == 'test'
Description-Content-Type: text/markdown

# Finctx Python SDK

在 Python 中查询股票、基金、财务和宏观数据，读取主题跟踪资讯，或订阅实时快讯。

## 1. 安装

需要 Python 3.10 或更高版本。本轮安全更新提高了运行环境要求；使用 Python 3.9 的项目需先升级 Python。

安装下载的 SDK 包：

```bash
python -m pip install ./finctx-0.3.3-py3-none-any.whl
```

也可以直接安装源码包：

```bash
python -m pip install ./finctx-0.3.3.tar.gz
```

需要处理 Arrow 数据或使用本地数据库时，再安装相应扩展：

```bash
python -m pip install "finctx[arrow]==0.3.7"     # Arrow 数据转换
python -m pip install "finctx[marketdb]==0.3.7"  # 本地数据库
```

## 2. 配置 API Key

在 [Finctx 网站](https://finctx.cn)创建 API Key，然后在运行 Python 的环境中设置：

```bash
export FINCTX_API_KEY="<你的 API Key>"
```

Windows PowerShell 使用 `$env:FINCTX_API_KEY = "<你的 API Key>"`。不要将真实 Key 写入代码或提交到 Git。

也可以将 `FINCTX_API_KEY=<你的 API Key>` 保存到 `~/.finctx/credentials.env`，并将文件权限设为仅当前用户可读写（Linux／macOS 使用 `chmod 600 ~/.finctx/credentials.env`）。SDK 按“传入的 `api_key` → 环境变量 → 用户凭据文件”的顺序读取 Key，不会自动加载项目的 `.env`。

## 3. 第一次查询

下面查询证券简称，并把结果提取为 Python 字典列表：

```python
from finctx import FinctxClient

with FinctxClient() as client:
    result = client.get_s_stockname(code=["600745.SH"])
    rows = client.rows(result)
    print(rows)
```

接口调用需要相应权限，并按账号的额度和计费规则使用。`rows()` 只提取 `data` 数组中的业务记录；不会把错误、单对象或旧 `data_frame` 当成空列表。原始响应及分页信息仍保留在 `result` 中。

## 查找接口和参数

这些查询在本地执行，无需 API Key：

```python
from finctx import FinctxClient

print(FinctxClient.endpoints()["daily"]["parameters"])
print(FinctxClient.fields("daily", search="收盘"))
help(FinctxClient.daily)
```

`endpoints()` 列出可调用的接口及其参数，`fields()` 查找返回字段，`help()` 查看方法签名。调用业务方法时使用关键字参数；具体返回内容取决于所选接口。

## 处理 Arrow 数据

安装 `arrow` 扩展后，可以把 Arrow 结果转换成表格：

```python
from finctx import FinctxClient

with FinctxClient() as client:
    raw = client.arrow(
        handler="get_s_stockname",
        params={"code": ["600745.SH"]},
        fields=["code", "sename"],
    )
    table = client.arrow_to_table(raw)
    print(table.to_pylist())
```

Arrow 接口返回原始 bytes，转换由调用方显式执行。

## 读取主题跟踪资讯

读取关注范围的内容、搜索资讯，或查看关注的主题：

```python
from finctx import FinctxClient

with FinctxClient() as client:
    feed = client.get_tracer_feed(limit=20)
    print(feed["data"])

    page = client.search_tracer_content(q="美债", scope="global", limit=20)
    print(page["data"])

    public_topics = client.list_tracer_public_topics()
    print(public_topics["data"])  # id、名称、描述、关注状态和主题状态

    topics = client.list_tracer_topics()
    print(topics)
```

Feed、搜索、研报和纪要列表位于 `data` 数组，可直接读取或显式使用 `rows()`；默认每页 1000 条，最多 1000 条。省略 `limit` 仍分页，由服务端使用默认值；SDK 不补参数。响应始终带 `meta.pagination`，续页原样传回 `next_cursor` 并保持筛选与有效每页条数，JSON null 表示当前查询已无后续页。游标记录当前位置 offset，排序保持不变；分页期间数据变化可能重复或遗漏，不因此返回 40008。40008 仅在游标过期或版本不受支持等情况下要求重新开始。SDK 不自动翻页或重试。

快讯同步返回 `data.items`、`data.snapshot_revision` 和 `data.sync`；它是业务 TopN 位置续取，`data.sync.has_more=false` 后仍保留位置供下一次拉新。无新数据不等于游标应清空。社媒列表同样返回 `data` 中的快照对象，不能使用普通列表转换。

资料和来源编号按字符串返回，请直接传回详情方法，避免转为浮点数或 JavaScript Number。HTTP 错误保留整数 `error_code`、`message`、可选 `details` 和 `X-Request-ID`，不再读取旧错误字符串或旧追踪头。

主题创建使用 `create_tracer_topic(query=...)`；关注和取消关注使用 `follow_tracer_topic(id=...)`、`unfollow_tracer_topic(id=...)`，主题 ID 从 `list_tracer_public_topics()` 返回的真实 `id` 取得；该列表无需先关注。普通关键词搜索使用 `scope="global"`，无需关注；`scope="following"` 只搜索自己的关注范围。创建回执表示任务已受理，不代表内容已生成完成。

## 订阅实时快讯

```python
from finctx import FinctxClient

with FinctxClient() as client:
    with client.ws_newsflash(limit=10) as stream:
        print(stream.receive_json())
```

SDK 不自动重连。持续订阅时，由应用保存已处理消息的游标并处理断线。主题跟踪的 SSE 推送需使用支持流式读取的 HTTP 客户端，SDK 的 `request()` 不支持持续读取 SSE。

## 使用本地数据库

安装 `marketdb` 扩展后，可以将数据保存到本地 DuckDB 文件，并用 SQL 查询：

```python
from finctx.marketdb import DATASETS, MarketDB

db = MarketDB()
db.init()
print(sorted(DATASETS))  # 查看支持同步的数据集
print(db.status())      # 查看本地数据和同步记录
```

通过 `db.sync(数据集名称, **查询参数)` 下载数据，`db.sql(SQL)` 执行只读查询，`db.export(表名, 文件路径)` 导出 CSV 或 Parquet。

同步后检查返回的 `status`：`complete` 表示本次查询范围已完整写入，`incomplete` 表示未确认完整，不写入数据。14 个金融预设不传 `limit` 或传 `None` 时按各接口契约接收一次全量结果，不自动补参；显式 `limit` 时，只有 `sync` 按 `meta.pagination.next_cursor` 继续，直到明确为 `None`。Arrow 从 schema metadata 的 `meta` 读取同一分页状态，Decimal 保留为精确字符串。缺失结束状态不当作末页，跨页失败不自动重试或写入部分数据。普通 SDK 调用仍不自动翻页。单次同步沿用 100,000 行或约 64 MiB 缓冲上限；超限时缩小查询范围。`validate()` 检查本地数据库，不验证源数据覆盖或历史时点质量。

## 调整地址和超时

通常只需配置 API Key。需要覆盖默认设置时使用：

| 设置 | 默认值 | 配置方式 |
| --- | --- | --- |
| HTTP 服务地址 | `https://api.finctx.cn` | `base_url=` 或 `FINCTX_BASE_URL` |
| HTTP 超时 | 30 秒 | `timeout=` |
| WebSocket 服务地址 | `wss://ws.finctx.cn` | `websocket_base_url=` |
| WebSocket 超时 | 30 秒 | `websocket_timeout=` |
| 本地数据库路径 | `~/.finctx/data/marketdb.duckdb` | `MarketDB(path=...)` 或 `FINCTX_DB` |

显式参数优先于环境变量。服务地址需包含协议，如 `https://api.example.com`，可带端口，不附带接口路径、查询参数或片段；HTTP 地址设置不会同时修改 WebSocket 地址。

## 处理错误

```python
from finctx import FinctxApiError, FinctxClient, FinctxTransportError

try:
    with FinctxClient() as client:
        result = client.get_s_stockname(code=["600745.SH"])
except FinctxApiError as error:
    print(error.status_code, error.error_code, error.request_id)
except FinctxTransportError as error:
    print(error.cause)
```

`FinctxApiError` 提供 HTTP 状态、服务端错误码、请求编号和原始响应；`FinctxTransportError` 提供网络错误原因。响应无法解析为 JSON 时抛出 `FinctxResponseError`，表格结果格式不符时抛出 `FinctxResultError`。根据具体错误处理，SDK 默认不自动重试。

## 从旧版升级

0.3.0 的安装包与导入名统一为 `finctx`，客户端为 `FinctxClient`，异常类使用 `Finctx` 前缀。升级时更新导入、异常捕获和环境变量；新版不自动读取旧配置或旧用户目录。已有数据库可通过 `FINCTX_DB` 或 `MarketDB(path=...)` 继续打开。

许可证：[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)。
