neurostats-API 0.0.14__py3-none-any.whl → 0.0.16__py3-none-any.whl

neurostats_API/__init__.py

@@ -1 +1,13 @@
-__version__='0.0.14'
+__version__='0.0.16'
+
+from .fetchers import (
+    BalanceSheetFetcher,
+    CashFlowFetcher,
+    FinanceOverviewFetcher,
+    FinanceReportFetcher,
+    InstitutionFetcher,
+    MarginTradingFetcher,
+    MonthRevenueFetcher,
+    TechFetcher,
+    ProfitLoseFetcher
+)

neurostats_API/fetchers/__init__.py

@@ -2,6 +2,8 @@ from .base import StatsDateTime, StatsFetcher
 from .balance_sheet import BalanceSheetFetcher
 from .cash_flow import CashFlowFetcher
 from .finance_overview import FinanceOverviewFetcher
+from .tej_finance_report import FinanceReportFetcher
+from .tech import TechFetcher
 from .institution import InstitutionFetcher
 from .margin_trading import MarginTradingFetcher
 from .month_revenue import MonthRevenueFetcher

neurostats_API/fetchers/base.py

@@ -1,16 +1,18 @@
+import abc
 from pymongo import MongoClient
 import pandas as pd
 import json
 import pytz
 from datetime import datetime, timedelta, date
-from ..utils import StatsDateTime, StatsProcessor
+from ..utils import StatsDateTime, StatsProcessor, YoY_Calculator
 import yaml
 
+
 class StatsFetcher:
+
     def __init__(self, ticker, db_client):
         self.ticker = ticker
-        self.db = db_client[
-            "company"]  # Replace with your database name
+        self.db = db_client["company"]    # Replace with your database name
         self.collection = self.db["twse_stats"]
 
         self.timezone = pytz.timezone("Asia/Taipei")
@@ -26,7 +28,6 @@ class StatsFetcher:
             'grand_total_growth': [f"YoY_{i}" for i in [1, 3, 5, 10]]
         }
 
