fund-cli 2.0.0__py3-none-any.whl

fund_cli/data/adapters/wind_adapter.py

@@ -0,0 +1,78 @@
+"""
+Wind 数据源适配器（占位）
+
+Wind 是商业数据源，需要授权使用。
+此文件为接口预留，实际实现需要 Wind Python API。
+"""
+
+from typing import Any
+
+import pandas as pd
+
+from fund_cli.data.base import (
+    DataSourceAdapter,
+    DataSourceError,
+)
+from fund_cli.data.cache import DataCache
+
+
+class WindAdapter(DataSourceAdapter):
+    """
+    Wind 数据源适配器（占位实现）
+
+    Wind 是商业数据源，需要授权和 Wind Python API。
+    当前为接口预留，实际使用需要：
+    1. 安装 Wind Python API
+    2. 配置有效的 Wind 账号
+    """
+
+    def __init__(self, cache: DataCache | None = None):
+        super().__init__("wind")
+        self._cache = cache
+
+    def is_available(self) -> bool:
+        """检查 Wind 是否可用"""
+        try:
+            from WindPy import w  # noqa: F401
+
+            return w.isconnected()
+        except Exception:
+            return False
+
+    def get_fund_info(self, fund_code: str) -> dict[str, Any]:
+        """获取基金基础信息"""
+        raise DataSourceError("Wind 数据源暂未实现，请使用 AKShare 或 Tushare 数据源")
+
+    def get_fund_nav(
+        self,
+        fund_code: str,
+        start_date: Any | None = None,
+        end_date: Any | None = None,
+    ) -> pd.DataFrame:
+        """获取基金净值数据"""
+        raise DataSourceError("Wind 数据源暂未实现，请使用 AKShare 或 Tushare 数据源")
+
+    def search_funds(
+        self,
+        fund_type: str | None = None,
+        company: str | None = None,
+        min_scale: float | None = None,
+        max_scale: float | None = None,
+        keyword: str | None = None,
+        limit: int = 100,
+    ) -> pd.DataFrame:
+        """搜索基金"""
+        raise DataSourceError("Wind 数据源暂未实现，请使用 AKShare 或 Tushare 数据源")
+
+    def get_fund_list(self, fund_type: str | None = None) -> pd.DataFrame:
+        """获取基金列表"""
+        raise DataSourceError("Wind 数据源暂未实现，请使用 AKShare 或 Tushare 数据源")
+
+    def get_benchmark_nav(
+        self,
+        benchmark_code: str,
+        start_date: Any | None = None,
+        end_date: Any | None = None,
+    ) -> pd.DataFrame:
+        """获取基准指数数据"""
+        raise DataSourceError("Wind 数据源暂未实现，请使用 AKShare 或 Tushare 数据源")

fund_cli/data/base.py

