neurostats-API 0.0.25rc1__py3-none-any.whl → 1.0.0rc1__py3-none-any.whl

neurostats_API/async_mode/db_extractors/seasonal/base.py

@@ -0,0 +1,159 @@
+from ..base import BaseDBExtractor
+from datetime import datetime
+import json
+import pandas as pd
+from pymongo import ASCENDING, DESCENDING
+from neurostats_API.async_mode.db import TWSEDBClient, USDBClient
+from neurostats_API.utils import StatsDateTime, StatsProcessor, NotSupportedError
+import yaml
+
+class AsyncBaseSeasonalDBExtractor(BaseDBExtractor):
+
+    def __init__(self, ticker, client):
+        super().__init__(ticker, client)
+
+        self.collection_name_map = self._get_collection_map()
+        self.collection_name = self._get_collection_name()
+        if (self.collection_name is None):
+            raise NotSupportedError(
+                    f"{self.__class__.__name__} only supports {list(self.collection_name_map.keys())}, got {self.zone} with ticker = \"{self.ticker}\""
+                )
+        self.collection = self.db_client.get_collection(
+                self.collection_name
+            )
+        
+        self.column_name_map = None
+
+        
+                
+    
+    async def query_data(
+        self, 
+        start_date = None,
+        end_date = None,
+        get_latest = False # 決定是否只取得最新一筆資料
+    ):
+        if (start_date is None):
+            start_date = "1991-01-01"
+        if (end_date is None):
+            end_date = self._get_today()
+        
+        start_year, start_season = self._get_year_and_season(
+            date = start_date
+        )
+        end_year, end_season = self._get_year_and_season(
+            date = end_date
+        )
+
+        query, projection, sort = self._prepare_query(
+            start_year,
+            start_season,
+            end_year,
+            end_season,
+            get_latest
+        )
+        cursor = self.collection.find(query, projection).sort(sort)
+
+        if (get_latest):
+            cursor = cursor.limit(1)
+
+        fetched_data = [data async for data in cursor]
+
+        return fetched_data
+
+    def _get_collection_name(self):
+        
+        return self.collection_name_map.get(self.zone, None)
+    
+    def _get_collection_map(self):
+        return {
+        "tw": "twse_seasonal_report",
+        "us": "us_fundamentals"
+    }
+    
+    def _prepare_query(
+        self,
+        start_year = None,
+        start_season = None,
+        end_year = None,
+        end_season = None,
+        get_latest = False
+    ):
+        chart_name = self.column_name_map.get(self.get_zone(), None)
+
+        query = {
+            "ticker": self.ticker
+        }
+
+        query = self._update_query_with_year_season(
+            query,
+            start_year,
+            start_season,
+            end_year,
+            end_season
+        )
+
+        projection = {
+            "_id": 0,
+            "ticker": 1,
+            "year": 1,
+            "season": 1,
+            chart_name: 1,
+        }
+        
+        if (get_latest):
+            sort = [
+                ("year", DESCENDING),
+                ("season", DESCENDING)
+            ]
+        else:
+            sort = [
+                ("year", ASCENDING),
+                ("season", ASCENDING)
+            ]
+
+        return query, projection, sort
+
+
+    def _get_year_and_season(self, date):
+            if (isinstance(date, str)):
+                date = datetime.strptime(date, "%Y-%m-%d")
+
+            year = date.year
+            month = date.month
+
+            season = (month - 1) // 3 + 1
+
+            return year, season
+    
+    def _update_query_with_year_season(
+        self, 
+        query, 
+        start_year, 
+        start_season, 
+        end_year, 
+        end_season
+    ):
+        if all(v is not None for v in [start_year, start_season]):
+            # 大於start_year條件
+            query.update({
+                "$or": [
+                    {"year": {"$gt": start_year}},
+                    {"year": start_year, "season": {"$gte": start_season}},
+                ]
+            })
+
+        if all(v is not None for v in [end_year, end_season]):
+            # 小於end_year條件
+            query.update({
+                "$and": query.get("$and", []) + [
+                    {
+                        "$or": [
+                            {"year": {"$lt": end_year}},
+                            {"year": end_year, "season": {"$lte": end_season}},
+                        ]
+                    }
+                ]
+            })
+        
+        return query

