Metadata-Version: 2.1
Name: ffd-sdk
Version: 0.2.0
Summary: FinFlow Data (FFD) Python SDK - 金融数据统一接口
Home-page: https://ffd.findesk.cn
Author: FinFlow Data
Author-email: FinFlow Data <support@findesk.cn>
License: MIT
Project-URL: Homepage, https://ffd.findesk.cn
Project-URL: Documentation, https://ffd.findesk.cn/docs
Keywords: finance,stock,quant,data,A-share,market-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas >=1.0.0
Requires-Dist: requests >=2.20.0

# FFD Python SDK

FinFlow Data 金融数据接口 Python SDK，提供 A 股日线、分钟线、实时行情、基本面、宏观经济等数据。

## 安装

```bash
pip install ffd-sdk
```

## 快速开始

```python
from ffd_sdk import FFDClient

# 初始化（API Key 在 https://ffd.findesk.cn 面板获取）
client = FFDClient("你的API_KEY")

# 查询账户
info = client.account()
print(f"套餐: {info['plan_name']}, 余额: {info['balance']} 数据点")

# 日线数据
df = client.daily("600519.SH", "close,open,high,low,volume", "2026-01-01", "2026-04-01")
print(df)
```

## 数据查询

所有查询函数默认返回 `pandas.DataFrame`，传 `as_df=False` 返回原始 dict。

### 日线数据

```python
df = client.daily(
    codes="600519.SH,000858.SZ",
    indicators="close,open,high,low,volume",
    start_date="2026-01-01",
    end_date="2026-04-01",
)
```

### 基本面截面

```python
df = client.basic(
    codes="600519.SH,000858.SZ",
    indicators="pe_ttm,pb,roe",
    date="2026-04-01",
)
```

### 实时行情

```python
df = client.realtime("600519.SH", "latest,open,high,low,volume,amount")
```

### 分钟行情

```python
df = client.minute("600519.SH", "close,volume", "2026-04-01", "2026-04-11")
```

### 宏观经济数据

```python
df = client.macro("M001620305", "2024-01-01", "2026-04-01")
```

### 条件选股

```python
df = client.screen("市盈率<20且营收增速>30%")
```

### 专题报表

```python
df = client.report(report_id="报表ID", params="参数")
```

### 公告查询

```python
df = client.announcement(codes="600519.SH", params="参数")
```

### 特色数据

```python
df = client.special(data_type="类型", keyword="关键词")
```

### 交易日历

```python
result = client.trade_dates("SSE", "2026-01-01", "2026-12-31")
```

### 日期偏移

```python
result = client.date_offset("SSE", "2026-04-15")
```

### 额度查询

```python
result = client.quota()
```

## 通用查询

高级用户可直接使用底层 `query()` 方法传入任意参数：

```python
resp = client.query("daily_series",
    codes="600519.SH",
    indicators="close",
    start_date="2026-01-01",
    end_date="2026-04-01",
)
```

## 错误处理

```python
from ffd_sdk import FFDClient, FFDError

client = FFDClient("你的API_KEY")

try:
    df = client.daily("600519.SH", "close", "2026-01-01", "2026-04-01")
except FFDError as e:
    if e.code == 401:
        print("API Key 无效")
    elif e.code == 402:
        print("余额不足，请充值")
    elif e.code == 503:
        print("服务暂不可用，稍后重试")
    else:
        print(f"错误: {e}")
```

## 多通道支持

FFD 支持多个数据通道，通道由 API Key 绑定。切换通道只需更换 Key，代码完全不变：

```python
# 智选F版
client_f = FFDClient("F版的API_KEY")
df = client_f.daily("600519.SH", "close", "2026-01-01", "2026-04-01")

# 旗舰W版
client_w = FFDClient("W版的API_KEY")
df = client_w.daily("600519.SH", "close", "2026-01-01", "2026-04-01")
```

## 获取 API Key

1. 访问 [https://ffd.findesk.cn](https://ffd.findesk.cn)
2. 注册/登录后进入控制面板
3. 在「API Key 管理」中创建 Key
4. 选择数据通道并复制 Key

## 系统要求

- Python >= 3.8
- 依赖: requests, pandas
