caichacha-sdk 0.2.0

财查查基金筛选 SDK - 支持 fundFilterV2 等多种基金筛选接口

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

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

功能特性

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

安装

pip install caichacha-sdk

快速开始

基础用法

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}%")

使用上下文管理器

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)
    # 自动关闭会话

复杂筛选条件

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)

按基金经理筛选

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

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

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

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

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 提供了丰富的枚举类型，方便使用：

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	网络请求异常

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}")

开发

安装开发依赖

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

运行测试

pytest

代码格式化

black src/
isort src/

类型检查

mypy src/

许可证

MIT License - 详见 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

• 邮箱: [e-mail]
• 项目主页: https://github.com/thinkive/caichacha-sdk