neurostats_API/async_mode/db_extractors/seasonal/cashflow.py

@@ -0,0 +1,10 @@
+from .base import AsyncBaseSeasonalDBExtractor
+
+class AsyncCashFlowExtractor(AsyncBaseSeasonalDBExtractor):
+    def __init__(self, ticker, client):
+        super().__init__(ticker, client)
+
+        self.column_name_map = {
+            'tw': "cash_flow",
+            'us': "cash_flow"
+        }

neurostats_API/async_mode/db_extractors/seasonal/profit_lose.py

@@ -0,0 +1,17 @@
+from .base import AsyncBaseSeasonalDBExtractor, StatsDateTime
+from datetime import datetime
+import json
+import pandas as pd
+from pymongo import ASCENDING, DESCENDING
+from neurostats_API.async_mode.db import TWSEDBClient, USDBClient
+from neurostats_API.utils import StatsDateTime, StatsProcessor
+import yaml
+
+class AsyncProfitLoseExtractor(AsyncBaseSeasonalDBExtractor):
+    def __init__(self, ticker, client):
+        super().__init__(ticker, client)
+
+        self.column_name_map = {
+            'tw': "profit_lose",
+            'us': "income_statement"
+        }

neurostats_API/async_mode/db_extractors/seasonal/tej.py

@@ -0,0 +1,87 @@
+from .base import AsyncBaseSeasonalDBExtractor
+from datetime import datetime
+from neurostats_API.utils import NotSupportedError
+from pymongo import ASCENDING
+
+
+class AsyncTEJSeasonalDBExtractor(AsyncBaseSeasonalDBExtractor):
+
+    def __init__(self, ticker, client, fetch_type='Q'):
+        super().__init__(ticker, client)
+
+        self.fetch_type = fetch_type
+
+        if (self.zone != 'tw'):
+            raise NotSupportedError(None)
+
+    async def query_data(self, start_date=None, end_date=None):
+        if (start_date is None):
+            start_date = "1991-01-01"
+        if (end_date is None):
+            end_date = self._get_today()
+
+        query, projection, sort = self._prepare_query(start_date, end_date)
+
+        cursor = self.collection.find(query, projection).sort(sort)
+
+        fetched_data = [data async for data in cursor]
+
+        return fetched_data
+
+    def _prepare_query(self, start_date, end_date):
+        start_date = self._transform_date(start_date)
+        end_date = self._transform_date(end_date)
+
+        query = {
+            "ticker": self.ticker,
+            "date": {
+                "$gte": start_date,
+                "$lte": end_date
+            }
+        }
+
+        projection = {
+            "_id": 0,
+            "year": 1,
+            "season": 1,
+            self.fetch_type: 1,
+        }
+
+        sorting = [("year", ASCENDING), ("season", ASCENDING)]
+
+        return query, projection, sorting
+
+    def _transform_date(self, date):
+        if (isinstance(date, str)):
+            try:
+                return datetime.strptime(date, "%Y-%m-%d")
+            except Exception as e:
+                raise ValueError(
+                    "date string format imcompatible, should be \"YYYY-MM-DD\""
+                )
+        elif (isinstance(date, datetime)):
+            return date
+        else:
+            raise ValueError(
+                "date type imcompatible, should be string(\"YYYY-MM-DD\") or datetime.datetime"
+            )
+
+
+class AsyncTEJFinanceStatementDBExtractor(AsyncTEJSeasonalDBExtractor):
+
+    def __init__(self, ticker, mongo_uri, fetch_type='Q'):
+        super().__init__(ticker, mongo_uri, fetch_type=fetch_type)
+
+    def _get_collection_map(self):
+        return {
+            'tw': "TEJ_finance_statement"
+        }
+    
+class AsyncTEJSelfSettlementDBExtractor(AsyncTEJSeasonalDBExtractor):
+    def __init__(self, ticker, mongo_uri, fetch_type='Q'):
+        super().__init__(ticker, mongo_uri, fetch_type=fetch_type)
+
+    def _get_collection_map(self):
+        return {
+            'tw': "TEJ_self_settlement"
+        }

