Added ak_equity_ownership

Author: shugaoye

openbb_akshare/models/equity_ownership.py

@@ -0,0 +1,71 @@
+"""AKShare Equity Ownership Model."""
+
+from datetime import (
+    date as dateType,
+    datetime,
+)
+from typing import Any, Dict, List, Optional
+
+from openbb_core.provider.abstract.fetcher import Fetcher
+from openbb_core.provider.standard_models.equity_ownership import (
+    EquityOwnershipData,
+    EquityOwnershipQueryParams,
+)
+from mysharelib.tools import most_recent_quarter
+from pydantic import field_validator
+
+
+class AKShareEquityOwnershipQueryParams(EquityOwnershipQueryParams):
+    """AKShare Equity Ownership Query.
+
+    Source: https://emweb.securities.eastmoney.com/PC_HSF10/ShareholderResearch/Index?type=web&code=SH688686#sdgd-0
+    """
+
+    @field_validator("date", mode="before", check_fields=True)
+    @classmethod
+    def time_validate(cls, v: str):
+        """Validate the date."""
+        if v is None:
+            v = dateType.today()
+        if isinstance(v, str):
+            base = datetime.strptime(v, "%Y-%m-%d").date()
+            return most_recent_quarter(base)
+        return most_recent_quarter(v)
+
+
+class AKShareEquityOwnershipData(EquityOwnershipData):
+    """AKShare Equity Ownership Data."""
+
+
+class AKShareEquityOwnershipFetcher(
+    Fetcher[
+        AKShareEquityOwnershipQueryParams,
+        List[AKShareEquityOwnershipData],
+    ]
+):
+    """Transform the query, extract and transform the data from the AKShare endpoints."""
+
+    @staticmethod
+    def transform_query(params: Dict[str, Any]) -> AKShareEquityOwnershipQueryParams:
+        """Transform the query params."""
+        return AKShareEquityOwnershipQueryParams(**params)
+
+    @staticmethod
+    def extract_data(
+        query: AKShareEquityOwnershipQueryParams,
+        credentials: Optional[Dict[str, str]],
+        **kwargs: Any,
+    ) -> List[Dict]:
+        """Return the raw data from the AKShare endpoint."""
+        from openbb_akshare.utils.ak_equity_ownership import stock_gdfx_top_10
+
+        return stock_gdfx_top_10(query.symbol, query.date).to_dict(orient="records")
+
+    @staticmethod
+    def transform_data(
+        query: AKShareEquityOwnershipQueryParams, data: List[Dict], **kwargs: Any
+    ) -> List[AKShareEquityOwnershipData]:
+        """Return the transformed data."""
+        own = [AKShareEquityOwnershipData.model_validate(d) for d in data]
+        own.sort(key=lambda x: x.filing_date, reverse=True)
+        return own

openbb_akshare/utils/ak_equity_ownership.py

@@ -0,0 +1,34 @@
+from datetime import (
+    date as dateType,
+    datetime,
+)
+import logging
+from openbb_akshare import project_name
+from mysharelib.tools import setup_logger, normalize_symbol
+from mysharelib.em.stock_hk_gdfx_em import stock_hk_gdfx_top_10_em
+
+setup_logger(project_name)
+logger = logging.getLogger(__name__)
+
+def stock_gdfx_top_10(symbol:str, date: dateType | str):
+    import akshare as ak
+
+    if isinstance(date, str):
+        # Assuming date format is 'YYYYMMDD'
+        try:
+            # Try parsing as 'YYYY-MM-DD'
+            date = datetime.strptime(date, "%Y%m%d")
+        except ValueError:
+            try:
+                # Try parsing as 'YYYY-MM-DD'
+                date = datetime.strptime(date, "%Y-%m-%d")
+            except ValueError:
+                raise ValueError("Invalid date format. Use 'YYYY-MM-DD' or 'YYYYMMDD'.")
+    
+    symbol_b, symbol_f, market = normalize_symbol(symbol)
+    if market == "HK":
+        return stock_hk_gdfx_top_10_em(symbol=symbol_f, date=date.strftime("%Y%m%d"))
+    elif market in ["SH", "SZ", "BJ"]:
+        return ak.stock_gdfx_free_top_10_em(symbol=f"sh{symbol_b}", date=date.strftime("%Y%m%d"))
+    else:
+        raise ValueError("Invalid market. Please use 'HK', 'SH', 'SZ', or 'BJ'.")

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "openbb-akshare"
-version = "0.7.8"
+version = "0.7.9"
 description = "AKShare extension for OpenBB"
 authors = ["Roger Ye <[email protected]>"]
 license = "AGPL-3.0-only"
@@ -9,7 +9,7 @@ packages = [{ include = "openbb_akshare" }]
 
 [tool.poetry.dependencies]
 python = ">=3.9.21,<3.13"
-akshare = "1.17.31"
+akshare = "1.17.39"
 openbb-core = { version = "^1.4.7" }
 mysharelib = "^0.4.5"
 ipywidgets = "^8.1.7"

tests/test_equity_ownership.py

@@ -0,0 +1,16 @@
+import pytest
+import pandas as pd
+import sqlite3
+from pathlib import Path
+from datetime import datetime, timezone
+from mysharelib.table_cache import TableCache
+from openbb_akshare.utils.fetch_equity_info import EQUITY_INFO_SCHEMA
+from openbb_akshare import project_name
+
+@pytest.mark.parametrize("symbol", ["00386", "600177"])
+
+def test_ak_equity_ownership(symbol, logger):
+    from openbb_akshare.utils.ak_equity_ownership import stock_gdfx_top_10
+    equity_owners_df = stock_gdfx_top_10(symbol, date="20250630")
+    logger.info(f"obb.equity.ownership:{symbol}, {equity_owners_df}")
+