-
     def prepare_query(self):
         return [
             {
@@ -37,7 +38,7 @@ class StatsFetcher:
         ]
 
     def collect_data(self, start_date, end_date):
-        pipeline = self.prepare_query(start_date, end_date)
+        pipeline = self.prepare_query()
 
         fetched_data = list(self.collection.aggregate(pipeline))
 
@@ -52,3 +53,102 @@ class StatsFetcher:
         season = (month - 1) // 3 + 1
 
         return StatsDateTime(date, year, month, day, season)
+
+
+class BaseTEJFetcher(abc.ABC):
+
+    def __init__(self):
+        self.client = None
+        self.db = None
+        self.collection = None
+
+    @abc.abstractmethod
+    def get(self):
+        pass
+
+    def get_latest_data_time(self, ticker):
+        latest_data = self.collection.find_one({"ticker": ticker}, {"last_update": 1, "_id": 0})
+
+        try:
+            latest_date = latest_data['last_update']["latest_data_date"]
+        except Exception as e:
+            latest_date = None
+
+        return latest_date
+
+    def cal_YoY(self, data_dict: dict, start_year: int, end_year: int, season: int):
+        year_shifts = [1, 3, 5, 10]
+        return_dict = {}
+        for year in range(start_year, end_year + 1):
+            year_data = data_dict[f"{year}Q{season}"]
+            year_keys = list(year_data.keys())
+            for key in year_keys:
+                if (key in 'season'):
+                    continue
+
+                if (isinstance(year_data[key], (int, float))):
+                    temp_dict = {"value": year_data[key]}
+
+                    for shift in year_shifts:
+                        this_value = year_data[key]
+                        try:
+                            past_year = str(year - shift)
+                            last_value = data_dict[f"{past_year}Q{season}"][key]
+                            temp_dict[f"YoY_{shift}"] = YoY_Calculator.cal_growth(this_value, last_value, delta=shift)
+                        except Exception as e:
+                            temp_dict[f"YoY_{shift}"] = None
+
+                    year_data[key] = temp_dict
+
+                else:
+                    year_data.pop(key)
+
+            return_dict[f"{year}Q{season}"] = year_data
+
+        return return_dict
+
+    def cal_QoQ(self, data_dict):
+        return_dict = {}
+        for i, time_index in enumerate(data_dict.keys()):
+            year, season = time_index.split("Q")
+            year = int(year)
+            season = int(season)
+            if (season == 1):
+                last_year = year - 1
+                last_season = 4
+            else:
+                last_year = year
+                last_season = season - 1
+
+            this_data = data_dict[time_index]
+            this_keys = list(this_data.keys())
+            for key in this_keys:
+                if (key in 'season'):
+                    continue
+
+                this_value = this_data[key]
+
+                if (isinstance(this_value, (int, float))):
+                    temp_dict = {"value": this_value}
+
+                    try:
+                        last_value = data_dict[f"{last_year}Q{last_season}"][key]['value']
+
+                        temp_dict['growth'] = YoY_Calculator.cal_growth(this_value, last_value, delta=1)
+                    except Exception as e:
+                        temp_dict['growth'] = None
+
+                    this_data[key] = temp_dict
+
+                else:
+                    this_data.pop(key)
+            return_dict[time_index] = this_data
+        return return_dict
+
+    def get_dict_of_df(self, data_dict):
+        """
+        dict[dict] -> dict[df]
+        """
+        for key in data_dict.keys():
+            data_dict[key] = pd.DataFrame.from_dict(data_dict[key])
+        return data_dict

neurostats_API/fetchers/tech.py

@@ -1,9 +1,16 @@
 from .base import StatsFetcher
 import pandas as pd
+import yfinance as yf
 
 class TechFetcher(StatsFetcher):
     
     def __init__(self, ticker:str, db_client):
+
+        """
+        The Capitalization-Weighted Index includes the following tickers:
+        ['GSPC', 'IXIC', 'DJI', 'TWII']   
+        """
+        
         super().__init__(ticker, db_client)
         self.full_ohlcv = self._get_ohlcv()
         self.basic_indexes = ['SMA5', 'SMA20', 'SMA60', 'EMA5', 'EMA20', 
@@ -40,16 +47,36 @@ class TechFetcher(StatsFetcher):
         )
 
     def _get_ohlcv(self):
-        query = {'ticker': self.ticker}
-        ticker_full = list(self.collection.find(query))
+        
+        if self.ticker in ['GSPC', 'IXIC', 'DJI', 'TWII']:
+            
+            full_tick = f'^{self.ticker}'
+            yf_ticker = yf.Ticker(full_tick)
+            origin_df = yf_ticker.history(period="10y")
+            origin_df = origin_df.reset_index()
+            origin_df["Date"] = pd.to_datetime(origin_df["Date"]).dt.date
+            df = origin_df.rename(
+                columns={
+                    "Date": "date",
+                    "Open": "open",
+                    "High": "high",
+                    "Low": "low",
+                    "Close": "close",
+                    "Volume": "volume"
+                }
+            )
+        else:
+
+            query = {'ticker': self.ticker}
+            ticker_full = list(self.collection.find(query))
 
-        if not ticker_full:
-            raise ValueError(f"No data found for ticker: {self.ticker}")
+            if not ticker_full:
+                raise ValueError(f"No data found for ticker: {self.ticker}")
 
-        if 'daily_data' not in ticker_full[0] or ticker_full[0]['daily_data'] is None:
-            raise KeyError("Missing 'daily_data' in the retrieved data")
+            if 'daily_data' not in ticker_full[0] or ticker_full[0]['daily_data'] is None:
+                raise KeyError("Missing 'daily_data' in the retrieved data")
 
-        df = pd.DataFrame(ticker_full[0]['daily_data'])
+            df = pd.DataFrame(ticker_full[0]['daily_data'])
 
         selected_cols = ['date','open','high','low','close','volume']
 

neurostats_API/fetchers/tej_finance_report.py

@@ -0,0 +1,339 @@
+from .base import BaseTEJFetcher
+from datetime import datetime
+from enum import Enum
+import pandas as pd
+from pymongo import MongoClient
+from ..utils import StatsProcessor, YoY_Calculator
+import warnings
+
+
+class FinanceReportFetcher(BaseTEJFetcher):
+
+    class FetchMode(Enum):
+        YOY = 1
+        QOQ = 2
+        YOY_NOCAL = 3
+        QOQ_NOCAL = 4
+
+    def __init__(self, mongo_uri, db_name="company", collection_name="TWN/AINVFQ1"):
+        self.client = MongoClient(mongo_uri)
+        self.db = self.client[db_name]
+        self.collection = self.db[collection_name]
+
+        # yapf: disabled
+        self.check_index = {
+            'coid', 'mdate', 'key3', 'no', 'sem', 'merg', 'curr', 'annd', 'fin_ind', 'bp11', 'bp21', 'bp22', 'bp31',
+            'bp41', 'bp51', 'bp53', 'bp61', 'bp62', 'bp63', 'bp64', 'bp65', 'bf11', 'bf12', 'bf21', 'bf22', 'bf41',
+            'bf42', 'bf43', 'bf44', 'bf45', 'bf99', 'bsca', 'bsnca', 'bsta', 'bscl', 'bsncl', 'bstl', 'bsse', 'bslse',
+            'debt', 'quick', 'ppe', 'ar', 'ip12', 'ip22', 'ip31', 'ip51', 'iv41', 'if11', 'isibt', 'isni', 'isnip',
+            'eps', 'ispsd', 'gm', 'opi', 'nri', 'ri', 'nopi', 'ebit', 'cip31', 'cscfo', 'cscfi', 'cscff', 'person',
+            'shares', 'wavg', 'taxrate', 'r104', 'r115', 'r105', 'r106', 'r107', 'r108', 'r201', 'r112', 'r401', 'r402',
+            'r403', 'r404', 'r405', 'r408', 'r409', 'r410', 'r502', 'r501', 'r205', 'r505', 'r517', 'r512', 'r509',
+            'r608', 'r616', 'r610', 'r607', 'r613', 'r612', 'r609', 'r614', 'r611', 'r307', 'r304', 'r305', 'r306',
+            'r316', 'r834'
+        }    # yapf: enabled
+
+    def get(
+            self,
+            ticker,
+            fetch_mode: FetchMode = FetchMode.QOQ_NOCAL,
+            start_date: str = None,
+            end_date: str = None,
+            report_type: str = "Q",
+            indexes: list = []):
+        """
+        基礎的query function
+        ticker(str): 股票代碼
+        start_date(str):  開頭日期範圍
+        end_date(str):  = 結束日期範圍
+        report_type(str): 報告型態 {"A", "Q", "TTM"}  
+        fetch_mode(class FetchMode): 
+           YoY : 起始日期到結束日期範圍內，特定該季的資料
+           QoQ : 起始日期到結束日期內，每季的資料(與上一季成長率)
+        indexes(List): 指定的index
+        """
+        # 確認indexes中是否有錯誤的index，有的話回傳warning
+        if (indexes and self.check_index):
+            indexes = set(indexes)
+            difference = indexes - self.check_index
+            if (difference):
+                warnings.warn(f"{list(difference)} 沒有出現在資料表中，請確認column名稱是否正確", UserWarning)
+
+        if (fetch_mode in {self.FetchMode.QOQ, self.FetchMode.QOQ_NOCAL}):
+            if (not start_date):
+                warnings.warn("No start_date specified, use default date = \"2005-01-01\"", UserWarning)
+                start_date = datetime.strptime("2005-01-01", "%Y-%m-%d")
+            if (not end_date):
+                warnings.warn("No end_date specified, use default date = today", UserWarning)
+                end_date = datetime.today()
+
+            assert (start_date <= end_date)
+            start_date = datetime.strptime(start_date, "%Y-%m-%d")
+            end_date = datetime.strptime(end_date, "%Y-%m-%d")
+
+            start_year = start_date.year
+            start_season = (start_date.month - 1) // 4 + 1
+            end_year = end_date.year
+            end_season = (end_date.month - 1) // 4 + 1
+
+            if (fetch_mode == self.FetchMode.QOQ):
+                use_cal = True
+            else:
+                use_cal = False
+
+            data_df = self.get_QoQ_data(
+                ticker=ticker,
+                start_year=start_year,
+                start_season=start_season,
+                end_year=end_year,
+                end_season=end_season,
+                report_type=report_type,
+                indexes=indexes,
+                use_cal=use_cal)
+
+            return data_df
+
+        elif (fetch_mode in {self.FetchMode.YOY, self.FetchMode.YOY_NOCAL}):
+            start_date = datetime.strptime(start_date, "%Y-%m-%d")
+            start_year = start_date.year
+            end_date = self.get_latest_data_time(ticker)
+            if (not end_date):
+                end_date = datetime.today()
+
+            end_year = end_date.year
+            season = (end_date.month - 1) // 4 + 1
+
+            if (fetch_mode == self.FetchMode.YOY):
+                use_cal = True
+            else:
+                use_cal = False
+
+            data_df = self.get_YoY_data(
+                ticker=ticker,
+                start_year=start_year,
+                end_year=end_year,
+                season=season,
+                report_type=report_type,
+                indexes=indexes,
+                use_cal=use_cal)
+
+            return data_df
+
+    def get_QoQ_data(
+            self, ticker, start_year, start_season, end_year, end_season, report_type="Q", indexes=[], use_cal=False):
+        """
+            取得時間範圍內每季資料
+        """
+        if (use_cal):
+            if (start_season == 1):
+                lower_bound_year = start_year - 1
+                lower_bound_season = 4
+
+            else:
+                lower_bound_year = start_year
+                lower_bound_season = start_season - 1
+
+        else:
+            lower_bound_year = start_year,
+            lower_bound_season = start_season
+
+        if (not indexes):    # 沒有指定 -> 取全部
+            pipeline = [
+                {
+                    "$match": {
+                        "ticker": ticker
+                    }
+                }, {
+                    "$unwind": "$data"
+                }, {
+                    "$match":
+                        {
+                            "$or":
+                                [
+                                    {
+                                        "data.year": {
+                                            "$gt": start_year,
+                                            "$lt": end_year
+                                        }
+                                    }, {
+                                        "data.year": start_year,
+                                        "data.season": {
+                                            "$gte": start_season
+                                        }
+                                    }, {
+                                        "data.year": end_year,
+                                        "data.season": {
+                                            "$lte": end_season
+                                        }
+                                    }, {
+                                        "data.year": lower_bound_year,
+                                        "data.season": lower_bound_season
+                                    }
+                                ]
+                        }
+                }, {
+                    "$project": {
+                        "data.year": 1,
+                        "data.season": 1,
+                        f"data.{report_type}": 1,
+                        "_id": 0
+                    }
+                }
+            ]
+
+        else:    # 取指定index
+            project_stage = {"data.year": 1, "data.season": 1}
+            for index in indexes:
+                project_stage[f"data.{report_type}.{index}"] = 1
+
+            pipeline = [
+                {
+                    "$match": {
+                        "ticker": ticker
+                    }
+                }, {
+                    "$unwind": "$data"
+                }, {
+                    "$match":
+                        {
+                            "$or":
+                                [
+                                    {
+                                        "data.year": {
+                                            "$gt": start_year,
+                                            "$lt": end_year
+                                        }
+                                    }, {
+                                        "data.year": start_year,
+                                        "data.season": {
+                                            "$gte": start_season
+                                        }
+                                    }, {
+                                        "data.year": end_year,
+                                        "data.season": {
+                                            "$lte": end_season
+                                        }
+                                    }, {
+                                        "data.year": lower_bound_year,
+                                        "data.season": lower_bound_season
+                                    }
+                                ]
+                        }
+                }, {
+                    "$project": project_stage
+                }
+            ]
+
+        fetched_data = self.collection.aggregate(pipeline).to_list()
+
+        data_dict = StatsProcessor.list_of_dict_to_dict(
+            fetched_data, keys=["year", "season"], delimeter="Q", data_key=report_type)
+
+        if (use_cal):
+            data_with_QoQ = self.cal_QoQ(data_dict)
+            data_df = pd.DataFrame.from_dict(data_with_QoQ)
+            data_df = data_df.iloc[:, 1:]
+            data_df = data_df.iloc[:, ::-1].T
+            data_dict = data_df.to_dict()
+            data_dict = self.get_dict_of_df(data_dict)
+            return data_dict
+        else:
+            data_df = pd.DataFrame.from_dict(data_dict)
+            data_df = data_df.iloc[:, ::-1]
+            return data_df
+
+    def get_YoY_data(self, ticker, start_year, end_year, season, report_type="Q", indexes=[], use_cal=False):
+        """
+        取得某季歷年資料
+        """
+        if (use_cal):
+            select_year = set()
+
+            for year in range(start_year, end_year + 1):
+                year_shifts = {year, year - 1, year - 3, year - 5, year - 10}
+
+                select_year = select_year.union(year_shifts)
+
+            select_year = sorted(list(select_year), reverse=True)
+        else:
+            select_year = [year for year in range(start_year, end_year + 1)]
+
+        if (not indexes):    # 沒有指定 -> 取全部
+            pipeline = [
+                {
+                    "$match": {
+                        "ticker": ticker
+                    }
+                }, {
+                    "$unwind": "$data"
+                }, {
+                    "$match":
+                        {
+                            "$or": [{
+                                "$and": [{
+                                    "data.year": {
+                                        "$in": select_year
+                                    }
+                                }, {
+                                    "data.season": {
+                                        "$eq": season
+                                    }
+                                }]
+                            },]
+                        }
+                }, {
+                    "$project": {
+                        "data.year": 1,
+                        "data.season": 1,
+                        f"data.{report_type}": 1,
+                        "_id": 0
+                    }
+                }
+            ]
+
+        else:    # 取指定index
+            project_stage = {"data.year": 1, "data.season": 1}
+            for index in indexes:
+                project_stage[f"data.{report_type}.{index}"] = 1
+
+            pipeline = [
+                {
+                    "$match": {
+                        "ticker": ticker
+                    }
+                }, {
+                    "$unwind": "$data"
+                }, {
+                    "$match": {
+                        "$and": [{
+                            "data.year": {
+                                "$in": select_year
+                            }
+                        }, {
+                            "data.season": {
+                                "$eq": season
+                            }
+                        }]
+                    }
+                }, {
+                    "$project": project_stage
+                }
+            ]
+
+        fetched_data = self.collection.aggregate(pipeline).to_list()
+
+        # 處理計算YoY
+        data_dict = StatsProcessor.list_of_dict_to_dict(
+            fetched_data, keys=['year', 'season'], data_key=report_type, delimeter='Q')
+
+        if (use_cal):
+            data_with_YoY = self.cal_YoY(data_dict, start_year, end_year, season)
+            data_df = pd.DataFrame.from_dict(data_with_YoY)
+            data_df = data_df.iloc[:, ::-1].T
+            data_dict = data_df.to_dict()
+            data_dict = self.get_dict_of_df(data_dict)
+            return data_dict
+        else:
+            data_df = pd.DataFrame.from_dict(data_dict)
+            data_df = data_df.iloc[:, ::-1]
+            return data_df

neurostats_API/fetchers/value_invest.py

@@ -12,51 +12,68 @@ class ValueFetcher(StatsFetcher):
     def prepare_query(self, start_date, end_date):
         pipeline = super().prepare_query()
 
-        pipeline.append({
-            "$project": {
-                "_id": 0,
-                "ticker": 1,
-                "company_name": 1,
-                "daily_data": {
-                    "$map": {
-                        "input": {
-                            "$filter": {
-                                "input": "$daily_data",
-                                "as": "daily",
-                                "cond": {
-                                    "$and": [{
-                                        "$gte": ["$$daily.date", start_date]
-                                    }, {
-                                        "$lte": ["$$daily.date", end_date]
-                                    }]
-                                }
-                            }
-                        },
-                        "as": "daily_item",
-                        "in": {
-                            "date": "$$daily_item.date",
-                            "close": "$$daily_item.close",
-                            "P_B": "$$daily_item.P_B",
-                            "P_E": "$$daily_item.P_E",
-                            "P_FCF": "$$daily_item.P_FCF",
-                            "P_S": "$$daily_item.P_S",
-                            "EV_OPI": "$$daily_item.EV_OPI",
-                            "EV_EBIT": "$$daily_item.EV_EBIT",
-                            "EV_EBITDA": "$$daily_item.EV_EBITDA",
-                            "EV_S": "$$daily_item.EV_S"
-                        }
+        pipeline.append(
+            {
+                "$project":
+                    {
+                        "_id": 0,
+                        "ticker": 1,
+                        "company_name": 1,
+                        "daily_data":
+                            {
+                                "$map":
+                                    {
+                                        "input":
+                                            {
+                                                "$filter":
+                                                    {
+                                                        "input": "$daily_data",
+                                                        "as": "daily",
+                                                        "cond":
+                                                            {
+                                                                "$and":
+                                                                    [
+                                                                        {
+                                                                            "$gte": ["$$daily.date", start_date]
+                                                                        }, {
+                                                                            "$lte": ["$$daily.date", end_date]
+                                                                        }
+                                                                    ]
+                                                            }
+                                                    }
+                                            },
+                                        "as": "daily_item",
+                                        "in":
+                                            {
+                                                "date": "$$daily_item.date",
+                                                "close": "$$daily_item.close",
+                                                "P_B": "$$daily_item.P_B",
+                                                "P_E": "$$daily_item.P_E",
+                                                "P_FCF": "$$daily_item.P_FCF",
+                                                "P_S": "$$daily_item.P_S",
+                                                "EV_OPI": "$$daily_item.EV_OPI",
+                                                "EV_EBIT": "$$daily_item.EV_EBIT",
+                                                "EV_EBITDA": "$$daily_item.EV_EBITDA",
+                                                "EV_S": "$$daily_item.EV_S"
+                                            }
+                                    }
+                            },
+                        "yearly_data": 1
                     }
-                },
-                "yearly_data": 1
-            }
-        })
+            })
 
         return pipeline
 
+    def collect_data(self, start_date, end_date):
+        pipeline = self.prepare_query(start_date, end_date)
+
+        fetched_data = list(self.collection.aggregate(pipeline))
+
+        return fetched_data[0]
+
     def query_data(self):
         try:
-            latest_time = StatsDateTime.get_latest_time(
-                self.ticker, self.collection)['last_update_time']
+            latest_time = StatsDateTime.get_latest_time(self.ticker, self.collection)['last_update_time']
             target_year = latest_time['daily_data']['last_update'].year
             start_date = latest_time['daily_data']['last_update'] - timedelta(days=31)
             end_date = latest_time['daily_data']['last_update']
@@ -79,7 +96,7 @@ class ValueFetcher(StatsFetcher):
         )
 
         return fetched_data
-    
+
     def query_value_serie(self):
         """
         回傳指定公司的歷來評價
@@ -104,28 +121,32 @@ class ValueFetcher(StatsFetcher):
                 }
             },
             {
-                "$project": {
-                    "_id": 0,
-                    "ticker": 1,
-                    "company_name": 1,
-                    "daily_data": {
-                        "$map": {
-                            "input": "$daily_data",  # 正確地指定要處理的陣列
-                            "as": "daily",  # 每個元素的名稱
-                            "in": {
-                                "date": "$$daily.date",
-                                "P_E": "$$daily.P_E",
-                                "P_FCF": "$$daily.P_FCF",
-                                "P_B": "$$daily.P_B",
-                                "P_S": "$$daily.P_S",
-                                "EV_OPI": "$$daily.EV_OPI",
-                                "EV_EBIT": "$$daily.EV_EBIT",
-                                "EV_EBITDA": "$$daily.EV_EBITDA",
-                                "EV_S": "$$daily.EV_S"
+                "$project":
+                    {
+                        "_id": 0,
+                        "ticker": 1,
+                        "company_name": 1,
+                        "daily_data":
+                            {
+                                "$map":
+                                    {
+                                        "input": "$daily_data",    # 正確地指定要處理的陣列
+                                        "as": "daily",    # 每個元素的名稱
+                                        "in":
+                                            {
+                                                "date": "$$daily.date",
+                                                "P_E": "$$daily.P_E",
+                                                "P_FCF": "$$daily.P_FCF",
+                                                "P_B": "$$daily.P_B",
+                                                "P_S": "$$daily.P_S",
+                                                "EV_OPI": "$$daily.EV_OPI",
+                                                "EV_EBIT": "$$daily.EV_EBIT",
+                                                "EV_EBITDA": "$$daily.EV_EBITDA",
+                                                "EV_S": "$$daily.EV_S"
+                                            }
+                                    }
                             }
-                        }
                     }
-                }
             }
         ]
 
@@ -133,21 +154,17 @@ class ValueFetcher(StatsFetcher):
         fetched_data = fetched_data[0]
 
         value_keys = ["P_E", "P_FCF", "P_B", "P_S", "EV_OPI", "EV_EBIT", "EV_EVITDA", "EV_S"]
-        return_dict = {
-            value_key: dict() for value_key in value_keys
-        }
+        return_dict = {value_key: dict() for value_key in value_keys}
 
         for value_key in value_keys:
             for data in fetched_data['daily_data']:
                 if (value_key not in data.keys()):
                     continue
                 else:
-                    return_dict[value_key].update({
-                        data['date']: data[value_key] 
-                    })
+                    return_dict[value_key].update({data['date']: data[value_key]})
 
         return_dict = {
-            value_key: pd.DataFrame.from_dict(value_dict, orient = 'index', columns = [value_key])
+            value_key: pd.DataFrame.from_dict(value_dict, orient='index', columns=[value_key])
             for value_key, value_dict in return_dict.items()
         }
         return return_dict

neurostats_API/utils/__init__.py

@@ -1,4 +1,5 @@
 from .datetime import StatsDateTime
 from .db_client import DBClient
 from .data_process import StatsProcessor
-from .fetcher import StatsFetcher
+from .fetcher import StatsFetcher
+from .calculate_value import YoY_Calculator

neurostats_API/utils/calculate_value.py

@@ -0,0 +1,26 @@
+class YoY_Calculator:
+    def __init__(self):
+        pass
+
+    @classmethod
+    def cal_growth(cls, target_value: float, past_value: float, delta: int):
+        """
+        計算成長率以及年化成長率
+        target_value: float，這個時間的數值
+        past_value: float，過去的這個時間數值
+        delta: int，代表隔了幾年/季 delta > 1 時改以年化成長率計算
+        """
+        try:
+            if (delta > 1):
+                YoY = ((target_value / past_value)**(1 / delta)) - 1
+
+            else:
+                YoY = ((target_value - past_value) / past_value)
+
+        except Exception as e:
+            return None
+
+        if (isinstance(YoY, complex)): # 年化成長率有複數問題
+            return None
+
+        return YoY

neurostats_API/utils/data_process.py

@@ -20,7 +20,6 @@ class StatsProcessor:
     """
     1. 讀檔: txt / yaml
     2. 將巢狀dictionary / DataFrame扁平化
-
     """
 
     @classmethod
@@ -215,3 +214,59 @@ class StatsProcessor:
             return int(np.round(value).item())
         else:
             return value
+    
+    @classmethod
+    def list_of_dict_to_dict(
+        cls,
+        data_list: list,
+        key: str = "",
+        keys: list = [],
+        delimeter: str = "_",
+        data_key: str = "Q"
+    ):
+        """
+        TEJ DB 用
+        List[Dict] -> Dict[Dict]
+        input:
+        data_list(List):
+            [
+                { "data":
+                    {
+                        "year": 2021...
+                        "season": 1,
+                        "Q": {}...
+                        
+                    }
+                }
+            ]
+        
+        key(str): 選擇哪一個key作為轉化後的index
+        delimeter(str): 多個key時要用甚麼分隔
+        return: 
+        {
+            "2021" : {# Q下的資料} ...
+        }
+
+        or  (keys = ['year', 'season'])
+        {
+            "2021Q2" : {}
+        }
+        """
+        assert (key or keys), "func list_of_dict_to_dict must have argument \"key\" or \"keys\""
+
+        return_dict = {}
+        if (key):
+            keys = [key]
+        for data in data_list:
+            data = data['data']
+
+            pop_keys = []
+
+            for key in keys:
+                assert (key in data.keys())
+                pop_keys.append(str(data.pop(key)))
+            
+            pop_key = delimeter.join(pop_keys)
+            return_dict[pop_key] = data[data_key]
+        
+        return return_dict

{neurostats_API-0.0.14.dist-info → neurostats_API-0.0.16.dist-info}/METADATA

@@ -1,12 +1,18 @@
 Metadata-Version: 2.1
 Name: neurostats_API
-Version: 0.0.14
+Version: 0.0.16
 Summary: The service of NeuroStats website
 Home-page: https://github.com/NeurowattStats/NeuroStats_API.git
 Author: JasonWang@Neurowatt
 Author-email: jason@neurowatt.ai
 Requires-Python: >=3.6
 Description-Content-Type: text/markdown
+Requires-Dist: numpy>=2.1.0
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: pymongo
+Requires-Dist: pytz
+Requires-Dist: python-dotenv
+Requires-Dist: yfinance
 
 # neurostats_API
 
@@ -83,7 +89,7 @@ pip install neurostats-API
 ```Python 
 >>> import neurostats_API
 >>> print(neurostats_API.__version__)
-0.0.14
+0.0.16
 ```
 
 ### 得到最新一期的評價資料與歷年評價
@@ -667,7 +673,121 @@ fetcher.query()
 
 請注意`range`, `last_range`, `52week_range`這三個項目型態為字串，其餘為float
 
+
+## TEJ 相關
+### 會計師簽證財務資料
+```Python
+from neurostats_API import FinanceReportFetcher
+
+mongo_uri = <MongoDB 的 URI>
+db_name = 'company' # 連接的DB名稱
+collection_name = "TWN/AINVFQ1" # 連接的collection對象
+
+fetcher = FinanceReportFetcher(
+    mongo_uri = mongo_uri,
+    db_name = db_name,
+    collection_name = collection_name
+)
+
+data = fetcher.get(
+    ticker = "2330" # 任意的股票代碼
+    fetch_mode = fetcher.FetchMode.QOQ_NOCAL # 取得模式
+    start_date = "2005-01-01",
+    end_date = "2024-12-31",
+    report_type = "Q",
+    indexes = []
+) # -> pd.DataFrame or Dict[pd.DataFrame] 
+```
+- `ticker`: 股票代碼
+
+- `fetch_mode` : 取得模式，為`fetcher.YOY_NOCAL` 或 `fetcher.QOQ_NOCAL`
+    - `YOY_NOCAL`: 以end_date為準，取得與end_date同季的歷年資料，時間範圍以start_date為起始
+        > 例如`start_date = "2020-07-01"`, `end_date = "2024-01-01"`，會回傳2020~2024的第一季資料
+
+    - `QOQ_NOCAL`: 時間範圍內的每季資料
+
+    - `QOQ`: 時間範圍內每季的每個index的數值以及QoQ
+
+    - `YoY`: 以end_date為準，取得與end_date同季的歷年資料以及成長率，時間範圍以start_date為起始
+
+- `start_date`: 開始日期，不設定時預設為`2005-01-01`
+
+- `end_date`: 結束日期，不設定時預設為資料庫最新資料的日期
+
+- `report_type`: 選擇哪種報告，預設為`Q`
+    - `A`: 當年累計
+    - `Q`: 當季數值
+    - `TTM`: 移動四季 (包括當季在內，往前累計四個季度)
+
+- `indexes`: 選擇的column，需要以TEJ提供的欄位名稱為準，不提供時或提供`[]`會回傳全部column
+   - 範例輸入: `['bp41', 'bp51']`
+
+[TEJ資料集連結](https://tquant.tejwin.com/%E8%B3%87%E6%96%99%E9%9B%86/)
+請看 `會計師簽證財務資料`
+
+#### 回傳資料
+##### `YOY_NOCAL` 與 `QOQ_NOCAL` 
+為回傳`pd.DataFrame`，column名稱為<年份>Q<季>， row名稱為指定財報項目
+```Python
+# fetch_mode = fetcher.FetchMode.QOQ_NOCAL
+        2024Q3        2024Q2        2024Q1
+bp41  7.082005e+07  6.394707e+07  5.761001e+07
+bp51  3.111298e+09  3.145373e+09  3.091985e+09
+
+# fetch_mode = fetcher.FetchMode.YOY_NOCAL
+        2024Q3        2023Q3        2022Q3
+bp41  7.082005e+07  5.377231e+07  6.201822e+07
+bp51  3.111298e+09  3.173919e+09  2.453840e+09
+```
+
+##### `YOY` 與 `QOQ`
+回傳為`Dict[pd.DataFrame]`, key 為指定的index, DataFrame中則是該index歷年的數值與成長率
+```Python
+# fetch_mode = fetcher.FetchMode.QOQ
+{
+        'bp41':               
+        2024Q3        2024Q2        2024Q1
+value   7.082005e+07  6.394707e+07  5.761001e+07
+growth  1.074791e-01  1.099994e-01  5.532101e-03, 
+        'bp51':               
+        2024Q3        2024Q2        2024Q1
+value   3.111298e+09  3.145373e+09  3.091985e+09
+growth -1.083335e-02  1.726663e-02 -4.159542e-03
+}
+
+# fetch_mode = fetcher.FetchMode.YOY
+{
+'bp41':               
+        2024Q3        2023Q3        2022Q3
+value   7.082005e+07  5.377231e+07  6.201822e+07
+YoY_1            NaN           NaN  4.130744e-01
+YoY_3   1.729171e-01  9.556684e-02  1.883274e-01
+YoY_5   1.389090e-01  1.215242e-01  1.642914e-01
+YoY_10  1.255138e-01  1.356297e-01  1.559702e-01, 
+'bp51':               
+        2024Q3        2023Q3        2022Q3
+value   3.111298e+09  3.173919e+09  2.453840e+09
+YoY_1            NaN           NaN  3.179539e-01
+YoY_3   1.866752e-01  2.766851e-01  2.638677e-01
+YoY_5   2.068132e-01  2.479698e-01  1.815106e-01
+YoY_10  1.420500e-01  1.586797e-01  1.551364e-01
+}
+```
+
+
 ## 版本紀錄
+## 0.0.16
+- 處理ValueFetcher的error #issue76
+
+- tej_fetcher新增 QOQ, YOY功能
+
+## 0.0.15
+- TechFetcher中新增指數條件
+
+- 新增tej_fetcher索取TEJ相關的資料
+
+- package新增depensnecy，可以安裝需要的相關package
+
 ## 0.0.14
 - 修改部分財報資料錯誤的乘以1000的問題
 

{neurostats_API-0.0.14.dist-info → neurostats_API-0.0.16.dist-info}/RECORD

@@ -1,28 +1,30 @@
-neurostats_API/__init__.py,sha256=zDrZHoj7CyPMzwVv9Yxva_-e95Gd1sRJSB99gLu9kXU,20
+neurostats_API/__init__.py,sha256=5ToELVqNOIdVJrMj5G8JvbyRIjvo1FxcP6e-a-iMe1Y,261
 neurostats_API/cli.py,sha256=UJSWLIw03P24p-gkBb6JSEI5dW5U12UvLf1L8HjQD-o,873
 neurostats_API/main.py,sha256=QcsfmWivg2Dnqw3MTJWiI0QvEiRs0VuH-BjwQHFCv00,677
-neurostats_API/fetchers/__init__.py,sha256=ylYEySHQxcAhUUWEOCGZfmaAg7Mir5MfuEhOjk3POJg,406
+neurostats_API/fetchers/__init__.py,sha256=B4aBwVzf_X-YieEf3fZteU0qmBPVIB9VjrmkyWhLK18,489
 neurostats_API/fetchers/balance_sheet.py,sha256=sQv4Gk5uoKURLEdh57YknOQWiyVwaXJ2Mw75jxNqUS0,5804
-neurostats_API/fetchers/base.py,sha256=NW2SFzrimyAIrdJx1LVmTazelyZOAtcj54kJKHc4Vaw,1662
+neurostats_API/fetchers/base.py,sha256=rcrKW2PTJYfBsxsiGpCYiVTK9pQW4aALYLixIjvNMUk,4890
 neurostats_API/fetchers/cash_flow.py,sha256=TY7VAWVXkj5-mzH5Iu0sIE-oV8MvGmmDy0URNotNV1E,7614
 neurostats_API/fetchers/finance_overview.py,sha256=PxUdWY0x030olYMLcCHDBn068JLmCE2RTOce1dxs5vM,27753
 neurostats_API/fetchers/institution.py,sha256=UrcBc6t7u7CnEwUsf6YmLbbJ8VncdWpq8bCz17q2dgs,11168
 neurostats_API/fetchers/margin_trading.py,sha256=lQImtNdvaBoSlKhJvQ3DkH3HjSSgKRJz4ZZpyR5-Z4I,10433
 neurostats_API/fetchers/month_revenue.py,sha256=nixX2llzjCFr2m2YVjxrSfkBusnZPrPb2dRDq1XLGhw,4251
 neurostats_API/fetchers/profit_lose.py,sha256=EN9Y0iamcAaHMZdjHXO6b_2buLnORssf8ZS7A0hi74s,5896
-neurostats_API/fetchers/tech.py,sha256=wH1kkqiETQhF0HAhk-UIiucnZ3EiL85Q-yMWCcVOiFM,11395
-neurostats_API/fetchers/value_invest.py,sha256=_eQxuEnIYvksb06QHixGK29Gnwr_3xmI6Tu7dv4J__E,5769
+neurostats_API/fetchers/tech.py,sha256=Hol1bcwJ_ERcnoTXNWlqqaWOuzdl7MeiAjCvzQMZDTg,12269
+neurostats_API/fetchers/tej_finance_report.py,sha256=laXph2ca1LCFocZjjdvtzmm5fcUecHk2Gs5h6-XMSWY,12967
+neurostats_API/fetchers/value_invest.py,sha256=b_x2Dpgs8VBU5HdG8ocKtfIEkqhU-Q0S5n6RxuFuM2g,7467
 neurostats_API/tools/balance_sheet.yaml,sha256=6XygNG_Ybb1Xkk1e39LMLKr7ATvaCP3xxuwFbgNl6dA,673
 neurostats_API/tools/cash_flow_percentage.yaml,sha256=fk2Z4eb1JjGFvP134eJatHacB7BgTkBenhDJr83w8RE,1345
 neurostats_API/tools/finance_overview_dict.yaml,sha256=B9nV75StXkrF3yv2-eezzitlJ38eEK86RD_VY6588gQ,2884
 neurostats_API/tools/profit_lose.yaml,sha256=iyp9asYJ04vAxk_HBUDse_IBy5oVvYHpwsyACg5YEeg,3029
 neurostats_API/tools/seasonal_data_field_dict.txt,sha256=X8yc_el6p8BH_3FikTqBVFGsvWdXT6MHXLfKfi44334,8491
-neurostats_API/utils/__init__.py,sha256=FTYKRFzW2XVXdnSHXnS3mQQaHlKF9xGqrMsgZZ2kroc,142
-neurostats_API/utils/data_process.py,sha256=YKfk3fXkcmwFS_8YxOV2uRLnt9NX3cYPV_XxrCgk8Yo,7597
+neurostats_API/utils/__init__.py,sha256=0tJCRmlJq2aDwcNNW-oEaA9H0OxTJMFvjpVYtG4AvZU,186
+neurostats_API/utils/calculate_value.py,sha256=lUKSsWU76XRmDUcmi4eDjoQxjb3vWpAAKInF9w49VNI,782
+neurostats_API/utils/data_process.py,sha256=A--dzOsu42jRxqqCD41gTtjE5rhEBYmhB6y-AnCvo5U,8986
 neurostats_API/utils/datetime.py,sha256=XJya4G8b_-ZOaBbMXgQjWh2MC4wc-o6goQ7EQJQMWrQ,773
 neurostats_API/utils/db_client.py,sha256=OYe6yazcR4Aa6jYmy47JrryUeh2NnKGqY2K_lSZe6i8,455
 neurostats_API/utils/fetcher.py,sha256=VbrUhjA-GG5AyjPX2SHtFIbZM4dm3jo0RgZzuCbb_Io,40927
-neurostats_API-0.0.14.dist-info/METADATA,sha256=MeV1goaFbTQI0ddvr-TvElrggROHEiAixNCqP_gyLkI,25935
-neurostats_API-0.0.14.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
-neurostats_API-0.0.14.dist-info/top_level.txt,sha256=nSlQPMG0VtXivJyedp4Bkf86EOy2TpW10VGxolXrqnU,15
-neurostats_API-0.0.14.dist-info/RECORD,,
+neurostats_API-0.0.16.dist-info/METADATA,sha256=9US1mdwWnOCAnwfsOj-ZLRCfo07p3yd0UfwMKS6989g,29848
+neurostats_API-0.0.16.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
+neurostats_API-0.0.16.dist-info/top_level.txt,sha256=nSlQPMG0VtXivJyedp4Bkf86EOy2TpW10VGxolXrqnU,15
+neurostats_API-0.0.16.dist-info/RECORD,,