neurostats_API/async_mode/factory/__init__.py

@@ -0,0 +1 @@
+from .extractor_factory import get_extractor

neurostats_API/async_mode/factory/extractor_factory.py

@@ -0,0 +1,168 @@
+from typing import Type, TypedDict, Optional
+from neurostats_API.async_mode.db_extractors import (
+    AsyncTEJDailyTechDBExtractor, AsyncYFDailyTechDBExtractor,
+    AsyncDailyValueDBExtractor, AsyncTEJDailyValueDBExtractor,
+    AsyncTWSEChipDBExtractor, AsyncTWSEMonthlyRevenueExtractor,
+    AsyncBalanceSheetExtractor, AsyncProfitLoseExtractor,
+    AsyncCashFlowExtractor, AsyncTEJFinanceStatementDBExtractor,
+    AsyncTEJSelfSettlementDBExtractor
+)
+from neurostats_API.utils import NotSupportedError
+
+
+class ExtractorConfig(TypedDict):
+    class_: Type
+    description: Optional[str]
+    default_kwargs: dict
+
+
+EXTRACTOR_MAP: dict[str, ExtractorConfig] = {
+    # TEJ 相關
+    "TEJ_finance_statement": {
+        "class_":
+        AsyncTEJFinanceStatementDBExtractor,
+        "default_kwargs": {
+            "fetch_type": "Q"
+        },
+        "description":
+        """
+        DB_collection: TEJ_finance_statement
+        對應TEJ的\"會計師簽證財務資料\"
+        """,
+    },
+    "TEJ_self_settlement": {
+        "class_":
+        AsyncTEJSelfSettlementDBExtractor,
+        "default_kwargs": {
+            "fetch_type": "Q"
+        },
+        "description":
+        """
+        DB_collection: TEJ_self_settlement
+        對應TEJ的\"公司自結數\"
+        """
+    },
+
+    # TWSE 本地DB
+    "DB_balance_sheet": {
+        "class_":
+        AsyncBalanceSheetExtractor,
+        "default_kwargs": {},
+        "description":
+        """
+        DB_collection: twse_seasonal_report(tw), us_fundamental(us)
+        對應TWSE的\"資產負債表\"與美股的\"Balance_Sheet\"
+        tw: 選取balance_sheet欄
+        us: 選取balance_sheet欄
+        """
+    },
+    "DB_profit_lose": {
+        "class_":
+        AsyncProfitLoseExtractor,
+        "default_kwargs": {},
+        "description":
+        """
+        DB_collection: twse_seasonal_report(tw), us_fundamental(us)
+        對應TWSE的\"損益表\"與美股的\"Income Statement\"
+        tw: 選取profit_lose欄
+        us: 選取income_statement欄
+        """
+    },
+    "DB_cash_flow": {
+        "class_":
+        AsyncCashFlowExtractor,
+        "default_kwargs": {},
+        "description":
+        """
+        DB_collection: twse_seasonal_report(tw), us_fundamental(us)
+        對應TWSE的\"金流表\"與美股的\"Cash Flow\"
+        tw: 選取cash_flow欄
+        us: 選取cash_flow欄
+        """
+    },
+
+    # tech
+    "YF_tech": {
+        "class_":
+        AsyncYFDailyTechDBExtractor,
+        "default_kwargs": {},
+        "description":
+        """
+        DB_collection: twse_daily_share_price(tw), us_tech(us)
+        開高低收
+        """
+    },
+    "TEJ_tech": {
+        "class_":
+        AsyncTEJDailyTechDBExtractor,
+        "default_kwargs": {},
+        "description":
+        """
+        DB_collection: TEJ_share_price
+        TEJ的開高低收
+        """
+    },
+
+    # Month Revenue
+    "TWSE_month_revenue": {
+        "class_":
+        AsyncTWSEMonthlyRevenueExtractor,
+        "default_kwargs": {},
+        "description":
+        """
+        DB_collection: twse_month_revenue
+        TWSE的月營收
+        """
+    },
+
+    # Chip
+    "TWSE_chip": {
+        "class_":
+        AsyncTWSEChipDBExtractor,
+        "default_kwargs": {
+            "fetch_type": "I"
+        },
+        "description":
+        """
+        DB_collection: twse_chip
+        TWSE的籌碼面
+        """
+    },
+
+    # Value
+    "TWSE_value": {
+        "class_":
+        AsyncDailyValueDBExtractor,
+        "default_kwargs": {},
+        "description":
+        """
+        DB_collection: twse_daily_share_price
+        TWSE的評價面
+        """
+    }
+}
+
+
+def get_extractor(collection: str, ticker: str, client, **override_kwargs):
+    """
+    collection: extractor對應的KEY_NAME,
+    ticker: 初始化extractor用的參數, 指定哪家公司
+    client: 初始化extractor用的參數, 連接的db_client
+    overide_kwargs: 除ticker與client外部分extractor會需要的參數，例如fetch_type
+    """
+
+    config = EXTRACTOR_MAP.get(collection, None)
+
+    if (config is None):
+        # 不存在的extractor name處理
+        valid = ", ".join(EXTRACTOR_MAP.keys())
+        raise NotSupportedError(
+            f"{collection} not a regular argument for collection, only {[valid]} available"
+        )
+
+    extractor_cls = config["class_"]
+    default_kwargs: dict = config["default_kwargs"]
+
+    init_kwargs = {**default_kwargs, **override_kwargs}    # 用後續的參數覆蓋
+
+    return extractor_cls(ticker, client, **init_kwargs)

