akshare-one 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

akshare_one/__init__.py

@@ -7,12 +7,11 @@ Provides standardized access to various financial data sources with:
 
 Example:
     >>> from akshare_one import get_hist_data, get_realtime_data
+    >>> # 获取股票历史数据
     >>> df = get_hist_data("600000", interval="day")
     >>> print(df.head())
-    >>> # 获取单只股票实时数据
+    >>> # 获取股票实时数据
     >>> df = get_realtime_data(symbol="600000")
-    >>> # 获取所有股票实时数据
-    >>> df = get_realtime_data()
 """
 
 from .stock import get_hist_data, get_realtime_data

akshare_one/financial.py

@@ -4,7 +4,7 @@
 """
 
 import pandas as pd
-from .adapters import SinaAdapter
+from akshare_one.modules.financial.factory import FinancialDataFactory
 
 
 def get_balance_sheet(symbol: str, source: str = "sina") -> "pd.DataFrame":
@@ -15,7 +15,8 @@ def get_balance_sheet(symbol: str, source: str = "sina") -> "pd.DataFrame":
         source: 数据源 ("sina")
     """
     if source == "sina":
-        return SinaAdapter().get_balance_sheet(symbol=symbol)
+        provider = FinancialDataFactory.get_provider(source, symbol=symbol)
+        return provider.get_balance_sheet()
     raise ValueError(f"Unsupported data source: {source}")
 
 
@@ -27,7 +28,8 @@ def get_income_statement(symbol: str, source: str = "sina") -> "pd.DataFrame":
         source: 数据源 ("sina")
     """
     if source == "sina":
-        return SinaAdapter().get_income_statement(symbol=symbol)
+        provider = FinancialDataFactory.get_provider(source, symbol=symbol)
+        return provider.get_income_statement()
     raise ValueError(f"Unsupported data source: {source}")
 
 
@@ -39,5 +41,6 @@ def get_cash_flow(symbol: str, source: str = "sina") -> "pd.DataFrame":
         source: 数据源 ("sina")
     """
     if source == "sina":
-        return SinaAdapter().get_cash_flow(symbol=symbol)
+        provider = FinancialDataFactory.get_provider(source, symbol=symbol)
+        return provider.get_cash_flow()
     raise ValueError(f"Unsupported data source: {source}")

akshare_one/insider.py

@@ -5,10 +5,12 @@
 
 from typing import Optional
 import pandas as pd
-from .adapters import XueQiuAdapter
+from .modules.insider.factory import InsiderDataFactory
 
 
-def get_inner_trade_data(source: str = "xueqiu", symbol: Optional[str] = None) -> "pd.DataFrame":
+def get_inner_trade_data(
+    symbol: Optional[str] = None, source: str = "xueqiu"
+) -> "pd.DataFrame":
     """获取雪球内部交易数据
 
     Args:
