fund-cli 2.0.0__py3-none-any.whl

fund_cli/data/models.py

@@ -0,0 +1,248 @@
+"""
+数据模型定义
+
+使用 Pydantic 定义基金相关的数据模型。
+"""
+
+from datetime import date, datetime
+from enum import Enum as PyEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class FundType(str, PyEnum):
+    """基金类型枚举"""
+
+    EQUITY = "股票型"
+    BOND = "债券型"
+    MIXED = "混合型"
+    INDEX = "指数型"
+    QDII = "QDII"
+    MONEY = "货币型"
+    ETF = "ETF"
+    LOF = "LOF"
+    OTHER = "其他"
+
+
+class FundInfo(BaseModel):
+    """
+    基金基础信息模型
+
+    包含基金的基本属性信息。
+    """
+
+    model_config = ConfigDict(
+        str_strip_whitespace=True,
+        validate_assignment=True,
+    )
+
+    # 基本信息
+    code: str = Field(..., min_length=6, max_length=6, description="基金代码")
+    name: str = Field(..., min_length=1, description="基金名称")
+    type: FundType = Field(..., description="基金类型")
+
+    # 详细信息
+    establish_date: date | None = Field(None, description="成立日期")
+    manager: str | None = Field(None, description="基金经理")
+    company: str | None = Field(None, description="基金公司")
+    scale: float | None = Field(None, ge=0, description="规模（亿元）")
+
+    # 业绩信息
+    return_1m: float | None = Field(None, description="近1月收益率(%)")
+    return_3m: float | None = Field(None, description="近3月收益率(%)")
+    return_6m: float | None = Field(None, description="近6月收益率(%)")
+    return_1y: float | None = Field(None, description="近1年收益率(%)")
+    return_3y: float | None = Field(None, description="近3年收益率(%)")
+    return_this_year: float | None = Field(None, description="今年以来收益率(%)")
+
+    # 风险指标
+    max_drawdown: float | None = Field(None, description="最大回撤(%)")
+    sharpe_ratio: float | None = Field(None, description="夏普比率")
+
+    @field_validator("code")
+    @classmethod
+    def validate_code(cls, v: str) -> str:
+        """验证基金代码格式"""
+        if not v.isdigit():
+            raise ValueError("基金代码必须为6位数字")
+        return v
+
+    def __repr__(self) -> str:
+        return f"FundInfo(code={self.code!r}, name={self.name!r}, type={self.type.value!r})"
+
+
+class NavData(BaseModel):
+    """
+    单条净值数据模型
+    """
+
+    model_config = ConfigDict(
+        str_strip_whitespace=True,
+    )
+
+    fund_code: str = Field(..., description="基金代码")
+    nav_date: date = Field(..., description="净值日期")
+    unit_nav: float = Field(..., gt=0, description="单位净值")
+    accumulated_nav: float | None = Field(None, gt=0, description="累计净值")
+    daily_return: float | None = Field(None, description="日收益率(%)")
+
+    @field_validator("fund_code")
+    @classmethod
+    def validate_fund_code(cls, v: str) -> str:
+        """验证基金代码格式"""
+        if not v.isdigit() or len(v) != 6:
+            raise ValueError("基金代码必须为6位数字")
+        return v
+
+
+class FundFilter(BaseModel):
+    """
+    基金筛选条件模型
+    """
+
+    model_config = ConfigDict(
+        str_strip_whitespace=True,
+    )
+
+    # 基础筛选
+    fund_type: FundType | None = Field(None, description="基金类型")
+    company: str | None = Field(None, description="基金公司")
+    manager: str | None = Field(None, description="基金经理")
+
+    # 规模筛选
+    min_scale: float | None = Field(None, ge=0, description="最小规模（亿元）")
+    max_scale: float | None = Field(None, ge=0, description="最大规模（亿元）")
+
+    # 业绩筛选
+    min_return_1y: float | None = Field(None, description="近1年收益率下限(%)")
+    max_return_1y: float | None = Field(None, description="近1年收益率上限(%)")
+
+    # 风险筛选
+    max_drawdown: float | None = Field(None, description="最大回撤上限(%)")
+    min_sharpe: float | None = Field(None, description="夏普比率下限")
+
+    # V1.0 新增筛选
+    fee_rate_max: float | None = Field(None, ge=0, description="管理费率上限(%)")
+    manager_name: str | None = Field(None, description="基金经理名称")
+    min_rating: int | None = Field(None, ge=1, le=5, description="最低评级(星)")
+
+    # 关键词搜索
+    keyword: str | None = Field(None, description="关键词")
+
+    # 排序
+    sort_by: str | None = Field(None, description="排序字段")
+    sort_order: str = Field(default="desc", description="排序方向: asc/desc")
+
+    # 分页
+    limit: int = Field(default=100, ge=1, le=1000, description="返回数量限制")
+    offset: int = Field(default=0, ge=0, description="偏移量")
+
+
+class AnalysisResult(BaseModel):
+    """
+    分析结果模型
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+    )
+
+    fund_code: str = Field(..., description="基金代码")
+    fund_name: str = Field(..., description="基金名称")
+    analysis_date: date = Field(default_factory=date.today, description="分析日期")
+    start_date: date = Field(..., description="分析开始日期")
+    end_date: date = Field(..., description="分析结束日期")
+
+    # 收益指标
+    total_return: float = Field(..., description="总收益率(%)")
+    annualized_return: float = Field(..., description="年化收益率(%)")
+
+    # 风险指标
+    volatility: float = Field(..., description="年化波动率(%)")
+    max_drawdown: float = Field(..., description="最大回撤(%)")
+    var_95: float | None = Field(None, description="VaR(95%)")
+
+    # 风险调整收益
+    sharpe_ratio: float = Field(..., description="夏普比率")
+    sortino_ratio: float | None = Field(None, description="索提诺比率")
+    calmar_ratio: float | None = Field(None, description="卡玛比率")
+
+    # 相对指标
+    alpha: float | None = Field(None, description="Alpha")
+    beta: float | None = Field(None, description="Beta")
+    information_ratio: float | None = Field(None, description="信息比率")
+    tracking_error: float | None = Field(None, description="跟踪误差(%)")
+
+    def to_dict(self) -> dict:
+        """转换为字典"""
+        return self.model_dump()
+
+
+class HoldingInfo(BaseModel):
+    """持仓信息模型"""
+
+    model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True)
+    fund_code: str = Field(..., description="基金代码")
+    report_date: date = Field(..., description="报告日期")
+    stock_code: str = Field(..., description="股票代码")
+    stock_name: str = Field(..., description="股票名称")
+    weight: float = Field(..., ge=0, le=100, description="占净值比例(%)")
+    market_value: float | None = Field(None, ge=0, description="持仓市值(万元)")
+    industry: str | None = Field(None, description="所属行业")
+
+
+class FundManager(BaseModel):
+    """基金经理模型"""
+
+    model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True)
+    name: str = Field(..., min_length=1, description="经理姓名")
+    fund_code: str = Field(..., description="基金代码")
+    fund_name: str | None = Field(None, description="基金名称")
+    start_date: date | None = Field(None, description="任职起始日")
+    tenure_days: int | None = Field(None, ge=0, description="任职天数")
+    total_return: float | None = Field(None, description="任期总收益率(%)")
+    annual_return: float | None = Field(None, description="年化收益率(%)")
+
+
+class HoldingSnapshot(BaseModel):
+    """持仓快照模型"""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    fund_code: str = Field(..., description="基金代码")
+    report_date: date = Field(..., description="报告日期")
+    total_stock_count: int = Field(..., ge=0, description="持股数量")
+    top10_weight: float = Field(..., ge=0, le=100, description="前十大重仓股占比(%)")
+    industry_distribution: dict[str, float] = Field(default_factory=dict, description="行业分布")
+
+
+class OptimizationConstraint(BaseModel):
+    """优化约束条件模型"""
+
+    min_weight: float = Field(default=0.0, ge=0, le=1, description="最小权重")
+    max_weight: float = Field(default=1.0, ge=0, le=1, description="最大权重")
+    target_return: float | None = Field(None, description="目标收益率")
+    max_volatility: float | None = Field(None, ge=0, description="最大波动率")
+    max_drawdown: float | None = Field(None, le=0, description="最大回撤")
+
+
+class MonitorRule(BaseModel):
+    """监控规则模型"""
+
+    fund_code: str = Field(..., description="基金代码")
+    rule_type: str = Field(
+        default="nav_change", description="规则类型: nav_change/threshold/drawdown"
+    )
+    threshold: float = Field(default=-2.0, description="阈值")
+    enabled: bool = Field(default=True, description="是否启用")
+    created_at: datetime = Field(default_factory=datetime.now, description="创建时间")
+
+
+class OutputConfig(BaseModel):
+    """输出格式配置模型"""
+
+    default_format: str = Field(default="table", description="默认输出格式: table/csv/json")
+    csv_encoding: str = Field(default="utf-8-sig", description="CSV编码")
+    csv_delimiter: str = Field(default=",", description="CSV分隔符")
+    json_indent: int = Field(default=2, ge=0, description="JSON缩进")
+    number_decimal: int = Field(default=2, ge=0, le=6, description="数字小数位")
+    date_format: str = Field(default="%Y-%m-%d", description="日期格式")

fund_cli/utils/__init__.py

@@ -0,0 +1,6 @@
+"""工具模块 - 装饰器、验证器、辅助函数"""
+
+from fund_cli.utils.helpers import format_currency, format_percentage
+from fund_cli.utils.validators import validate_fund_code
+
+__all__ = ["validate_fund_code", "format_percentage", "format_currency"]

fund_cli/utils/decorators.py

@@ -0,0 +1,88 @@
+"""
+装饰器模块
+
+提供常用装饰器。
+"""
+
+import time
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+
+def timer(func: Callable) -> Callable:
+    """
+    计时装饰器
+
+    记录函数执行时间。
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs) -> Any:
+        start_time = time.time()
+        result = func(*args, **kwargs)
+        end_time = time.time()
+        elapsed = end_time - start_time
+        print(f"[{func.__name__}] 执行时间: {elapsed:.2f}秒")
+        return result
+
+    return wrapper
+
+
+def retry(
+    max_attempts: int = 3,
+    delay: float = 1.0,
+    exceptions: tuple = (Exception,),
+) -> Callable:
+    """
+    重试装饰器
+
+    Args:
+        max_attempts: 最大重试次数
+        delay: 重试间隔（秒）
+        exceptions: 需要重试的异常类型
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            last_exception = None
+
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+                    if attempt < max_attempts - 1:
+                        time.sleep(delay)
+
+            raise last_exception
+
+        return wrapper
+
+    return decorator
+
+
+def deprecated(message: str = "") -> Callable:
+    """
+    废弃警告装饰器
+
+    Args:
+        message: 废弃说明
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            import warnings
+
+            warnings.warn(
+                f"{func.__name__} 已废弃。{message}",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

fund_cli/utils/helpers.py

@@ -0,0 +1,127 @@
+"""
+辅助函数模块
+
+提供通用辅助函数。
+"""
+
+from datetime import date, datetime
+
+
+def format_percentage(value: float | None, decimal: int = 2) -> str:
+    """
+    格式化百分比显示
+
+    Args:
+        value: 数值
+        decimal: 小数位数
+
+    Returns:
+        格式化后的字符串
+    """
+    if value is None:
+        return "-"
+
+    return f"{value:.{decimal}f}%"
+
+
+def format_currency(
+    value: float | None,
+    unit: str = "亿",
+    decimal: int = 2,
+) -> str:
+    """
+    格式化货币显示
+
+    Args:
+        value: 数值
+        unit: 单位
+        decimal: 小数位数
+
+    Returns:
+        格式化后的字符串
+    """
+    if value is None:
+        return "-"
+
+    return f"{value:.{decimal}f}{unit}"
+
+
+def format_date(value: date | datetime | None, fmt: str = "%Y-%m-%d") -> str:
+    """
+    格式化日期显示
+
+    Args:
+        value: 日期值
+        fmt: 格式字符串
+
+    Returns:
+        格式化后的字符串
+    """
+    if value is None:
+        return "-"
+
+    if isinstance(value, datetime):
+        return value.strftime(fmt)
+    elif isinstance(value, date):
+        return value.strftime(fmt)
+
+    return str(value)
+
+
+def format_number(value: float | None, decimal: int = 2) -> str:
+    """
+    格式化数字显示
+
+    Args:
+        value: 数值
+        decimal: 小数位数
+
+    Returns:
+        格式化后的字符串
+    """
+    if value is None:
+        return "-"
+
+    return f"{value:.{decimal}f}"
+
+
+def safe_divide(
+    numerator: float,
+    denominator: float,
+    default: float = 0.0,
+) -> float:
+    """
+    安全除法
+
+    Args:
+        numerator: 分子
+        denominator: 分母
+        default: 默认值（分母为0时）
+
+    Returns:
+        计算结果
+    """
+    if denominator == 0:
+        return default
+    return numerator / denominator
+
+
+def truncate_string(s: str, max_length: int = 20, suffix: str = "...") -> str:
+    """
+    截断字符串
+
+    Args:
+        s: 原字符串
+        max_length: 最大长度
+        suffix: 后缀
+
+    Returns:
+        截断后的字符串
+    """
+    if not s:
+        return ""
+
+    if len(s) <= max_length:
+        return s
+
+    return s[: max_length - len(suffix)] + suffix

fund_cli/utils/validators.py

@@ -0,0 +1,77 @@
+"""
+验证器模块
+
+提供各类数据验证功能。
+"""
+
+import re
+
+
+def validate_fund_code(fund_code: str) -> bool:
+    """
+    验证基金代码格式
+
+    Args:
+        fund_code: 基金代码
+
+    Returns:
+        是否有效
+    """
+    if not fund_code:
+        return False
+
+    # 基金代码应为6位数字
+    if not re.match(r"^\d{6}$", fund_code):
+        return False
+
+    return True
+
+
+def validate_date(date_str: str) -> bool:
+    """
+    验证日期格式
+
+    Args:
+        date_str: 日期字符串 (YYYY-MM-DD)
+
+    Returns:
+        是否有效
+    """
+    if not date_str:
+        return False
+
+    pattern = r"^\d{4}-\d{2}-\d{2}$"
+    if not re.match(pattern, date_str):
+        return False
+
+    return True
+
+
+def validate_positive_number(value: float | None) -> bool:
+    """
+    验证正数
+
+    Args:
+        value: 数值
+
+    Returns:
+        是否为正数
+    """
+    if value is None:
+        return False
+    return value > 0
+
+
+def validate_percentage(value: float | None) -> bool:
+    """
+    验证百分比范围
+
+    Args:
+        value: 百分比值
+
+    Returns:
+        是否在有效范围内
+    """
+    if value is None:
+        return False
+    return -100 <= value <= 100

fund_cli/views/__init__.py

@@ -0,0 +1,6 @@
+"""视图层 - 表格视图、图表视图、报告视图"""
+
+from fund_cli.views.charts import ChartRenderer
+from fund_cli.views.tables import TableRenderer
+
+__all__ = ["TableRenderer", "ChartRenderer"]

fund_cli/views/charts.py

@@ -0,0 +1,120 @@
+"""
+图表渲染模块
+
+提供图表生成功能。
+"""
+
+import pandas as pd
+
+
+class ChartRenderer:
+    """
+    图表渲染器
+
+    使用 Plotly 生成交互式图表。
+    """
+
+    def __init__(self):
+        """初始化图表渲染器"""
+        self._plotly = None
+
+    def _get_plotly(self):
+        """延迟加载 Plotly"""
+        if self._plotly is None:
+            try:
+                import plotly.graph_objects as go
+
+                self._plotly = go
+            except ImportError as e:
+                raise ImportError("Plotly 未安装，请运行: pip install plotly") from e
+        return self._plotly
+
+    def render_nav_chart(
+        self,
+        nav_data: pd.DataFrame,
+        title: str = "净值走势",
+    ) -> dict:
+        """
+        渲染净值走势图
+
+        Args:
+            nav_data: 净值数据
+            title: 图表标题
+
+        Returns:
+            Plotly Figure 字典
+        """
+        go = self._get_plotly()
+
+        fig = go.Figure()
+
+        # 单位净值
+        fig.add_trace(
+            go.Scatter(
+                x=nav_data["nav_date"],
+                y=nav_data["unit_nav"],
+                mode="lines",
+                name="单位净值",
+                line={"color": "blue"},
+            )
+        )
+
+        # 累计净值
+        if "accumulated_nav" in nav_data.columns:
+            fig.add_trace(
+                go.Scatter(
+                    x=nav_data["nav_date"],
+                    y=nav_data["accumulated_nav"],
+                    mode="lines",
+                    name="累计净值",
+                    line={"color": "green", "dash": "dot"},
+                )
+            )
+
+        fig.update_layout(
+            title=title,
+            xaxis_title="日期",
+            yaxis_title="净值",
+            hovermode="x unified",
+        )
+
+        return fig.to_dict()
+
+    def render_drawdown_chart(
+        self,
+        drawdown: pd.Series,
+        title: str = "回撤分析",
+    ) -> dict:
+        """
+        渲染回撤图表
+
+        Args:
+            drawdown: 回撤序列
+            title: 图表标题
+
+        Returns:
+            Plotly Figure 字典
+        """
+        go = self._get_plotly()
+
+        fig = go.Figure()
+
+        fig.add_trace(
+            go.Scatter(
+                x=drawdown.index,
+                y=drawdown * 100,
+                mode="lines",
+                name="回撤",
+                fill="tozeroy",
+                line={"color": "red"},
+            )
+        )
+
+        fig.update_layout(
+            title=title,
+            xaxis_title="日期",
+            yaxis_title="回撤(%)",
+            hovermode="x unified",
+        )
+
+        return fig.to_dict()