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

akshare_one/modules/historical/eastmoney.py

@@ -0,0 +1,242 @@
+from cachetools import cached
+from .base import HistoricalDataProvider, validate_hist_data
+import akshare as ak
+import pandas as pd
+from ..cache import CACHE_CONFIG
+
+
+class EastMoneyHistorical(HistoricalDataProvider):
+    """Adapter for EastMoney historical stock data API"""
+
+    @validate_hist_data
+    @cached(
+        cache=CACHE_CONFIG["hist_data_cache"],
+        key=lambda self: f"eastmoney_hist_{self.symbol}_{self.interval}_{self.interval_multiplier}_{self.adjust}",
+    )
+    def get_hist_data(self) -> pd.DataFrame:
+        """Fetches EastMoney historical market data
+
+        Returns:
+            pd.DataFrame:
+                - timestamp
+                - open
+                - high
+                - low
+                - close
+                - volume
+        """
+        self.interval = self.interval.lower()
+        self._validate_interval_params(self.interval, self.interval_multiplier)
+
+        try:
+            if self.interval in ["minute", "hour"]:
+                df = self._get_intraday_data()
+            else:
+                df = self._get_daily_plus_data()
+
+            return df
+        except Exception as e:
+            raise ValueError(f"Failed to fetch historical data: {str(e)}")
+
+    def _get_intraday_data(self) -> pd.DataFrame:
+        """Fetches intraday data at minute or hour intervals"""
+        # Set trading hours
+        start_date = self._ensure_time_format(self.start_date, "09:30:00")
+        end_date = self._ensure_time_format(self.end_date, "15:00:00")
+
+        # Get raw data
+        period = "1" if self.interval == "minute" else "60"
+        raw_df = ak.stock_zh_a_hist_min_em(
+            symbol=self.symbol,
+            period=period,
+            start_date=start_date,
+            end_date=end_date,
+            adjust=self._map_adjust_param(self.adjust),
+        )
+
+        # Process data
+        resampled = self._resample_intraday_data(
+            raw_df,
+            f"{self.interval_multiplier}min"
+            if self.interval == "minute"
+            else f"{self.interval_multiplier}h",
+        )
+        return self._clean_minute_data(resampled, str(self.interval_multiplier))
+
+    def _get_daily_plus_data(self) -> pd.DataFrame:
+        """Fetches daily and higher-level data (day/week/month/year)"""
+        start_date = self._convert_date_format(self.start_date)
+        end_date = self._convert_date_format(self.end_date)
+
+        period_map = {
+            "day": "daily",
+            "week": "weekly",
+            "month": "monthly",
+            "year": "monthly",
+        }
+        period = period_map[self.interval]
+
+        raw_df = ak.stock_zh_a_hist(
+            symbol=self.symbol,
+            period=period,
+            start_date=start_date,
+            end_date=end_date,
+            adjust=self._map_adjust_param(self.adjust),
+        )
+
+        if self.interval == "year":
+            self.interval_multiplier *= 12
+
+        if self.interval_multiplier > 1:
+            raw_df = self._resample_data(
+                raw_df, self.interval, self.interval_multiplier
+            )
+
+        return self._clean_data(raw_df)
+
+    def _validate_interval_params(self, interval: str, multiplier: int) -> None:
+        """Validates the validity of interval and multiplier"""
+        if interval not in self.get_supported_intervals():
+            raise ValueError(f"Unsupported interval parameter: {interval}")
+
+        if interval in ["minute", "hour"] and multiplier < 1:
+            raise ValueError(f"interval_multiplier for {interval} level must be ≥ 1")
+
+    def _ensure_time_format(self, date_str: str, default_time: str) -> str:
+        """Ensures the date string includes the time part"""
+        if " " not in date_str:
+            return f"{date_str} {default_time}"
+        return date_str
+
+    def _convert_date_format(self, date_str: str) -> str:
+        """Converts date format from YYYY-MM-DD to YYYYMMDD"""
+        return date_str.replace("-", "") if "-" in date_str else date_str
+
+    def _map_adjust_param(self, adjust: str) -> str:
+        """Maps adjustment parameters to the required format"""
+        return adjust if adjust != "none" else ""
+
+    def _resample_intraday_data(self, df: pd.DataFrame, freq: str) -> pd.DataFrame:
+        """Resamples intraday data to the specified frequency"""
+        df["时间"] = pd.to_datetime(df["时间"])
+        df = df.set_index("时间")
+        resampled = df.resample(freq).agg(
+            {
+                "开盘": "first",
+                "最高": "max",
+                "最低": "min",
+                "收盘": "last",
+                "成交量": "sum",
+                "成交额": "sum",
+            }
+        )
+        return resampled.reset_index()
+
+    def _resample_data(
+        self, df: pd.DataFrame, interval: str, multiplier: int
+    ) -> pd.DataFrame:
+        """Resamples daily and higher-level data to the specified interval"""
+        freq_map = {
+            "day": f"{multiplier}D",
+            "week": f"{multiplier}W-MON",
+            "month": f"{multiplier}MS",
+            "year": f"{multiplier}AS-JAN",
+        }
+        freq = freq_map[interval]
+
+        df["日期"] = pd.to_datetime(df["日期"])
+        df = df.set_index("日期")
+        resampled = df.resample(freq).agg(
+            {
+                "开盘": "first",
+                "最高": "max",
+                "最低": "min",
+                "收盘": "last",
+                "成交量": "sum",
+            }
+        )
+        return resampled.reset_index()
+
+    def _clean_minute_data(self, raw_df: pd.DataFrame, period: str) -> pd.DataFrame:
+        """Cleans and standardizes minute/hour level data, converting timestamps to UTC"""
+        column_map = {
+            "1": {
+                "时间": "timestamp",
+                "开盘": "open",
+                "收盘": "close",
+                "最高": "high",
+                "最低": "low",
+                "成交量": "volume",
+                "成交额": "amount",
+                "均价": "vwap",
+            },
+            "default": {
+                "时间": "timestamp",
+                "开盘": "open",
+                "收盘": "close",
+                "最高": "high",
+                "最低": "low",
+                "涨跌幅": "pct_change",
+                "涨跌额": "change",
+                "成交量": "volume",
+                "成交额": "amount",
+                "振幅": "amplitude",
+                "换手率": "turnover",
+            },
+        }
+
+        mapping = column_map["1"] if period == "1" else column_map["default"]
+        df = raw_df.rename(columns=mapping)
+
+        if "timestamp" in df.columns:
+            df["timestamp"] = (
+                pd.to_datetime(df["timestamp"])
+                .dt.tz_localize("Asia/Shanghai")
+                .dt.tz_convert("UTC")
+            )
+
+        return self._select_standard_columns(df)
+
+    def _clean_data(self, raw_df: pd.DataFrame) -> pd.DataFrame:
+        """Cleans and standardizes daily and higher-level data, converting timestamps to UTC"""
+        column_map = {
+            "日期": "timestamp",
+            "开盘": "open",
+            "收盘": "close",
+            "最高": "high",
+            "最低": "low",
+            "成交量": "volume",
+        }
+
+        available_columns = {
+            src: target for src, target in column_map.items() if src in raw_df.columns
+        }
+
+        if not available_columns:
+            raise ValueError("Expected columns not found in raw data")
+
+        df = raw_df.rename(columns=available_columns)
+
+        if "timestamp" in df.columns:
+            df["timestamp"] = (
+                pd.to_datetime(df["timestamp"])
+                .dt.tz_localize("Asia/Shanghai")
+                .dt.tz_convert("UTC")
+            )
+
+        if "volume" in df.columns:
+            df["volume"] = df["volume"].astype("int64")
+
+        return self._select_standard_columns(df)
+
+    def _select_standard_columns(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Selects and orders the standard output columns"""
+        standard_columns = [
+            "timestamp",
+            "open",
+            "high",
+            "low",
+            "close",
+            "volume",
+        ]
+        return df[[col for col in standard_columns if col in df.columns]]

akshare_one/modules/historical/factory.py

@@ -0,0 +1,46 @@
+from .base import HistoricalDataProvider
+from .eastmoney import EastMoneyHistorical
+from .sina import SinaHistorical
+
+
+class HistoricalDataFactory:
+    """
+    Factory class for creating historical data providers
+    """
+
+    _providers = {
+        "eastmoney": EastMoneyHistorical,
+        "sina": SinaHistorical,
+    }
+
+    @classmethod
+    def get_provider(cls, provider_name: str, **kwargs) -> HistoricalDataProvider:
+        """
+        Get a historical data provider by name
+
+        Args:
+            provider_name: Name of the provider (e.g., 'eastmoney')
+            **kwargs: Additional arguments to pass to the provider's constructor
+
+        Returns:
+            HistoricalDataProvider: 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 historical data provider: {provider_name}")
+
+        return provider_class(**kwargs)
+
+    @classmethod
+    def register_provider(cls, name: str, provider_class: type):
+        """
+        Register a new historical 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/modules/historical/sina.py

@@ -0,0 +1,219 @@
+from cachetools import cached
+from .base import HistoricalDataProvider, validate_hist_data
+import akshare as ak
+import pandas as pd
+from ..cache import CACHE_CONFIG
+
+
+class SinaHistorical(HistoricalDataProvider):
+    """Adapter for Sina historical stock data API"""
+
+    @validate_hist_data
+    @cached(
+        cache=CACHE_CONFIG["hist_data_cache"],
+        key=lambda self: f"sina_hist_{self.symbol}_{self.interval}_{self.interval_multiplier}_{self.adjust}",
+    )
+    def get_hist_data(self) -> pd.DataFrame:
+        """Fetches Sina historical market data
+
+        Returns:
+            pd.DataFrame:
+                - timestamp
+                - open
+                - high
+                - low
+                - close
+                - volume
+        """
+        self.interval = self.interval.lower()
+        self._validate_interval_params(self.interval, self.interval_multiplier)
+
+        try:
+            stock = (
+                f"sh{self.symbol}"
+                if not self.symbol.startswith(("sh", "sz", "bj"))
+                else self.symbol
+            )
+
+            if self.interval == "minute":
+                df = self._get_minute_data(stock)
+            elif self.interval == "hour":
+                df = self._get_hour_data(stock)
+            else:
+                df = self._get_daily_plus_data(stock)
+
+            return df
+        except Exception as e:
+            raise ValueError(f"Failed to fetch historical data: {str(e)}")
+
+    def _get_minute_data(self, stock: str) -> pd.DataFrame:
+        """Fetches minute level data"""
+        raw_df = ak.stock_zh_a_minute(
+            symbol=stock,
+            period="1",
+            adjust=self._map_adjust_param(self.adjust),
+        )
+        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"{self.interval_multiplier}min")
+            .agg(
+                {
+                    "open": "first",
+                    "high": "max",
+                    "low": "min",
+                    "close": "last",
+                    "volume": "sum",
+                }
+            )
+            .reset_index()
+        )
+        return self._clean_minute_data(raw_df)
+
+    def _get_hour_data(self, stock: str) -> pd.DataFrame:
+        """Fetches hour level data"""
+        if self.interval_multiplier < 1:
+            raise ValueError("Hour interval multiplier must be >= 1")
+
+        raw_df = ak.stock_zh_a_minute(
+            symbol=stock,
+            period="60",
+            adjust=self._map_adjust_param(self.adjust),
+        )
+        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"{self.interval_multiplier}h")
+            .agg(
+                {
+                    "open": "first",
+                    "high": "max",
+                    "low": "min",
+                    "close": "last",
+                    "volume": "sum",
+                }
+            )
+            .reset_index()
+        )
+        return self._clean_minute_data(raw_df)
+
+    def _get_daily_plus_data(self, stock: str) -> pd.DataFrame:
+        """Fetches daily and higher-level data (day/week/month/year)"""
+        start_date = self._convert_date_format(self.start_date)
+        end_date = self._convert_date_format(self.end_date)
+
+        raw_df = ak.stock_zh_a_daily(
+            symbol=stock,
+            start_date=start_date,
+            end_date=end_date,
+            adjust=self._map_adjust_param(self.adjust),
+        )
+
+        if self.interval_multiplier > 1:
+            raw_df = self._resample_data(
+                raw_df, self.interval, self.interval_multiplier
+            )
+
+        return self._clean_data(raw_df)
+
+    def _validate_interval_params(self, interval: str, multiplier: int) -> None:
+        """Validates the validity of interval and multiplier"""
+        if interval not in self.get_supported_intervals():
+            raise ValueError(f"Unsupported interval parameter: {interval}")
+
+        if interval in ["minute", "hour"] and multiplier < 1:
+            raise ValueError(f"interval_multiplier for {interval} level must be ≥ 1")
+
+    def _convert_date_format(self, date_str: str) -> str:
+        """Converts date format from YYYY-MM-DD to YYYYMMDD"""
+        return date_str.replace("-", "") if "-" in date_str else date_str
+
+    def _map_adjust_param(self, adjust: str) -> str:
+        """Maps adjustment parameters to the required format"""
+        return adjust if adjust != "none" else ""
+
+    def _resample_data(
+        self, df: pd.DataFrame, interval: str, multiplier: int
+    ) -> pd.DataFrame:
+        """Resamples daily and higher-level data to the specified interval"""
+        freq_map = {
+            "day": f"{multiplier}D",
+            "week": f"{multiplier}W-MON",
+            "month": f"{multiplier}MS",
+            "year": f"{multiplier}AS-JAN",
+        }
+        freq = freq_map[interval]
+
+        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_minute_data(self, raw_df: pd.DataFrame) -> pd.DataFrame:
+        """Cleans and standardizes minute/hour level data, converting timestamps to UTC"""
+        column_map = {
+            "date": "timestamp",
+            "open": "open",
+            "high": "high",
+            "low": "low",
+            "close": "close",
+            "volume": "volume",
+        }
+
+        df = raw_df.rename(columns=column_map)
+
+        if "timestamp" in df.columns:
+            df["timestamp"] = (
+                pd.to_datetime(df["timestamp"])
+                .dt.tz_localize("Asia/Shanghai")
+                .dt.tz_convert("UTC")
+            )
+
+        return self._select_standard_columns(df)
+
+    def _clean_data(self, raw_df: pd.DataFrame) -> pd.DataFrame:
+        """Cleans and standardizes daily and higher-level data, converting timestamps to UTC"""
+        column_map = {
+            "date": "timestamp",
+            "open": "open",
+            "high": "high",
+            "low": "low",
+            "close": "close",
+            "volume": "volume",
+        }
+
+        df = raw_df.rename(columns=column_map)
+
+        if "timestamp" in df.columns:
+            df["timestamp"] = (
+                pd.to_datetime(df["timestamp"])
+                .dt.tz_localize("Asia/Shanghai")
+                .dt.tz_convert("UTC")
+            )
+
+        if "volume" in df.columns:
+            df["volume"] = df["volume"].astype("int64")
+
+        return self._select_standard_columns(df)
+
+    def _select_standard_columns(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Selects and orders the standard output columns"""
+        standard_columns = [
+            "timestamp",
+            "open",
+            "high",
+            "low",
+            "close",
+            "volume",
+        ]
+        return df[[col for col in standard_columns if col in df.columns]]

akshare_one/modules/insider/base.py

@@ -0,0 +1,78 @@
+from abc import ABC, abstractmethod
+import pandas as pd
+from typing import Optional
+
+
+def validate_insider_data(func):
+    """Decorator to validate insider trading 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 fields for insider trading data
+        required_fields = {
+            "symbol",
+            "issuer",
+            "name",
+            "transaction_date",
+            "transaction_shares",
+            "transaction_price_per_share",
+        }
+        if not required_fields.issubset(df.columns):
+            missing = required_fields - set(df.columns)
+            raise ValueError(f"Missing required fields: {missing}")
+
+        # Validate timestamp if present
+        if "transaction_date" in df.columns:
+            if not pd.api.types.is_datetime64_any_dtype(df["transaction_date"]):
+                raise ValueError("transaction_date must be datetime64 dtype")
+            if (
+                df["transaction_date"].dt.tz is None
+                or str(df["transaction_date"].dt.tz) != "UTC"
+            ):
+                raise ValueError("transaction_date must be in UTC timezone")
+
+        # Validate numeric fields
+        numeric_fields = {
+            "transaction_shares",
+            "transaction_price_per_share",
+            "transaction_value",
+            "shares_owned_before_transaction",
+            "shares_owned_after_transaction",
+        }
+        for field in numeric_fields & set(df.columns):
+            if not pd.api.types.is_numeric_dtype(df[field]):
+                raise ValueError(f"{field} must be numeric")
+
+        return df
+
+    return wrapper
+
+
+class InsiderDataProvider(ABC):
+    def __init__(self, symbol: Optional[str] = None) -> None:
+        self.symbol = symbol
+
+    @abstractmethod
+    def get_inner_trade_data(self, symbol: Optional[str] = None) -> pd.DataFrame:
+        """Fetches insider trade data
+
+        Returns:
+            pd.DataFrame:
+            - symbol: 股票代码
+            - issuer: 股票名称
+            - name: 变动人
+            - title: 董监高职务
+            - transaction_date: 变动日期(UTC时区)
+            - transaction_shares: 变动股数
+            - transaction_price_per_share: 成交均价
+            - shares_owned_after_transaction: 变动后持股数
+            - relationship: 与董监高关系
+            - is_board_director: 是否为董事会成员
+            - transaction_value: 交易金额(变动股数*成交均价)
+            - shares_owned_before_transaction: 变动前持股数
+        """
+        pass

akshare_one/modules/insider/factory.py

@@ -0,0 +1,44 @@
+from .xueqiu import XueQiuInsider
+from .base import InsiderDataProvider
+
+
+class InsiderDataFactory:
+    """
+    Factory class for creating insider data providers
+    """
+
+    _providers = {
+        "xueqiu": XueQiuInsider,
+    }
+
+    @classmethod
+    def get_provider(cls, provider_name: str, **kwargs) -> InsiderDataProvider:
+        """
+        Get an insider data provider by name
+
+        Args:
+            provider_name: Name of the provider (e.g., 'xueqiu')
+            **kwargs: Additional arguments to pass to the provider's constructor
+
+        Returns:
+            InsiderDataProvider: 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 insider data provider: {provider_name}")
+
+        return provider_class(**kwargs)
+
+    @classmethod
+    def register_provider(cls, name: str, provider_class: type):
+        """
+        Register a new insider data provider
+
+        Args:
+            name: Name to associate with this provider
+            provider_class: The provider class to register
+        """
+        cls._providers[name.lower()] = provider_class