@@ -30,6 +32,5 @@ def get_inner_trade_data(source: str = "xueqiu", symbol: Optional[str] = None) -
         - transaction_value: 交易金额(变动股数*成交均价)
         - shares_owned_before_transaction: 变动前持股数
     """
-    if source == "xueqiu":
-        return XueQiuAdapter().get_inner_trade_data(symbol=symbol)
-    raise ValueError(f"Unsupported data source: {source}")
+    provider = InsiderDataFactory.get_provider(source, symbol=symbol)
+    return provider.get_inner_trade_data()

akshare_one/modules/cache.py

@@ -0,0 +1,9 @@
+from cachetools import TTLCache
+
+# 缓存配置
+CACHE_CONFIG = {
+    "hist_data_cache": TTLCache(maxsize=1000, ttl=3600),  # 历史数据缓存1小时
+    "realtime_cache": TTLCache(maxsize=500, ttl=60),  # 实时数据缓存1分钟
+    "news_cache": TTLCache(maxsize=500, ttl=3600),
+    "financial_cache": TTLCache(maxsize=500, ttl=86400),  # 财务数据缓存24小时
+}

akshare_one/modules/financial/base.py

@@ -0,0 +1,41 @@
+from abc import ABC, abstractmethod
+import pandas as pd
+
+
+def validate_financial_data(func):
+    """Decorator to validate financial data returned by data providers"""
+
+    def wrapper(*args, **kwargs):
+        df = func(*args, **kwargs)
+
+        if not isinstance(df, pd.DataFrame):
+            raise ValueError("Returned data must be a pandas DataFrame")
+
+        # Validate report_date if present
+        if "report_date" in df.columns:
+            if not pd.api.types.is_datetime64_any_dtype(df["report_date"]):
+                raise ValueError("report_date must be datetime64 dtype")
+
+        return df
+
+    return wrapper
+
+
+class FinancialDataProvider(ABC):
+    def __init__(self, symbol: str) -> None:
+        self.symbol = symbol
+
+    @abstractmethod
+    def get_balance_sheet(self) -> pd.DataFrame:
+        """Fetches balance sheet data"""
+        pass
+
+    @abstractmethod
+    def get_income_statement(self) -> pd.DataFrame:
+        """Fetches income statement data"""
+        pass
+
+    @abstractmethod
+    def get_cash_flow(self) -> pd.DataFrame:
+        """Fetches cash flow data"""
+        pass

akshare_one/modules/financial/factory.py

@@ -0,0 +1,44 @@
+from .sina import SinaFinancialReport
+from .base import FinancialDataProvider
+
+
+class FinancialDataFactory:
+    """
+    Factory class for creating financial data providers
+    """
+
+    _providers = {
+        "sina": SinaFinancialReport,
+    }
+
+    @classmethod
+    def get_provider(cls, provider_name: str, **kwargs) -> FinancialDataProvider:
+        """
+        Get a financial data provider by name
+
+        Args:
+            provider_name: Name of the provider (e.g., 'sina')
+            **kwargs: Additional arguments to pass to the provider's constructor
+
+        Returns:
+            FinancialDataProvider: An instance of the requested provider
+
+        Raises:
+            ValueError: If the requested provider is not found
+        """
+        provider_class = cls._providers.get(provider_name.lower())
+        if not provider_class:
+            raise ValueError(f"Unknown financial data provider: {provider_name}")
+
+        return provider_class(**kwargs)
+
+    @classmethod
+    def register_provider(cls, name: str, provider_class: type):
+        """
+        Register a new financial data provider
+
+        Args:
+            name: Name to associate with this provider
+            provider_class: The provider class to register
+        """
+        cls._providers[name.lower()] = provider_class

akshare_one/{adapters → modules/financial}/sina.py

@@ -1,19 +1,24 @@
+from cachetools import cached
 import pandas as pd
 import akshare as ak
-from cachetools import cached
-from .cache.cache import CACHE_CONFIG
 
+from akshare_one.modules.cache import CACHE_CONFIG
+from .base import FinancialDataProvider, validate_financial_data
 
-class SinaAdapter:
-    """Adapter for Sina financial data API
 
-    Includes:
-    - Financial reports (balance sheet, income statement, cash flow)
-    - Historical market data
-    """
+class SinaFinancialReport(FinancialDataProvider):
+    def __init__(self, symbol: str) -> None:
+        super().__init__(symbol)
+        self.stock = (
+            f"sh{symbol}" if not symbol.startswith(("sh", "sz", "bj")) else symbol
+        )
 
-    @cached(CACHE_CONFIG["financial_cache"], key=lambda self, symbol: f"sina_balance_{symbol}")
-    def get_balance_sheet(self, symbol: str) -> pd.DataFrame:
+    @validate_financial_data
+    @cached(
+        CACHE_CONFIG["financial_cache"],
+        key=lambda self, symbol=None: f"sina_balance_{self.symbol}",
+    )
+    def get_balance_sheet(self) -> pd.DataFrame:
         """获取资产负债表数据
 
         Args:
@@ -22,12 +27,15 @@ class SinaAdapter:
         Returns:
             Standardized DataFrame with balance sheet data
         """
-        stock = f"sh{symbol}" if not symbol.startswith(("sh", "sz", "bj")) else symbol
-        raw_df = ak.stock_financial_report_sina(stock=stock, symbol="资产负债表")
+        raw_df = ak.stock_financial_report_sina(stock=self.stock, symbol="资产负债表")
         return self._clean_balance_data(raw_df)
 
-    @cached(CACHE_CONFIG["financial_cache"], key=lambda self, symbol: f"sina_income_{symbol}")
-    def get_income_statement(self, symbol: str) -> pd.DataFrame:
+    @validate_financial_data
+    @cached(
+        CACHE_CONFIG["financial_cache"],
+        key=lambda self, symbol=None: f"sina_income_{self.symbol}",
+    )
+    def get_income_statement(self) -> pd.DataFrame:
         """获取利润表数据
 
         Args:
@@ -36,12 +44,15 @@ class SinaAdapter:
         Returns:
             Standardized DataFrame with income statement data
         """
-        stock = f"sh{symbol}" if not symbol.startswith(("sh", "sz", "bj")) else symbol
-        raw_df = ak.stock_financial_report_sina(stock=stock, symbol="利润表")
+        raw_df = ak.stock_financial_report_sina(stock=self.stock, symbol="利润表")
         return self._clean_income_data(raw_df)
 
-    @cached(CACHE_CONFIG["financial_cache"], key=lambda self, symbol: f"sina_cash_{symbol}")
-    def get_cash_flow(self, symbol: str) -> pd.DataFrame:
+    @validate_financial_data
+    @cached(
+        CACHE_CONFIG["financial_cache"],
+        key=lambda self, symbol=None: f"sina_cash_{self.symbol}",
+    )
+    def get_cash_flow(self) -> pd.DataFrame:
         """获取现金流量表数据
 
         Args:
@@ -50,8 +61,7 @@ class SinaAdapter:
         Returns:
             Standardized DataFrame with cash flow data
         """
-        stock = f"sh{symbol}" if not symbol.startswith(("sh", "sz", "bj")) else symbol
-        raw_df = ak.stock_financial_report_sina(stock=stock, symbol="现金流量表")
+        raw_df = ak.stock_financial_report_sina(stock=self.stock, symbol="现金流量表")
         return self._clean_cash_data(raw_df)
 
     def _clean_cash_data(self, raw_df: pd.DataFrame) -> pd.DataFrame:
@@ -199,181 +209,6 @@ class SinaAdapter:
         available_columns = [col for col in required_columns if col in raw_df.columns]
         return raw_df[available_columns]
 
-    @cached(
-        CACHE_CONFIG["hist_data_cache"],
-        key=lambda self,
-        symbol,
-        interval,
-        interval_multiplier,
-        start_date,
-        end_date,
-        adjust: ("sina", symbol, interval, interval_multiplier, start_date, end_date, adjust),
-    )
-    def get_hist_data(
-        self,
-        symbol: str,
-        interval: str = "day",
-        interval_multiplier: int = 1,
-        start_date: str = "1970-01-01",
-        end_date: str = "2030-12-31",
-        adjust: str = "none",
-    ) -> pd.DataFrame:
-        """获取新浪历史行情数据
-
-        Args:
-            symbol: 股票代码 (如 "600000")
-            interval: 时间粒度 (支持: "minute", "hour", "day", "week", "month", "year")
-            interval_multiplier: 时间间隔倍数 (如: 5分钟数据设为5)
-            start_date: 开始日期 (YYYY-MM-DD)
-            end_date: 结束日期 (YYYY-MM-DD)
-            adjust: 复权类型 ('none','qfq','hfq','qfq-factor','hfq-factor')
-
-        Returns:
-            Standardized DataFrame with OHLCV data
-        """
-        interval = interval.lower()
-        stock = f"sh{symbol}" if not symbol.startswith(("sh", "sz", "bj")) else symbol
-
-        if interval == "minute":
-            raw_df = ak.stock_zh_a_minute(
-                symbol=stock,
-                period="1",
-                adjust=adjust if adjust != "none" else "",
-            )
-            raw_df = raw_df.rename(columns={"day": "date"})
-            raw_df["date"] = pd.to_datetime(raw_df["date"])
-            raw_df = raw_df.set_index("date")
-            raw_df = (
-                raw_df.resample(f"{interval_multiplier}min")
-                .agg(
-                    {
-                        "open": "first",
-                        "high": "max",
-                        "low": "min",
-                        "close": "last",
-                        "volume": "sum",
-                    }
-                )
-                .reset_index()
-            )
-
-        elif interval == "hour":
-            if interval_multiplier < 1:
-                raise ValueError("Hour interval multiplier must be >= 1")
-
-            raw_df = ak.stock_zh_a_minute(
-                symbol=stock,
-                period="60",
-                adjust=adjust if adjust != "none" else "",
-            )
-            raw_df = raw_df.rename(columns={"day": "date"})
-            raw_df["date"] = pd.to_datetime(raw_df["date"])
-            raw_df = raw_df.set_index("date")
-            raw_df = (
-                raw_df.resample(f"{interval_multiplier}h")
-                .agg(
-                    {
-                        "open": "first",
-                        "high": "max",
-                        "low": "min",
-                        "close": "last",
-                        "volume": "sum",
-                    }
-                )
-                .reset_index()
-            )
-
-        elif interval in ["day", "week", "month", "year"]:
-            # Convert date format from YYYY-MM-DD to YYYYMMDD
-            start_date = (
-                start_date.replace("-", "") if "-" in start_date else start_date
-            )
-            end_date = end_date.replace("-", "") if "-" in end_date else end_date
-
-            raw_df = ak.stock_zh_a_daily(
-                symbol=stock,
-                start_date=start_date,
-                end_date=end_date,
-                adjust=adjust if adjust != "none" else "",
-            )
-
-            if interval_multiplier > 1:
-                raw_df = self._resample_data(raw_df, interval, interval_multiplier)
-        else:
-            raise ValueError(f"Unsupported interval: {interval}")
-
-        return self._clean_hist_data(raw_df, adjust)
-
-    def _resample_data(
-        self, df: pd.DataFrame, interval: str, multiplier: int
-    ) -> pd.DataFrame:
-        if interval == "day":
-            freq = f"{multiplier}D"
-        elif interval == "week":
-            freq = f"{multiplier}W-MON"
-        elif interval == "month":
-            freq = f"{multiplier}MS"
-        elif interval == "year":
-            freq = f"{multiplier}AS-JAN"
-
-        df["date"] = pd.to_datetime(df["date"])
-        df = df.set_index("date")
-        resampled = df.resample(freq).agg(
-            {
-                "open": "first",
-                "high": "max",
-                "low": "min",
-                "close": "last",
-                "volume": "sum",
-            }
-        )
-        return resampled.reset_index()
-
-    def _clean_hist_data(self, raw_df: pd.DataFrame, adjust: str) -> pd.DataFrame:
-        """清理和标准化历史行情数据
-
-        Args:
-            raw_df: 原始数据DataFrame
-            adjust: 复权类型
-
-        Returns:
-            标准化后的DataFrame
-        """
-        column_mapping = {
-            "date": "timestamp",
-            "open": "open",
-            "high": "high",
-            "low": "low",
-            "close": "close",
-            "volume": "volume",
-        }
-
-        df = raw_df.rename(columns=column_mapping)
-
-        # Process timestamp
-        if "timestamp" in df.columns:
-            df["timestamp"] = (
-                pd.to_datetime(df["timestamp"])
-                .dt.tz_localize("Asia/Shanghai")
-                .dt.tz_convert("UTC")
-            )
-
-        # Process volume
-        if "volume" in df.columns:
-            df["volume"] = df["volume"].astype("int64")
-
-        # Select and order columns
-        standard_columns = [
-            "timestamp",
-            "open",
-            "high",
-            "low",
-            "close",
-            "volume",
-        ]
-
-        return df[[col for col in standard_columns if col in df.columns]]
-
     def _clean_income_data(self, raw_df: pd.DataFrame) -> pd.DataFrame:
         """清理和标准化利润表数据
 

