a6cca48fed
- Covered by data-persistence-service tests (db/api). - No references or compose entries.
89 lines
3.4 KiB
Python
89 lines
3.4 KiB
Python
from abc import ABC, abstractmethod
|
|
from typing import Any, Dict, List, Optional
|
|
|
|
class BaseDataProvider(ABC):
|
|
"""
|
|
Abstract base class for all financial data providers.
|
|
"""
|
|
|
|
def __init__(self, token: Optional[str] = None):
|
|
"""
|
|
Initializes the data provider, optionally with an API token.
|
|
|
|
:param token: API token for the data provider, if required.
|
|
"""
|
|
self.token = token
|
|
self._initialize()
|
|
|
|
def _initialize(self):
|
|
"""
|
|
Perform any necessary initialization, such as API client setup.
|
|
This method is called by the constructor.
|
|
"""
|
|
pass
|
|
|
|
@abstractmethod
|
|
async def get_stock_basic(self, stock_code: str) -> Optional[Dict[str, Any]]:
|
|
"""
|
|
Fetches basic company information for a given stock code.
|
|
|
|
:param stock_code: The stock identifier.
|
|
:return: A dictionary with basic company info, or None if not found.
|
|
"""
|
|
pass
|
|
|
|
@abstractmethod
|
|
async def get_daily_price(self, stock_code: str, start_date: str, end_date: str) -> List[Dict[str, Any]]:
|
|
"""
|
|
Fetches daily stock prices for a given period.
|
|
|
|
:param stock_code: The stock identifier.
|
|
:param start_date: The start date of the period (e.g., 'YYYYMMDD').
|
|
:param end_date: The end date of the period (e.g., 'YYYYMMDD').
|
|
:return: A list of dictionaries, each representing a day's price data.
|
|
"""
|
|
pass
|
|
|
|
@abstractmethod
|
|
async def get_financial_statements(self, stock_code: str, report_dates: List[str]) -> Dict[str, List[Dict[str, Any]]]:
|
|
"""
|
|
Fetches financial statements for a list of report dates and returns them
|
|
in a series format.
|
|
|
|
The series format is a dictionary where keys are metric names (e.g., 'revenue')
|
|
and values are a list of data points over time.
|
|
e.g., {"revenue": [{"year": "2023", "value": 1000}, ...]}
|
|
|
|
Providers should also calculate derived metrics if they are not directly available.
|
|
|
|
:param stock_code: The stock identifier.
|
|
:param report_dates: A list of report dates to fetch data for (e.g., ['20231231', '20221231']).
|
|
:return: A dictionary in series format.
|
|
"""
|
|
pass
|
|
|
|
async def get_financial_statement(self, stock_code: str, report_date: str) -> Optional[Dict[str, Any]]:
|
|
"""
|
|
Fetches a single financial statement for a specific report date.
|
|
This is a convenience method that can be implemented by calling get_financial_statements.
|
|
|
|
Note: The return value of this function is a single report (dictionary),
|
|
not a series object. This is for compatibility with parts of the code
|
|
that need a single flat report.
|
|
|
|
:param stock_code: The stock identifier.
|
|
:param report_date: The report date for the statement (e.g., '20231231').
|
|
:return: A dictionary with financial statement data, or None if not found.
|
|
"""
|
|
series_data = await self.get_financial_statements(stock_code, [report_date])
|
|
if not series_data:
|
|
return None
|
|
|
|
report: Dict[str, Any] = {"ts_code": stock_code, "end_date": report_date}
|
|
for metric, points in series_data.items():
|
|
for point in points:
|
|
if point.get("year") == report_date[:4]:
|
|
report[metric] = point.get("value")
|
|
break
|
|
return report
|