neurostats_API/async_mode/factory/transformer_factory.py

@@ -0,0 +1,164 @@
+# 本模組提供各種財報、評價、籌碼等資料轉換器的工廠函式，根據 zone（如 "tw"、"us"）自動選擇對應的 Transformer 類別。
+# 若 zone 不支援則會拋出 NotSupportedError，方便統一管理與擴充。
+
+from typing import Type, TypedDict, Optional
+from neurostats_API.transformers import (
+    AgentOverviewTransformer,
+    TEJFinanceStatementTransformer,
+    TWSEAnnualValueTransformer,
+    TWSEBalanceSheetTransformer,
+    TWSECashFlowTransformer,
+    TWSEChipTransformer,
+    TWSEHistoryValueTransformer,
+    TWSEMonthlyRevenueTransformer,
+    TWSEProfitLoseTransformer,
+    USBalanceSheetTransformer,
+    USCashFlowTransformer,
+    USProfitLoseTransformer
+)
+from neurostats_API.utils import NotSupportedError
+
+
+def get_balance_sheet_transformer(zone):
+    """
+    取得資產負債表（Balance Sheet）對應地區的 Transformer 類別。
+    參數:
+        zone: "tw"（台灣）或 "us"（美國）
+    回傳:
+        對應的 Transformer 類別
+    """
+    transformer_map = {
+        "tw": TWSEBalanceSheetTransformer,
+        "us": USBalanceSheetTransformer
+    }
+    return _get_transformer_by_zone("Balance Sheet", zone, transformer_map)
+
+def get_cash_flow_transformer(zone):
+    """
+    取得現金流量表（Cash Flow）對應地區的 Transformer 類別。
+    參數:
+        zone: "tw" 或 "us"
+    回傳:
+        對應的 Transformer 類別
+    """
+    transformer_map = {
+        "tw": TWSECashFlowTransformer,
+        "us": USCashFlowTransformer
+    }
+    return _get_transformer_by_zone("Cash Flow", zone, transformer_map)
+
+def get_profit_lose_transformer(zone):
+    """
+    取得損益表（Profit Lose, 又稱 Income Statement）對應地區的 Transformer 類別。
+    參數:
+        zone: "tw" 或 "us"
+    回傳:
+        對應的 Transformer 類別
+    """
+
+    transformer_map = {
+        "tw": TWSEProfitLoseTransformer,
+        "us": USProfitLoseTransformer
+    }
+    return _get_transformer_by_zone("Profit Lose (a.k.a. Income Statement)", zone, transformer_map)
+
+def get_chip_transformer(zone):
+    """
+    取得籌碼面（Chip）對應地區的 Transformer 類別。
+    參數:
+        zone: "tw"
+    回傳:
+        對應的 Transformer 類別
+    """
+    transformer_map = {
+        "tw": TWSEChipTransformer
+    }
+    return _get_transformer_by_zone("Chip", zone, transformer_map)
+
+
+def get_monthly_revenue_transformer(zone):
+    """
+    取得月營收（Monthly Revenue）對應地區的 Transformer 類別。
+    參數:
+        zone: "tw"
+    回傳:
+        對應的 Transformer 類別
+    """
+    transformer_map = {
+        "tw": TWSEMonthlyRevenueTransformer
+    }
+    return _get_transformer_by_zone("MonthlyRevenue", zone, transformer_map)
+
+
+def get_annual_value_transformer(zone):
+    """
+    取得歷年評價面數值（Annual Value）對應地區的 Transformer 類別。
+    參數:
+        zone: "tw"
+    回傳:
+        對應的 Transformer 類別
+    """
+    transformer_map = {
+        "tw": TWSEAnnualValueTransformer
+    }
+    return _get_transformer_by_zone("AnnualValue", zone, transformer_map)
+
+
+def get_history_value_transformer(zone):
+    """
+    取得歷來評價面數值（History Value）對應地區的 Transformer 類別。
+    參數:
+        zone: "tw"
+    回傳:
+        對應的 Transformer 類別
+    """
+    transformer_map = {
+        "tw": TWSEHistoryValueTransformer
+    }
+    return _get_transformer_by_zone("HistoryValue", zone, transformer_map)
+
+
+def get_agent_overview_transformer(zone):
+    """
+    取得美股券商總覽（Agent Overview）對應地區的 Transformer 類別。
+    參數:
+        zone: "us"
+    回傳:
+        對應的 Transformer 類別
+    """
+    transformer_map = {
+        "us": AgentOverviewTransformer
+    }
+    return _get_transformer_by_zone("AgentOverview", zone, transformer_map)
+
+
+def get_tej_finance_statement_transformer(zone):
+    """
+    取得 TEJ 財報（TEJ Finance Statement）對應地區的 Transformer 類別。
+    參數:
+        zone: "tw"
+    回傳:
+        對應的 Transformer 類別
+    """
+    transformer_map = {
+        "tw": TEJFinanceStatementTransformer
+    }
+    return _get_transformer_by_zone("TEJFinanceStatement", zone, transformer_map)
+
+# === 共用內部工具 ===
+def _get_transformer_by_zone(name: str, zone: str, transformer_map: dict):
+    """
+    根據 zone 回傳對應的 Transformer 類別，若 zone 不支援則拋出 NotSupportedError。
+    參數:
+        name: 字串，Transformer 名稱（用於錯誤訊息）
+        zone: 地區代碼
+        transformer_map: dict，zone 對應的 Transformer 類別
+    回傳:
+        對應的 Transformer 類別
+    """
+    transformer = transformer_map.get(zone)
+    if not transformer:
+        raise NotSupportedError(
+            f"[transformer_factory] {name} Transformer only supports {list(transformer_map.keys())}, got '{zone}'"
+        )
+    return transformer

