Metadata-Version: 2.4
Name: caichacha-sdk
Version: 0.2.0
Summary: 财查查基金筛选 SDK - 支持 fundFilterV2 等多种基金筛选接口
Author-email: Thinkive <dev@thinkive.com>
License: MIT
Project-URL: Homepage, https://github.com/thinkive/caichacha-sdk
Project-URL: Documentation, https://github.com/thinkive/caichacha-sdk/blob/main/README.md
Project-URL: Repository, https://github.com/thinkive/caichacha-sdk.git
Project-URL: Issues, https://github.com/thinkive/caichacha-sdk/issues
Keywords: fund,finance,sdk,caichacha,基金筛选
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

# 财查查基金筛选 SDK (caichacha-sdk)

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

财查查基金筛选 SDK 是一个用于访问基金筛选 API 的 Python 客户端库，支持 fundFilterV2 等多种基金筛选接口。

## 功能特性

- ✅ **完整的 fundFilterV2 接口支持** - 支持所有筛选条件和参数
- ✅ **类型安全** - 使用 Pydantic 进行数据验证和序列化
- ✅ **易于使用** - 简洁的 API 设计，支持上下文管理器
- ✅ **完善的错误处理** - 区分网络错误、API 错误和参数验证错误
- ✅ **Python 3.8+ 支持** - 兼容 Python 3.8 及以上版本

## 安装

```bash
pip install caichacha-sdk
```

## 快速开始

### 基础用法

```python
from caichacha_sdk import FundFilterClient
from caichacha_sdk.models import FundFilterRequest

# 创建客户端
client = FundFilterClient(base_url="http://192.168.90.209:6098")

# 构建请求
request = FundFilterRequest(
    page_num=1,
    page_size=20
)

# 调用接口
response = client.fund_filter_v2(request)

# 处理响应
if response.is_success:
    print(f"共找到 {response.data.total} 只基金")
    for fund in response.fund_list:
        print(f"{fund.fund_sname}: {fund.daily_change}%")
```

### 使用上下文管理器

```python
from caichacha_sdk import FundFilterClient
from caichacha_sdk.models import FundFilterRequest

with FundFilterClient() as client:
    request = FundFilterRequest(page_num=1, page_size=20)
    response = client.fund_filter_v2(request)
    # 自动关闭会话
```

### 复杂筛选条件

```python
from caichacha_sdk import FundFilterClient
from caichacha_sdk.models import (
    FundFilterRequest,
    FundFilterRangeV2DTO,
    FundOrderRankValueV2DTO
)

client = FundFilterClient()

# 构建复杂筛选条件
request = FundFilterRequest(
    page_num=1,
    page_size=20,
    # 基金公司
    company_code_list=["80000248", "80000249"],
    # 风险等级
    risk_level_list=["R3", "R4"],
    # 基金规模：10-100亿元
    fund_specification_list=[
        FundFilterRangeV2DTO(min_value=10, max_value=100)
    ],
    # 近一年收益率：10%-50%
    ret_list=[
        FundOrderRankValueV2DTO(code="5", min_value=10, max_value=50)
    ],
    # 最大回撤：-20%到0%
    draw_down_list=[
        FundOrderRankValueV2DTO(code="5", min_value=-20, max_value=0)
    ],
    # 排序
    sort_by="per1y",
    sort_type="DESC"
)

response = client.fund_filter_v2(request)
```

### 按基金经理筛选

```python
from caichacha_sdk import FundFilterClient
from caichacha_sdk.models import FundFilterRequest, FundFilterRangeV2DTO

client = FundFilterClient()

request = FundFilterRequest(
    page_num=1,
    page_size=10,
    # 基金经理代码
    mgr_code_list=["M001", "M002"],
    # 是否获奖
    mgr_awards_num=1,
    # 从业年限：5年以上
    mgr_employ_year_list=[
        FundFilterRangeV2DTO(min_value=5)
    ]
)

response = client.fund_filter_v2(request)
```

## API 参考

### FundFilterClient

客户端类，用于调用基金筛选接口。

#### 初始化参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `base_url` | str | `http://192.168.90.209:6098` | API 基础地址 |
| `timeout` | int | 30 | 请求超时时间（秒） |
| `headers` | dict | None | 自定义请求头 |

#### 方法

##### `fund_filter_v2(request: FundFilterRequest) -> FundFilterResponse`