@@ -0,0 +1,209 @@
+"""
+数据源适配器基类
+
+定义数据源适配器的标准接口，支持多数据源扩展。
+"""
+
+from abc import ABC, abstractmethod
+from datetime import date
+from typing import Any
+
+import pandas as pd
+
+
+class DataSourceAdapter(ABC):
+    """
+    数据源适配器基类
+
+    所有数据源适配器必须继承此类并实现所有抽象方法。
+    """
+
+    def __init__(self, name: str):
+        """
+        初始化数据源适配器
+
+        Args:
+            name: 数据源名称
+        """
+        self._name = name
+
+    @property
+    def name(self) -> str:
+        """数据源名称"""
+        return self._name
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """
+        检查数据源是否可用
+
+        Returns:
+            数据源是否可用
+        """
+        pass
+
+    @abstractmethod
+    def get_fund_info(self, fund_code: str) -> dict[str, Any]:
+        """
+        获取基金基础信息
+
+        Args:
+            fund_code: 基金代码（6位数字）
+
+        Returns:
+            基金基础信息字典，包含：
+            - code: 基金代码
+            - name: 基金名称
+            - type: 基金类型
+            - establish_date: 成立日期
+            - manager: 基金经理
+            - company: 基金公司
+            - scale: 规模（亿元）
+
+        Raises:
+            DataNotFoundError: 基金不存在
+            DataSourceError: 数据源错误
+        """
+        pass
+
+    @abstractmethod
+    def get_fund_nav(
+        self,
+        fund_code: str,
+        start_date: date | None = None,
+        end_date: date | None = None,
+    ) -> pd.DataFrame:
+        """
+        获取基金净值数据
+
+        Args:
+            fund_code: 基金代码
+            start_date: 开始日期，默认为基金成立日
+            end_date: 结束日期，默认为最新日期
+
+        Returns:
+            净值数据DataFrame，包含列：
+            - nav_date: 净值日期
+            - unit_nav: 单位净值
+            - accumulated_nav: 累计净值
+            - daily_return: 日收益率（可选）
+
+        Raises:
+            DataNotFoundError: 基金不存在
+            DataSourceError: 数据源错误
+        """
+        pass
+
+    @abstractmethod
+    def search_funds(
+        self,
+        fund_type: str | None = None,
+        company: str | None = None,
+        min_scale: float | None = None,
+        max_scale: float | None = None,
+        keyword: str | None = None,
+        limit: int = 100,
+    ) -> pd.DataFrame:
+        """
+        搜索/筛选基金
+
+        Args:
+            fund_type: 基金类型
+            company: 基金公司
+            min_scale: 最小规模（亿元）
+            max_scale: 最大规模（亿元）
+            keyword: 关键词搜索
+            limit: 返回数量限制
+
+        Returns:
+            基金列表DataFrame
+        """
+        pass
+
+    @abstractmethod
+    def get_fund_list(self, fund_type: str | None = None) -> pd.DataFrame:
+        """
+        获取基金列表
+
+        Args:
+            fund_type: 基金类型筛选
+
+        Returns:
+            基金列表DataFrame
+        """
+        pass
+
+    @abstractmethod
+    def get_benchmark_nav(
+        self,
+        benchmark_code: str,
+        start_date: date | None = None,
+        end_date: date | None = None,
+    ) -> pd.DataFrame:
+        """
+        获取基准指数净值数据
+
+        Args:
+            benchmark_code: 基准指数代码
+            start_date: 开始日期
+            end_date: 结束日期
+
+        Returns:
+            基准净值数据DataFrame
+        """
+        pass
+
+    @abstractmethod
+    def get_fund_holdings(
+        self,
+        fund_code: str,
+        report_date: date | None = None,
+    ) -> pd.DataFrame:
+        """获取基金持仓数据"""
+        pass
+
+    @abstractmethod
+    def get_fund_manager(self, fund_code: str) -> dict[str, Any]:
+        """获取基金经理信息"""
+        pass
+
+    @abstractmethod
+    def get_fund_fee(self, fund_code: str) -> dict[str, Any]:
+        """获取基金费率信息"""
+        pass
+
+    @abstractmethod
+    def get_fund_rating(self, fund_code: str) -> int | None:
+        """获取基金评级"""
+        pass
+
+    @abstractmethod
+    def batch_get_fund_nav(
+        self,
+        fund_codes: list[str],
+        start_date: date | None = None,
+        end_date: date | None = None,
+    ) -> dict[str, pd.DataFrame]:
+        """批量获取基金净值数据"""
+        pass
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name={self._name!r})"
+
+
+class DataSourceError(Exception):
+    """数据源错误"""
+
+    pass
+
+
+class DataNotFoundError(Exception):
+    """数据未找到错误"""
+
+    pass
+
+
+class NetworkError(Exception):
+    """网络错误"""
+
+    pass

fund_cli/data/cache.py