neurostats_API/async_mode/fetchers/__init__.py

@@ -0,0 +1,10 @@
+from .balance_sheet import AsyncBalanceSheetFetcher
+from .cash_flow import AsyncCashFlowFetcher
+from .finance_overview import AsyncFinanceOverviewFetcher, AsyncAgentOverviewFetcher
+from .tech import AsyncTechFetcher
+from .twse_institution import AsyncTWSEInstitutionFetcher
+from .twse_margin import AsyncTWSEMarginFetcher
+from .month_revenue import AsyncMonthlyRevenueFetcher
+from .profit_lose import AsyncProfitLoseFetcher
+from .value import AsyncTWSEStatsValueFetcher
+from .tej import AsyncTEJSeasonalFetcher

neurostats_API/async_mode/fetchers/balance_sheet.py

@@ -0,0 +1,31 @@
+from .base import AsyncBaseFetcher
+from ..db_extractors import AsyncBalanceSheetExtractor
+from neurostats_API.transformers import (
+    TWSEBalanceSheetTransformer, USBalanceSheetTransformer
+)
+from neurostats_API.async_mode.factory import get_extractor
+from neurostats_API.utils import NotSupportedError
+
+
+class AsyncBalanceSheetFetcher(AsyncBaseFetcher):
+
+    def __init__(self, ticker, client):
+        super().__init__()
+        self.ticker = ticker
+        self.transformer_map = {
+            "tw": TWSEBalanceSheetTransformer,
+            "us": USBalanceSheetTransformer
+        }
+        self.extractor = get_extractor("DB_balance_sheet", ticker, client)
+        company_name = self.extractor.get_company_name()
+        zone = self.extractor.get_zone()
+
+        transformer = self.get_transformer(zone)
+        self.transformer = transformer(ticker, company_name, zone)
+
+    async def query_data(self, start_date=None, end_date=None):
+        fetched_data = await self.extractor.query_data(start_date, end_date)
+
+        transformed_data = self.transformer.process_transform(fetched_data)
+
+        return transformed_data