基金筛选v2接口，支持多种筛选条件组合查询基金列表。

**参数：**
- `request` (FundFilterRequest): 基金筛选请求参数

**返回：**
- `FundFilterResponse`: 基金筛选响应

**异常：**
- `ValidationError`: 请求参数验证失败
- `NetworkError`: 网络请求失败
- `APIError`: API 调用失败

### FundFilterRequest

基金筛选请求参数类，与 fundFilterV2 接口的入参完全一致。

#### 基础参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `merchant_no` | str | "thinkive" | 商户编号 |
| `user_id` | str | "thinkive" | 用户编号 |
| `page_num` | int | 1 | 当前页码，从1开始 |
| `page_size` | int | 20 | 每页数量 |
| `sort_by` | str | "dailyChange" | 排序字段 |
| `sort_type` | str | "DESC" | 排序顺序：ASC/DESC |

#### 基金基本信息筛选

| 参数 | 类型 | 说明 |
|------|------|------|
| `company_code_list` | List[str] | 基金公司代码集合 |
| `fund_sub_type_list` | List[str] | 基金子类型代码列表 |
| `risk_level_list` | List[str] | 风险等级列表 |
| `apply_state_list` | List[str] | 申购状态 |
| `open_type_list` | List[str] | 开放类型 |
| `other_list` | List[str] | 其他属性 |

#### 规模与时间筛选

| 参数 | 类型 | 说明 |
|------|------|------|
| `fund_specification_list` | List[FundFilterRangeV2DTO] | 基金规模区间（亿元） |
| `establish_year_list` | List[FundFilterRangeV2DTO] | 基金成立年限区间 |
| `sub_amount_list` | List[FundFilterRangeV2DTO] | 起购金额区间 |

#### 收益率相关筛选

| 参数 | 类型 | 说明 |
|------|------|------|
| `ret_list` | List[FundOrderRankValueV2DTO] | 收益率筛选 |
| `ret_rank_list` | List[FundOrderRankValueV2DTO] | 收益排名筛选 |
| `year_ret_list` | List[FundOrderRankValueV2DTO] | 年度收益率筛选 |
| `year_rank_list` | List[FundOrderRankValueV2DTO] | 年度收益排名筛选 |
| `dsfof_ret_list` | List[FundOrderRankValueV2DTO] | 定投收益率筛选 |
| `dsfof_ret_rank_list` | List[FundOrderRankValueV2DTO] | 定投收益排名筛选 |
| `annual_ret_list` | List[FundOrderRankValueV2DTO] | 年化收益率筛选 |
| `annual_ret_rank_list` | List[FundOrderRankValueV2DTO] | 年化收益排名筛选 |
| `active_ret_list` | List[FundOrderRankValueV2DTO] | 超额收益率筛选 |
| `active_ret_rank_list` | List[FundOrderRankValueV2DTO] | 超额收益排名筛选 |

#### 风险指标筛选

| 参数 | 类型 | 说明 |
|------|------|------|
| `draw_down_list` | List[FundOrderRankValueV2DTO] | 最大回撤筛选 |
| `draw_down_rank_list` | List[FundOrderRankValueV2DTO] | 最大回撤排名筛选 |
| `stddev_list` | List[FundOrderRankValueV2DTO] | 区间波动率筛选 |
| `stddev_rank_list` | List[FundOrderRankValueV2DTO] | 区间波动率排名筛选 |
| `down_risk_list` | List[FundOrderRankValueV2DTO] | 区间下行风险筛选 |
| `down_risk_rank_list` | List[FundOrderRankValueV2DTO] | 区间下行风险排名筛选 |

#### 比率排名筛选

| 参数 | 类型 | 说明 |
|------|------|------|
| `sharperatio_rank_list` | List[FundOrderRankValueV2DTO] | 夏普比率同类排名筛选 |
| `kama_rank_list` | List[FundOrderRankValueV2DTO] | 卡玛比率同类排名筛选 |
| `info_rank_list` | List[FundOrderRankValueV2DTO] | 信息比率同类排名筛选 |

#### 持仓相关筛选

