Merge pull request #10 from shugaoye/master

Added ak_equity_ownership

Author: finanalyzer

openbb_akshare/__init__.py

@@ -12,6 +12,7 @@
 from openbb_akshare.models.equity_quote import AKShareEquityQuoteFetcher
 from openbb_akshare.models.equity_historical import AKShareEquityHistoricalFetcher
 from openbb_akshare.models.equity_profile import AKShareEquityProfileFetcher
+from openbb_akshare.models.equity_screener import AKShareEquityScreenerFetcher
 from openbb_akshare.models.historical_dividends import AKShareHistoricalDividendsFetcher
 from openbb_akshare.models.income_statement import AKShareIncomeStatementFetcher
 from openbb_akshare.models.price_performance import AKSharePricePerformanceFetcher
@@ -21,9 +22,7 @@
 provider = Provider(
     name="akshare",
     description="Data provider for openbb-akshare.",
-    # Only add 'credentials' if they are needed.
-    # For multiple login details, list them all here.
-    # credentials=["api_key"],
+    credentials=["api_key"],
     website="https://akshare.akfamily.xyz/",
     # Here, we list out the fetchers showing what our provider can get.
     # The dictionary key is the fetcher's name, used in the `router.py`.
@@ -37,6 +36,7 @@
         "EquityQuote": AKShareEquityQuoteFetcher,
         "EquityHistorical": AKShareEquityHistoricalFetcher,
         "EquityInfo": AKShareEquityProfileFetcher,
+        "EquityScreener": AKShareEquityScreenerFetcher,
         "HistoricalDividends": AKShareHistoricalDividendsFetcher,
         "IncomeStatement": AKShareIncomeStatementFetcher,
         "PricePerformance": AKSharePricePerformanceFetcher,

openbb_akshare/models/balance_sheet.py

@@ -33,7 +33,6 @@ class AKShareBalanceSheetQueryParams(BalanceSheetQueryParams):
     limit: Optional[int] = Field(
         default=5,
         description=QUERY_DESCRIPTIONS.get("limit", ""),
-        le=5,
     )
     use_cache: bool = Field(
         default=True,
@@ -47,11 +46,24 @@ class AKShareBalanceSheetData(BalanceSheetData):
     __alias_dict__ = {
         "period_ending": "REPORT_DATE",
         "fiscal_period": "REPORT_TYPE",
-        "totalEquity": "TOTAL_EQUITY",
-        "totalDebt": "TOTAL_LIABILITIES",
-        "totalAssets": "TOTAL_ASSETS"
+        "股东权益": "TOTAL_EQUITY",
+        "总负债": "TOTAL_LIABILITIES",
+        "总资产": "TOTAL_ASSETS"
     }
 
+    总权益: Optional[float] = Field(
+        default=None,
+        description="总权益.",
+    )
+    负债总额: Optional[float] = Field(
+        default=None,
+        description="负债总额.",
+    )
+    总资产: Optional[float] = Field(
+        default=None,
+        description="总资产.",
+    )
+
     @field_validator("period_ending", mode="before", check_fields=False)
     @classmethod
     def date_validate(cls, v):  # pylint: disable=E0213
@@ -84,7 +96,10 @@ def extract_data(
         # pylint: disable=import-outside-toplevel
         em_df = get_data(query.symbol, query.period, query.use_cache)
 
-        return em_df.to_dict(orient="records")
+        if query.limit is None:
+            return em_df.to_dict(orient="records")
+        else:
+            return em_df.head(query.limit).to_dict(orient="records")
 
     @staticmethod
     def transform_data(

openbb_akshare/models/cash_flow.py

@@ -33,7 +33,6 @@ class AKShareCashFlowStatementQueryParams(CashFlowStatementQueryParams):
     limit: Optional[int] = Field(
         default=5,
         description=QUERY_DESCRIPTIONS.get("limit", ""),
-        le=5,
     )
     use_cache: bool = Field(
         default=True,
@@ -48,7 +47,22 @@ class AKShareCashFlowStatementData(CashFlowStatementData):
         "period_ending": "REPORT_DATE",
         "fiscal_period": "REPORT_TYPE",
         "reported_currency": "CURRENCY",
+        "营业性现金流": "NETCASH_OPERATE",
+        "投资性现金流": "NETCASH_INVEST",
+        "融资性现金流": "NETCASH_FINANCE",
     }
+    营业性现金流: Optional[float] = Field(
+        default=None,
+        description="营业性现金流.",
+    )
+    投资性现金流: Optional[float] = Field(
+        default=None,
+        description="投资性现金流.",
+    )
+    融资性现金流: Optional[float] = Field(
+        default=None,
+        description="融资性现金流.",
+    )
 
     @field_validator("period_ending", mode="before", check_fields=False)
     @classmethod
@@ -82,7 +96,10 @@ def extract_data(
         # pylint: disable=import-outside-toplevel
         em_df = get_data(query.symbol, query.period, query.use_cache)
 
-        return em_df.to_dict(orient="records")
+        if query.limit is None:
+            return em_df.to_dict(orient="records")
+        else:
+            return em_df.head(query.limit).to_dict(orient="records")
 
     @staticmethod
     def transform_data(

openbb_akshare/models/equity_historical.py

@@ -104,9 +104,10 @@ def extract_data(
     ) -> List[Dict]:
         """Return the raw data from the AKShare endpoint."""
         from openbb_akshare.utils.helpers import ak_download
+        api_key = credentials.get("akshare_api_key") if credentials else ""
 
         data = ak_download(symbol=query.symbol, start_date=query.start_date, end_date=query.end_date, 
-                           period="daily", use_cache=query.use_cache, adjust="")
+                           period="daily", use_cache=query.use_cache, api_key=api_key, adjust="")
 
         if data.empty:
             raise EmptyDataError()

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/models/equity_profile.py

@@ -3,7 +3,7 @@
 # pylint: disable=unused-argument
 
 from typing import Any, Dict, List, Optional
-from datetime import date as dateType
+from datetime import (date as dateType, datetime)
 
 from openbb_core.provider.abstract.fetcher import Fetcher
 from openbb_core.provider.standard_models.equity_info import (
@@ -29,10 +29,12 @@ class AKShareEquityProfileData(EquityInfoData):
     """AKShare Equity Profile Data."""
 
     __alias_dict__ = {
+        "公司名称": "org_name_cn",
+        "公司简介": "org_cn_introduction",
+        "主要范围": "main_operation_business",
+        "成立日期": "established_date",
+        "上市日期": "listed_date",
         "name": "org_name_en",
-        "org_short_name_cn": "quoteType",
-        "short_description": "main_operation_business",
-        "long_description": "org_cn_introduction",
         "ceo": "chairman",
         "company_url": "org_website",
         "business_address": "reg_address_cn",
@@ -43,9 +45,23 @@ class AKShareEquityProfileData(EquityInfoData):
         "employees": "staff_num",
         "sector": "affiliate_industry",
         "industry_category": "operating_scope",
-        "first_stock_price_date": "listed_date",
     }
 
+    公司名称: Optional[str] = Field(
+        description="Alias of org_name_cn.",
+        default=None,
+    )
+    公司简介: Optional[str] = Field(
+        description="Alias of org_name_cn.",
+        default=None,
+    )
+    主要范围: Optional[str] = Field(
+        description="Alias of org_name_cn.",
+        default=None,
+    )
+    上市日期: Optional[dateType|None] = Field(
+        default=None, description="Date of the establishment."
+    )
     org_name_cn: Optional[str] = Field(
         description="Chinese name of the asset.",
         default=None,
@@ -62,7 +78,7 @@ class AKShareEquityProfileData(EquityInfoData):
         description="The number of listed shares outstanding.",
         default=None,
     )
-    established_date: Optional[dateType] = Field(
+    established_date: Optional[dateType|None] = Field(
         default=None, description="Date of the establishment."
     )
     actual_issue_vol: Optional[int] = Field(
@@ -107,16 +123,20 @@ def validate_established_date(cls, v):
         # pylint: disable=import-outside-toplevel
         from datetime import timezone  # noqa
         from openbb_core.provider.utils.helpers import safe_fromtimestamp  # noqa
+        if pd.isna(v):
+            return None
 
         return safe_fromtimestamp(get_timestamp(v), tz=timezone.utc).date() if v else None
 
-    @field_validator("first_stock_price_date", mode="before", check_fields=False)
+    @field_validator("上市日期", mode="before", check_fields=False)
     @classmethod
     def validate_first_trade_date(cls, v):
         """Validate first stock price date."""
         # pylint: disable=import-outside-toplevel
         from datetime import timezone  # noqa
         from openbb_core.provider.utils.helpers import safe_fromtimestamp  # noqa
+        if pd.isna(v):
+            return None
 
         return safe_fromtimestamp(get_timestamp(v), tz=timezone.utc).date() if v else None
 
@@ -144,24 +164,26 @@ async def aextract_data(
         from openbb_core.provider.utils.errors import EmptyDataError
         from warnings import warn
 
+        api_key = credentials.get("akshare_api_key") if credentials else ""
+
         symbols = query.symbol.split(",")
         results = []
         messages: list = []
 
-        async def get_one(symbol):
+        async def get_one(symbol, api_key: str, use_cache: bool = True):
             from openbb_akshare.utils.fetch_equity_info import fetch_equity_info
             """Get the data for one ticker symbol."""
             try:
                 result: dict = {}
-                result = fetch_equity_info(symbol).to_dict(orient="records")[0]
+                result = fetch_equity_info(symbol, api_key=api_key, use_cache=use_cache).to_dict(orient="records")[0]
                 if result:
                     results.append(result)
             except Exception as e:
                 messages.append(
                     f"Error getting data for {symbol} -> {e.__class__.__name__}: {e}"
                 )
 
-        tasks = [get_one(symbol) for symbol in symbols]
+        tasks = [get_one(symbol, api_key=api_key, use_cache=query.use_cache) for symbol in symbols]
 
         await asyncio.gather(*tasks)