neurostats_API/async_mode/fetchers/base.py

@@ -0,0 +1,48 @@
+import abc
+from datetime import datetime, timedelta, date
+import json
+import pandas as pd
+from pymongo import MongoClient
+import pytz
+from typing import Union
+from neurostats_API.utils import StatsDateTime, StatsProcessor, YoY_Calculator, NotSupportedError
+
+class AsyncBaseFetcher(abc.ABC):
+    """
+    Fetcher目的: 真正給其他使用者的接口
+    """
+    def __init__(self):
+        self.timezone = pytz.timezone("Asia/Taipei")
+        self.target_metric_dict = {
+            'value': ['value'],
+            'value_and_percentage': ['value', 'percentage'],
+            'percentage': ['percentage'],
+            'grand_total': ['grand_total'],
+            'grand_total_values': ['grand_total', 'grand_total_percentage'],
+            'grand_total_percentage': ['grand_total_percentage'],
+            'growth': [f'YoY_{i}' for i in [1, 3, 5, 10]],
+            'grand_total_growth': [f"YoY_{i}" for i in [1, 3, 5, 10]]
+        }
+        self.transformer_map = None
+    @ abc.abstractmethod
+    async def query_data(self):
+        """
+        user使用的接口
+        """
+        return NotImplementedError()
+    
+    @staticmethod
+    def str_to_datetime(self, date_str: str) -> StatsDateTime:
+        date = self.timezone.localize(datetime.strptime(date_str, "%Y-%m-%d"))
+        year, month, day = date.year, date.month, date.day
+        season = (month - 1) // 3 + 1
+        return StatsDateTime(date, year, month, day, season)
+    
+    def get_transformer(self, zone):
+        transformer = self.transformer_map.get(zone)
+        if (transformer is None):
+            raise NotSupportedError(
+                f"{self.__class__.__name__} get transformer failed: only supports {list(self.transformer_map.keys())}, got {zone}"
+            )
+        
+        return transformer