akshare_one/modules/historical/base.py

@@ -0,0 +1,64 @@
+from abc import ABC, abstractmethod
+import pandas as pd
+
+
+def validate_hist_data(func):
+    """Decorator to validate historical data returned by data providers"""
+
+    def wrapper(*args, **kwargs):
+        df = func(*args, **kwargs)
+
+        if not isinstance(df, pd.DataFrame):
+            raise ValueError("Returned data must be a pandas DataFrame")
+
+        required_columns = {"timestamp", "open", "high", "low", "close", "volume"}
+        missing_cols = required_columns - set(df.columns)
+        if missing_cols:
+            raise ValueError(f"Missing required columns: {missing_cols}")
+
+        if "timestamp" in df.columns:
+            if not pd.api.types.is_datetime64_any_dtype(df["timestamp"]):
+                raise ValueError("timestamp must be datetime64 dtype")
+            if df["timestamp"].dt.tz is None or str(df["timestamp"].dt.tz) != "UTC":
+                raise ValueError("timestamp must be in UTC timezone")
+
+        return df
+
+    return wrapper
+
+
+class HistoricalDataProvider(ABC):
+    def __init__(
+        self,
+        symbol: str,
+        interval: str = "day",
+        interval_multiplier: int = 1,
+        start_date: str = "1970-01-01",
+        end_date: str = "2030-12-31",
+        adjust: str = "none",
+    ) -> None:
+        self.symbol = symbol
+        self.interval = interval
+        self.interval_multiplier = interval_multiplier
+        self.start_date = start_date
+        self.end_date = end_date
+        self.adjust = adjust
+
+    @classmethod
+    def get_supported_intervals(cls):
+        return ["minute", "hour", "day", "week", "month", "year"]
+
+    @abstractmethod
+    def get_hist_data(self) -> pd.DataFrame:
+        """Fetches historical market data
+
+        Returns:
+            pd.DataFrame:
+            - timestamp (UTC)
+            - open
+            - high
+            - low
+            - close
+            - volume
+        """
+        pass