@@ -0,0 +1,192 @@
+"""
+数据缓存管理
+
+使用 DiskCache 实现数据缓存，支持过期时间和持久化。
+"""
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+from diskcache import Cache
+
+
+class DataCache:
+    """
+    数据缓存管理器
+
+    使用 DiskCache 实现数据缓存，支持：
+    - 过期时间设置
+    - 持久化存储
+    - 自动序列化/反序列化
+    """
+
+    def __init__(
+        self,
+        cache_dir: str = "~/.fund_cli/cache",
+        default_ttl: int = 3600,
+    ):
+        """
+        初始化缓存管理器
+
+        Args:
+            cache_dir: 缓存目录
+            default_ttl: 默认过期时间（秒）
+        """
+        self.cache_dir = Path(cache_dir).expanduser()
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.default_ttl = default_ttl
+        self._cache = Cache(str(self.cache_dir))
+
+    def _generate_key(self, prefix: str, *args, **kwargs) -> str:
+        """
+        生成缓存键
+
+        Args:
+            prefix: 键前缀
+            *args: 位置参数
+            **kwargs: 关键字参数
+
+        Returns:
+            缓存键字符串
+        """
+        # 将参数序列化为字符串
+        key_data = json.dumps({"args": args, "kwargs": kwargs}, sort_keys=True, default=str)
+        key_hash = hashlib.md5(key_data.encode()).hexdigest()[:8]
+        return f"{prefix}:{key_hash}"
+
+    def get(self, key: str) -> Any | None:
+        """
+        获取缓存值
+
+        Args:
+            key: 缓存键
+
+        Returns:
+            缓存值，不存在返回 None
+        """
+        return self._cache.get(key)
+
+    def set(
+        self,
+        key: str,
+        value: Any,
+        ttl: int | None = None,
+    ) -> None:
+        """
+        设置缓存值
+
+        Args:
+            key: 缓存键
+            value: 缓存值
+            ttl: 过期时间（秒），默认使用 default_ttl
+        """
+        expire = ttl if ttl is not None else self.default_ttl
+        self._cache.set(key, value, expire=expire)
+
+    def delete(self, key: str) -> bool:
+        """
+        删除缓存
+
+        Args:
+            key: 缓存键
+
+        Returns:
+            是否删除成功
+        """
+        return self._cache.delete(key)
+
+    def exists(self, key: str) -> bool:
+        """
+        检查缓存是否存在
+
+        Args:
+            key: 缓存键
+
+        Returns:
+            缓存是否存在
+        """
+        return key in self._cache
+
+    def clear(self) -> None:
+        """清空所有缓存"""
+        self._cache.clear()
+
+    def get_stats(self) -> dict:
+        """
+        获取缓存统计信息
+
+        Returns:
+            统计信息字典
+        """
+        return {
+            "size": len(self._cache),
+            "volume": self._cache.volume(),
+            "directory": str(self.cache_dir),
+        }
+
+    # ========== 便捷方法 ==========
+
+    def get_fund_info(self, fund_code: str) -> dict | None:
+        """获取缓存的基金信息"""
+        key = f"fund_info:{fund_code}"
+        return self.get(key)
+
+    def set_fund_info(self, fund_code: str, info: dict, ttl: int | None = None) -> None:
+        """缓存基金信息"""
+        key = f"fund_info:{fund_code}"
+        self.set(key, info, ttl)
+
+    def get_fund_nav(self, fund_code: str, start_date: str, end_date: str) -> pd.DataFrame | None:
+        """获取缓存的净值数据"""
+        key = f"fund_nav:{fund_code}:{start_date}:{end_date}"
+        return self.get(key)
+
+    def set_fund_nav(
+        self,
+        fund_code: str,
+        start_date: str,
+        end_date: str,
+        nav_data: pd.DataFrame,
+        ttl: int | None = None,
+    ) -> None:
+        """缓存净值数据"""
+        key = f"fund_nav:{fund_code}:{start_date}:{end_date}"
+        self.set(key, nav_data, ttl)
+
+    def get_fund_holdings(self, fund_code: str, report_date: str = "latest") -> pd.DataFrame | None:
+        """获取缓存的持仓数据"""
+        key = f"fund_holdings:{fund_code}:{report_date}"
+        return self.get(key)
+
+    def set_fund_holdings(
+        self,
+        fund_code: str,
+        report_date: str,
+        data: pd.DataFrame,
+        ttl: int | None = None,
+    ) -> None:
+        """缓存持仓数据"""
+        key = f"fund_holdings:{fund_code}:{report_date}"
+        self.set(key, data, ttl)
+
+    def get_fund_manager(self, fund_code: str) -> dict | None:
+        """获取缓存的经理信息"""
+        key = f"fund_manager:{fund_code}"
+        return self.get(key)
+
+    def set_fund_manager(self, fund_code: str, info: dict, ttl: int | None = None) -> None:
+        """缓存经理信息"""
+        key = f"fund_manager:{fund_code}"
+        self.set(key, info, ttl)
+
+    def __enter__(self) -> "DataCache":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        pass
+
+    def __repr__(self) -> str:
+        return f"DataCache(directory={self.cache_dir}, size={len(self._cache)})"