| 参数 | 类型 | 说明 |
|------|------|------|
| `industry_list` | List[FundOrderRankValueV2DTO] | 持仓行业偏好筛选 |
| `style_list` | List[FundOrderRankValueV2DTO] | 持仓风格偏好筛选 |
| `stock_list` | List[FundFilterRangeV2DTO] | 重仓集中度筛选 |
| `turnover_list` | List[FundFilterRangeV2DTO] | 换手率筛选 |
| `not_industry_code_list` | List[str] | 行业风格不持有集合 |
| `org_proportion_list` | List[FundFilterRangeV2DTO] | 机构占比筛选 |

#### 基金经理相关筛选

| 参数 | 类型 | 说明 |
|------|------|------|
| `mgr_code_list` | List[str] | 基金经理代码列表 |
| `mgr_awards_num` | int | 经理是否获奖：1-是，0-否 |
| `mgr_fund_specification_list` | List[FundFilterRangeV2DTO] | 经理管理规模筛选 |
| `mgr_employ_year_list` | List[FundFilterRangeV2DTO] | 经理从业年限筛选 |
| `mgr_fund_employ_year_list` | List[FundFilterRangeV2DTO] | 当前在管时长筛选 |
| `mgr_fund_year_ret_list` | List[FundFilterRangeV2DTO] | 经理任期年化回报筛选 |

### 数据模型

#### FundFilterRangeV2DTO

范围筛选对象，用于表示数值型范围筛选条件。

```python
from caichacha_sdk.models import FundFilterRangeV2DTO

# 基金规模：10-100亿元
range_dto = FundFilterRangeV2DTO(min_value=10, max_value=100)

# 起购金额：1000元以上
range_dto = FundFilterRangeV2DTO(min_value=1000)

# 基金规模：100亿元以下
range_dto = FundFilterRangeV2DTO(max_value=100)
```

#### FundOrderRankValueV2DTO

排序排名值对象，用于表示需要按时间区间筛选的数值条件。

```python
from caichacha_sdk.models import FundOrderRankValueV2DTO

# 近一年收益率：10%-50%
rank_value = FundOrderRankValueV2DTO(
    code="5",        # 时间区间代码：5-近一年
    min_value=10,    # 最小值：10%
    max_value=50     # 最大值：50%
)
```

**时间区间代码：**

| code | 含义 |
|------|------|
| 0 | 实时 |
| 1 | 近一周 |
| 2 | 近一个月 |
| 3 | 近三个月 |
| 4 | 近半年 |
| 5 | 近一年 |
| 6 | 近两年 |
| 7 | 近三年 |
| 8 | 近五年 |
| 9 | 近十年 |
| 10 | 成立以来 |
| 11 | 今年以来 |

### 枚举类型

SDK 提供了丰富的枚举类型，方便使用：

```python
from caichacha_sdk.models import (
    TimeRangeCode,    # 时间区间代码
    FundType,         # 基金一级分类
    FundSubType,      # 基金二级分类
    RiskLevel,        # 风险等级
    ApplyState,       # 申购状态
    OpenType,         # 开放类型
    OtherAttribute,   # 其他属性
    Currency,         # 发行币种
)

# 使用枚举
request = FundFilterRequest(
    risk_level_list=[RiskLevel.R3, RiskLevel.R4],
    apply_state_list=[ApplyState.OPEN],
    open_type_list=[OpenType.FULL]
)
```

## 错误处理

SDK 定义了以下异常类型：

| 异常 | 说明 |
|------|------|
| `CaichachaSDKError` | SDK 基础异常 |
| `APIError` | API 调用异常 |
| `ValidationError` | 参数校验异常 |
| `NetworkError` | 网络请求异常 |

```python
from caichacha_sdk import FundFilterClient
from caichacha_sdk.exceptions import APIError, NetworkError, ValidationError

client = FundFilterClient()

try:
    response = client.fund_filter_v2(request)
except ValidationError as e:
    print(f"参数错误: {e.message}")
except NetworkError as e:
    print(f"网络错误: {e.message}")
except APIError as e:
    print(f"API 错误: {e.message}, 错误码: {e.code}")
```

## 开发

### 安装开发依赖

```bash
git clone https://github.com/thinkive/caichacha-sdk.git
cd caichacha-sdk
pip install -e ".[dev]"
```

### 运行测试

```bash
pytest
```

### 代码格式化

```bash
black src/
isort src/
```

### 类型检查

```bash
mypy src/
```

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

- 邮箱: dev@thinkive.com
- 项目主页: https://github.com/thinkive/caichacha-sdk
