akshare-one 0.2.0__tar.gz → 0.2.2__tar.gz

{akshare_one-0.2.0 → akshare_one-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akshare-one
-Version: 0.2.0
+Version: 0.2.2
 Summary: Standardized interface for Chinese financial market data, built on AKShare with unified data formats and simplified APIs
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/zwldarren/akshare-one
@@ -9,35 +9,35 @@ Keywords: akshare,financial-data,stock-data,quant
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: akshare>=1.16.94
-Requires-Dist: cachetools>=5.5.2
+Requires-Dist: akshare>=1.16.98
+Requires-Dist: cachetools>=6.0.0
 Dynamic: license-file
 
 <div align="center">
   <h1>AKShare One</h1>
   <div>
-    <strong>English</strong> | <a href="README_zh.md">中文</a>
+    <a href="README_zh.md">中文</a> | <strong>English</strong>
   </div>
 </div>
 
-**AKShare One** is a standardized interface for Chinese financial market data, built as a wrapper around [AKShare](https://github.com/akfamily/akshare) to solve inconsistencies in input/output formats across different data sources.
+**AKShare One** is a data interface for obtaining Chinese A-shares, based on [AKShare](https://github.com/akfamily/akshare). It aims to simplify AKShare's usage and unify input/output formats from different data sources, making it easier to pass data to LLM.
 
 ## ✨ Features
 
 - 📊 Unified stock code formats across data sources
 - 🏗️ Standardized return data structures
-- 🛠️ Simplified API parameters
+- 🛠️ Simplified API parameter design
 - ⏱️ Automatic timestamp and adjustment handling
 
 ## 🚀 Core Features
 
-| Feature | Interface |
-|---------|-----------|
+| Function | Interface |
+|------|------|
 | Historical data | `get_hist_data` |
 | Real-time quotes | `get_realtime_data` |
 | Stock news | `get_news_data` |
 | Financial data | `get_balance_sheet`/`get_income_statement`/`get_cash_flow` |
-| Insider trading | `get_inner_trade_data` |
+| Internal transactions | `get_inner_trade_data` |
 
 ## 📦 Quick Installation
 

{akshare_one-0.2.0 → akshare_one-0.2.2}/README.md

@@ -1,28 +1,28 @@
 <div align="center">
   <h1>AKShare One</h1>
   <div>
-    <strong>English</strong> | <a href="README_zh.md">中文</a>
+    <a href="README_zh.md">中文</a> | <strong>English</strong>
   </div>
 </div>
 
-**AKShare One** is a standardized interface for Chinese financial market data, built as a wrapper around [AKShare](https://github.com/akfamily/akshare) to solve inconsistencies in input/output formats across different data sources.
+**AKShare One** is a data interface for obtaining Chinese A-shares, based on [AKShare](https://github.com/akfamily/akshare). It aims to simplify AKShare's usage and unify input/output formats from different data sources, making it easier to pass data to LLM.
 
 ## ✨ Features
 
 - 📊 Unified stock code formats across data sources
 - 🏗️ Standardized return data structures
-- 🛠️ Simplified API parameters
+- 🛠️ Simplified API parameter design
 - ⏱️ Automatic timestamp and adjustment handling
 
 ## 🚀 Core Features
 
-| Feature | Interface |
-|---------|-----------|
+| Function | Interface |
+|------|------|
 | Historical data | `get_hist_data` |
 | Real-time quotes | `get_realtime_data` |
 | Stock news | `get_news_data` |
 | Financial data | `get_balance_sheet`/`get_income_statement`/`get_cash_flow` |
-| Insider trading | `get_inner_trade_data` |
+| Internal transactions | `get_inner_trade_data` |
 
 ## 📦 Quick Installation
 

{akshare_one-0.2.0 → akshare_one-0.2.2}/akshare_one/insider.py

@@ -3,19 +3,16 @@
 包含上市公司内部交易相关功能
 """
 
-from typing import Optional
 import pandas as pd
 from .modules.insider.factory import InsiderDataFactory
 
 
-def get_inner_trade_data(
-    symbol: Optional[str] = None, source: str = "xueqiu"
-) -> "pd.DataFrame":
+def get_inner_trade_data(symbol: str, source: str = "xueqiu") -> "pd.DataFrame":
     """获取雪球内部交易数据
 
     Args:
         source: 数据源 (目前支持 "xueqiu")
-        symbol: 可选股票代码，如"600000"，不传则返回所有数据
+        symbol: 股票代码，如"600000"
 
     Returns:
         pd.DataFrame:

akshare_one-0.2.2/akshare_one/modules/eastmoney/client.py

@@ -0,0 +1,88 @@
+import requests
+from typing import Dict, Any
+
+
+class EastMoneyClient:
+    """
+    A client for interacting directly with EastMoney's data APIs.
+    This class handles session management, request signing, and API calls.
+    """
+
+    def __init__(self):
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36",
+                "Referer": "https://quote.eastmoney.com/",
+                "Accept": "application/json, text/plain, */*",
+                "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+            }
+        )
+
+    def _get_security_id(self, symbol: str) -> str:
+        """
+        Converts a stock symbol to EastMoney's internal secid format.
+        e.g., '600519' -> '1.600519', '000001' -> '0.000001'
+        """
+        symbol = symbol.upper()
+        if symbol.startswith("SZ"):
+            market = "0"
+            code = symbol[2:]
+        elif symbol.startswith("SH"):
+            market = "1"
+            code = symbol[2:]
+        elif symbol.startswith("HK"):
+            market = "116"
+            code = symbol[2:]
+        elif len(symbol) == 6:
+            if symbol.startswith(("000", "001", "002", "003", "300")):
+                market = "0"
+            elif symbol.startswith(("600", "601", "603", "605", "688")):
+                market = "1"
+            else:
+                market = "0"  # Default to SZ for ambiguity
+            code = symbol
+        elif len(symbol) == 5:  # HK Market
+            market = "116"
+            code = symbol
+        else:
+            market = "0"
+            code = symbol
+        return f"{market}.{code}"
+
+    def fetch_historical_klines(
+        self, symbol: str, klt: str, fqt: str, start_date: str, end_date: str
+    ) -> Dict[str, Any]:
+        """
+        Fetches historical K-line (candlestick) data.
+        """
+        url = "https://push2his.eastmoney.com/api/qt/stock/kline/get"
+        secid = self._get_security_id(symbol)
+        params = {
+            "fields1": "f1,f2,f3,f4,f5,f6",
+            "fields2": "f51,f52,f53,f54,f55,f56,f57,f58,f59,f60,f61",
+            "klt": klt,
+            "fqt": fqt,
+            "secid": secid,
+            "beg": start_date,
+            "end": end_date,
+        }
+        response = self.session.get(url, params=params)
+        response.raise_for_status()
+        return response.json()
+
+    def fetch_realtime_quote(self, symbol: str) -> Dict[str, Any]:
+        """
+        Fetches real-time quote data for a single stock.
+        """
+        url = "https://push2.eastmoney.com/api/qt/stock/get"
+        secid = self._get_security_id(symbol)
+        params = {
+            "invt": "2",
+            "fltt": "2",
+            "fields": "f43,f57,f58,f169,f170,f46,f60,f44,f51,f168,f47,f164,f163,f116,f60,f45,f52,f50,f48,f167,f117,f71,f161,f49,f530",
+            "secid": secid,
+        }
+        response = self.session.get(url, params=params)
+        response.raise_for_status()
+        return response.json()

akshare_one-0.2.2/akshare_one/modules/eastmoney/utils.py

@@ -0,0 +1,104 @@
+import pandas as pd
+from typing import Dict, Any
+
+
+def parse_kline_data(data: Dict[str, Any]) -> pd.DataFrame:
+    """
+    Parses K-line data from the API response into a pandas DataFrame.
+    """
+    klines = data.get("data", {}).get("klines", [])
+    if not klines:
+        return pd.DataFrame(
+            columns=["timestamp", "open", "high", "low", "close", "volume"]
+        )
+
+    records = []
+    for kline in klines:
+        parts = kline.split(",")
+        if len(parts) >= 6:
+            records.append(
+                {
+                    "timestamp": parts[0],
+                    "open": float(parts[1]),
+                    "close": float(parts[2]),
+                    "high": float(parts[3]),
+                    "low": float(parts[4]),
+                    "volume": int(parts[5]),
+                }
+            )
+
+    df = pd.DataFrame(records)
+    if not df.empty:
+        df["timestamp"] = pd.to_datetime(df["timestamp"])
+        df["timestamp"] = (
+            df["timestamp"].dt.tz_localize("Asia/Shanghai").dt.tz_convert("UTC")
+        )
+        df = df[["timestamp", "open", "high", "low", "close", "volume"]]
+    return df
+
+
+def parse_realtime_data(data: Dict[str, Any]) -> pd.DataFrame:
+    """
+    Parses real-time quote data from the API response into a pandas DataFrame.
+    """
+    stock_data = data.get("data")
+    if not stock_data:
+        return pd.DataFrame()
+
+    df = pd.DataFrame(
+        [
+            {
+                "symbol": stock_data.get("f57"),
+                "price": stock_data.get("f43"),
+                "change": stock_data.get("f169"),
+                "pct_change": stock_data.get("f170"),
+                "volume": stock_data.get("f47"),
+                "amount": stock_data.get("f48"),
+                "open": stock_data.get("f46"),
+                "high": stock_data.get("f44"),
+                "low": stock_data.get("f45"),
+                "prev_close": stock_data.get("f60"),
+            }
+        ]
+    )
+    df["timestamp"] = pd.Timestamp.now(tz="Asia/Shanghai").tz_convert("UTC")
+    return df
+
+
+def resample_historical_data(
+    df: pd.DataFrame, interval: str, multiplier: int
+) -> pd.DataFrame:
+    """
+    Resamples historical data to a specified frequency.
+    """
+    if df.empty or multiplier <= 1:
+        return df
+
+    df = df.set_index("timestamp")
+
+    freq_map = {
+        "day": f"{multiplier}D",
+        "week": f"{multiplier}W-MON",
+        "month": f"{multiplier}MS",
+        "year": f"{multiplier * 12}MS",
+    }
+    freq = freq_map.get(interval)
+
+    if not freq:
+        return df.reset_index()
+
+    resampled = (
+        df.resample(freq)
+        .agg(
+            {
+                "open": "first",
+                "high": "max",
+                "low": "min",
+                "close": "last",
+                "volume": "sum",
+            }
+        )
+        .dropna()
+    )
+
+    return resampled.reset_index()

akshare_one-0.2.2/akshare_one/modules/financial/base.py

@@ -0,0 +1,22 @@
+from abc import ABC, abstractmethod
+import pandas as pd
+
+
+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-0.2.0 → akshare_one-0.2.2}/akshare_one/modules/financial/sina.py

@@ -3,7 +3,7 @@ import pandas as pd
 import akshare as ak
 
 from akshare_one.modules.cache import CACHE_CONFIG
-from .base import FinancialDataProvider, validate_financial_data
+from .base import FinancialDataProvider
 
 
 class SinaFinancialReport(FinancialDataProvider):
@@ -13,7 +13,6 @@ class SinaFinancialReport(FinancialDataProvider):
             f"sh{symbol}" if not symbol.startswith(("sh", "sz", "bj")) else symbol
         )
 
-    @validate_financial_data
     @cached(
         CACHE_CONFIG["financial_cache"],
         key=lambda self, symbol=None: f"sina_balance_{self.symbol}",
@@ -30,7 +29,6 @@ class SinaFinancialReport(FinancialDataProvider):
         raw_df = ak.stock_financial_report_sina(stock=self.stock, symbol="资产负债表")
         return self._clean_balance_data(raw_df)
 
-    @validate_financial_data
     @cached(
         CACHE_CONFIG["financial_cache"],
         key=lambda self, symbol=None: f"sina_income_{self.symbol}",
@@ -47,7 +45,6 @@ class SinaFinancialReport(FinancialDataProvider):
         raw_df = ak.stock_financial_report_sina(stock=self.stock, symbol="利润表")
         return self._clean_income_data(raw_df)
 
-    @validate_financial_data
     @cached(
         CACHE_CONFIG["financial_cache"],
         key=lambda self, symbol=None: f"sina_cash_{self.symbol}",

{akshare_one-0.2.0 → akshare_one-0.2.2}/akshare_one/modules/historical/base.py

@@ -2,31 +2,6 @@ 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,

{akshare_one-0.2.0 → akshare_one-0.2.2}/akshare_one/modules/historical/eastmoney.py

@@ -1,5 +1,5 @@
 from cachetools import cached
-from .base import HistoricalDataProvider, validate_hist_data
+from .base import HistoricalDataProvider
 import akshare as ak
 import pandas as pd
 from ..cache import CACHE_CONFIG
@@ -8,7 +8,6 @@ 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}",

akshare_one-0.2.2/akshare_one/modules/historical/eastmoney_direct.py

@@ -0,0 +1,79 @@
+import pandas as pd
+from cachetools import cached
+from .base import HistoricalDataProvider
+from ..cache import CACHE_CONFIG
+from ..eastmoney.client import EastMoneyClient
+from ..eastmoney.utils import parse_kline_data, resample_historical_data
+
+
+class EastMoneyDirectHistorical(HistoricalDataProvider):
+    """Direct implementation for EastMoney historical stock data API"""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.client = EastMoneyClient()
+
+    @cached(
+        cache=CACHE_CONFIG["hist_data_cache"],
+        key=lambda self: f"eastmoney_direct_hist_{self.symbol}_{self.interval}_{self.interval_multiplier}_{self.adjust}",
+    )
+    def get_hist_data(self) -> pd.DataFrame:
+        """Fetches EastMoney historical market data directly from API"""
+        self.interval = self.interval.lower()
+        self._validate_interval_params()
+
+        try:
+            klt = self._get_kline_type()
+            fqt = self._get_adjust_type()
+            start_date = self.start_date.replace("-", "")
+            end_date = self.end_date.replace("-", "")
+
+            raw_data = self.client.fetch_historical_klines(
+                symbol=self.symbol,
+                klt=klt,
+                fqt=fqt,
+                start_date=start_date,
+                end_date=end_date,
+            )
+
+            if raw_data.get("rc") != 0:
+                raise ValueError(f"API returned error: {raw_data.get('msg')}")
+
+            df = parse_kline_data(raw_data)
+
+            df = resample_historical_data(df, self.interval, self.interval_multiplier)
+
+            return df
+
+        except Exception as e:
+            raise ValueError(f"Failed to fetch historical data for {self.symbol}: {e}")
+
+    def _get_kline_type(self) -> str:
+        """Get K-line type based on interval."""
+        kline_map = {
+            "minute": "1",
+            "hour": "60",
+            "day": "101",
+            "week": "102",
+            "month": "103",
+            "year": "103",
+        }
+
+        base_klt = kline_map.get(self.interval, "101")
+
+        if self.interval == "minute" and self.interval_multiplier in [5, 15, 30, 60]:
+            return str(self.interval_multiplier)
+
+        return base_klt
+
+    def _get_adjust_type(self) -> str:
+        """Get adjustment type."""
+        adjust_map = {"none": "0", "qfq": "1", "hfq": "2"}
+        return adjust_map.get(self.adjust, "0")
+
+    def _validate_interval_params(self) -> None:
+        """Validates the interval and multiplier."""
+        if self.interval not in self.get_supported_intervals():
+            raise ValueError(f"Unsupported interval: {self.interval}")
+        if self.interval in ["minute", "hour"] and self.interval_multiplier < 1:
+            raise ValueError("Interval multiplier must be >= 1 for minute/hour.")

{akshare_one-0.2.0 → akshare_one-0.2.2}/akshare_one/modules/historical/factory.py

@@ -1,5 +1,6 @@
 from .base import HistoricalDataProvider
 from .eastmoney import EastMoneyHistorical
+from .eastmoney_direct import EastMoneyDirectHistorical
 from .sina import SinaHistorical
 
 
@@ -10,6 +11,7 @@ class HistoricalDataFactory:
 
     _providers = {
         "eastmoney": EastMoneyHistorical,
+        "eastmoney_direct": EastMoneyDirectHistorical,
         "sina": SinaHistorical,
     }
 

{akshare_one-0.2.0 → akshare_one-0.2.2}/akshare_one/modules/historical/sina.py

@@ -1,5 +1,5 @@
 from cachetools import cached
-from .base import HistoricalDataProvider, validate_hist_data
+from .base import HistoricalDataProvider
 import akshare as ak
 import pandas as pd
 from ..cache import CACHE_CONFIG
@@ -8,7 +8,6 @@ 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}",

akshare_one-0.2.2/akshare_one/modules/insider/base.py

@@ -0,0 +1,28 @@
+from abc import ABC, abstractmethod
+import pandas as pd
+
+
+class InsiderDataProvider(ABC):
+    def __init__(self, symbol: str) -> None:
+        self.symbol = symbol
+
+    @abstractmethod
+    def get_inner_trade_data(self) -> 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-0.2.0 → akshare_one-0.2.2}/akshare_one/modules/insider/xueqiu.py

@@ -1,7 +1,7 @@
 from cachetools import cached
 import pandas as pd
 import akshare as ak
-from .base import InsiderDataProvider, validate_insider_data
+from .base import InsiderDataProvider
 from ..utils import convert_xieqiu_symbol
 from ..cache import CACHE_CONFIG
 
@@ -9,7 +9,6 @@ from ..cache import CACHE_CONFIG
 class XueQiuInsider(InsiderDataProvider):
     """Provider for XueQiu insider trading data"""
 
-    @validate_insider_data
     @cached(
         cache=CACHE_CONFIG["financial_cache"],
         key=lambda self, symbol=None: f"xueqiu_insider_{symbol if symbol else 'all'}",

akshare_one-0.2.2/akshare_one/modules/news/base.py

@@ -0,0 +1,22 @@
+from abc import ABC, abstractmethod
+import pandas as pd
+
+
+class NewsDataProvider(ABC):
+    def __init__(self, symbol: str) -> None:
+        self.symbol = symbol
+
+    @abstractmethod
+    def get_news_data(self) -> pd.DataFrame:
+        """Fetches news data for given symbol
+
+        Returns:
+            pd.DataFrame:
+            - keyword: 关键词
+            - title: 新闻标题
+            - content: 新闻内容
+            - publish_time: 发布时间 (UTC)
+            - source: 文章来源
+            - url: 新闻链接
+        """
+        pass

{akshare_one-0.2.0 → akshare_one-0.2.2}/akshare_one/modules/news/eastmoney.py

@@ -3,11 +3,10 @@ import pandas as pd
 import akshare as ak
 
 from ..cache import CACHE_CONFIG
-from .base import NewsDataProvider, validate_news_data
+from .base import NewsDataProvider
 
 
 class EastMoneyNews(NewsDataProvider):
-    @validate_news_data
     @cached(
         CACHE_CONFIG["news_cache"],
         key=lambda self: f"eastmoney_news_{self.symbol}",

akshare_one-0.2.2/akshare_one/modules/realtime/base.py

@@ -0,0 +1,27 @@
+from abc import ABC, abstractmethod
+import pandas as pd
+
+
+class RealtimeDataProvider(ABC):
+    def __init__(self, symbol: str) -> None:
+        self.symbol = symbol
+
+    @abstractmethod
+    def get_current_data(self) -> pd.DataFrame:
+        """Fetches realtime market data
+
+        Returns:
+            pd.DataFrame:
+            - symbol: 股票代码
+            - price: 最新价
+            - change: 涨跌额
+            - pct_change: 涨跌幅(%)
+            - timestamp: 时间戳
+            - volume: 成交量(手)
+            - amount: 成交额(元)
+            - open: 今开
+            - high: 最高
+            - low: 最低
+            - prev_close: 昨收
+        """
+        pass

{akshare_one-0.2.0 → akshare_one-0.2.2}/akshare_one/modules/realtime/eastmoney.py

@@ -3,11 +3,10 @@ import pandas as pd
 import akshare as ak
 
 from ..cache import CACHE_CONFIG
-from .base import RealtimeDataProvider, validate_realtime_data
+from .base import RealtimeDataProvider
 
 
 class EastmoneyRealtime(RealtimeDataProvider):
-    @validate_realtime_data
     @cached(
         CACHE_CONFIG["realtime_cache"],
         key=lambda self, symbol=None: f"eastmoney_{symbol if symbol else 'all'}",