neurostats-API 0.0.17__tar.gz → 0.0.19__tar.gz

{neurostats_api-0.0.17 → neurostats_api-0.0.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: neurostats_API
-Version: 0.0.17
+Version: 0.0.19
 Summary: The service of NeuroStats website
 Home-page: https://github.com/NeurowattStats/NeuroStats_API.git
 Author: JasonWang@Neurowatt
@@ -774,43 +774,73 @@ YoY_10  1.420500e-01  1.586797e-01  1.551364e-01
 }
 ```
 
+### 公司自結資料
+```Python
+from neurostats_API import FinanceReportFetcher
 
-## 版本紀錄
-## 0.0.16
-- 處理ValueFetcher的error #issue76
+fetcher = FinanceReportFetcher(
+    mongo_uri = mongo_uri,
+    db_name = db_name,
+    collection_name = collection_name
+)
 
-- tej_fetcher新增 QOQ, YOY功能
+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`: 股票代碼
 
-## 0.0.15
-- TechFetcher中新增指數條件
+- `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的第一季資料
 
-- 新增tej_fetcher索取TEJ相關的資料
+    - `QOQ_NOCAL`: 時間範圍內的每季資料
 
-- package新增depensnecy，可以安裝需要的相關package
+    - `QOQ`: 時間範圍內每季的每個index的數值以及QoQ
 
-## 0.0.14
-- 修改部分財報資料錯誤的乘以1000的問題
+    - `YoY`: 以end_date為準，取得與end_date同季的歷年資料以及成長率，時間範圍以start_date為起始
 
-- 新增例外處理: 若資料庫對於季資料一部分index缺失的情況下仍會盡可能去將資料蒐集並呈現
+- `start_date`: 開始日期，不設定時預設為`2005-01-01`
 
-### 0.0.13
-- value_fetcher 新增獲得一序列評價的功能
+- `end_date`: 結束日期，不設定時預設為資料庫最新資料的日期
 
-### 0.0.12
-- 新增資券變化(margin trading)
+- `report_type`: 選擇哪種報告，預設為`Q`
+    - `A`: 當年累計
+    - `Q`: 當季數值
+    - `TTM`: 移動四季 (包括當季在內，往前累計四個季度)
 
-- 修改法人買賣(institution_trading)的query方式
+- `indexes`: 選擇的column，需要以TEJ提供的欄位名稱為準，不提供時或提供`[]`會回傳全部column
+   - 範例輸入: `['bp41', 'bp51']`
 
-### 0.0.11
-- 修復財務分析的千元計算問題
+[TEJ資料集連結](https://tquant.tejwin.com/%E8%B3%87%E6%96%99%E9%9B%86/)
+請看 `公司自結數`
 
-- 籌碼面新增法人買賣(institution_trading)
+### 開高低收
+```Python
+mongo_uri = <MongoDB 的 URI>
+db_name = 'company' # 連接的DB名稱
+collection_name = "TWN/APIPRCD" # 連接的collection對象
+from neurostats_API import TEJStockPriceFetcher
 
-- 將財報三表與月營收的資料型態與數值做轉換(%轉字串, 千元乘以1000)
-### 0.0.10
-- 更新指標的資料型態: 單位為千元乘以1000之後回傳整數
+fetcher = TEJStockPriceFetcher(
+    mongo_uri = mongo_uri,
+    db_name = db_name,
+    collection_name = collection_name
+)
 
-- 處理銀行公司在finanace_overview會報錯誤的問題(未完全解決，因銀行公司財報有許多名稱不同，目前都會顯示為None)
+data = fetcher.get(
+    ticker = "2330" # 任意的股票代碼
+    start_date = "2005-01-01",
+    period = "3m"
+) # -> pd.DataFrame
+```
+- `ticker`: 股票代碼
+- `start_date`: 搜尋範圍的開始日期
+- `period`: 搜尋的時間範圍長度
 
-### 0.0.9
-- 更新指標的資料型態: 單位為日, %, 倍轉為字串
+`period`與`start_date`同時存在時以period優先

{neurostats_api-0.0.17 → neurostats_api-0.0.19}/README.md

@@ -758,43 +758,73 @@ YoY_10  1.420500e-01  1.586797e-01  1.551364e-01
 }
 ```
 
+### 公司自結資料
+```Python
+from neurostats_API import FinanceReportFetcher
 
-## 版本紀錄
-## 0.0.16
-- 處理ValueFetcher的error #issue76
+fetcher = FinanceReportFetcher(
+    mongo_uri = mongo_uri,
+    db_name = db_name,
+    collection_name = collection_name
+)
 
-- tej_fetcher新增 QOQ, YOY功能
+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`: 股票代碼
 
-## 0.0.15
-- TechFetcher中新增指數條件
+- `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的第一季資料
 
-- 新增tej_fetcher索取TEJ相關的資料
+    - `QOQ_NOCAL`: 時間範圍內的每季資料
 
-- package新增depensnecy，可以安裝需要的相關package
+    - `QOQ`: 時間範圍內每季的每個index的數值以及QoQ
 
-## 0.0.14
-- 修改部分財報資料錯誤的乘以1000的問題
+    - `YoY`: 以end_date為準，取得與end_date同季的歷年資料以及成長率，時間範圍以start_date為起始
 
-- 新增例外處理: 若資料庫對於季資料一部分index缺失的情況下仍會盡可能去將資料蒐集並呈現
+- `start_date`: 開始日期，不設定時預設為`2005-01-01`
 
-### 0.0.13
-- value_fetcher 新增獲得一序列評價的功能
+- `end_date`: 結束日期，不設定時預設為資料庫最新資料的日期
 
-### 0.0.12
-- 新增資券變化(margin trading)
+- `report_type`: 選擇哪種報告，預設為`Q`
+    - `A`: 當年累計
+    - `Q`: 當季數值
+    - `TTM`: 移動四季 (包括當季在內，往前累計四個季度)
 
-- 修改法人買賣(institution_trading)的query方式
+- `indexes`: 選擇的column，需要以TEJ提供的欄位名稱為準，不提供時或提供`[]`會回傳全部column
+   - 範例輸入: `['bp41', 'bp51']`
 
-### 0.0.11
-- 修復財務分析的千元計算問題
+[TEJ資料集連結](https://tquant.tejwin.com/%E8%B3%87%E6%96%99%E9%9B%86/)
+請看 `公司自結數`
 
-- 籌碼面新增法人買賣(institution_trading)
+### 開高低收
+```Python
+mongo_uri = <MongoDB 的 URI>
+db_name = 'company' # 連接的DB名稱
+collection_name = "TWN/APIPRCD" # 連接的collection對象
+from neurostats_API import TEJStockPriceFetcher
 
-- 將財報三表與月營收的資料型態與數值做轉換(%轉字串, 千元乘以1000)
-### 0.0.10
-- 更新指標的資料型態: 單位為千元乘以1000之後回傳整數
+fetcher = TEJStockPriceFetcher(
+    mongo_uri = mongo_uri,
+    db_name = db_name,
+    collection_name = collection_name
+)
 
-- 處理銀行公司在finanace_overview會報錯誤的問題(未完全解決，因銀行公司財報有許多名稱不同，目前都會顯示為None)
+data = fetcher.get(
+    ticker = "2330" # 任意的股票代碼
+    start_date = "2005-01-01",
+    period = "3m"
+) # -> pd.DataFrame
+```
+- `ticker`: 股票代碼
+- `start_date`: 搜尋範圍的開始日期
+- `period`: 搜尋的時間範圍長度
 
-### 0.0.9
-- 更新指標的資料型態: 單位為日, %, 倍轉為字串
+`period`與`start_date`同時存在時以period優先

{neurostats_api-0.0.17 → neurostats_api-0.0.19}/neurostats_API/__init__.py

@@ -1,4 +1,4 @@
-__version__='0.0.16'
+__version__='0.0.19'
 
 from .fetchers import (
     BalanceSheetFetcher,
@@ -9,5 +9,6 @@ from .fetchers import (
     MarginTradingFetcher,
     MonthRevenueFetcher,
     TechFetcher,
-    ProfitLoseFetcher
+    TEJStockPriceFetcher,
+    ProfitLoseFetcher,
 )

{neurostats_api-0.0.17 → neurostats_api-0.0.19}/neurostats_API/fetchers/__init__.py

@@ -2,7 +2,7 @@ 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 .tej_finance_report import FinanceReportFetcher, TEJStockPriceFetcher
 from .tech import TechFetcher
 from .institution import InstitutionFetcher
 from .margin_trading import MarginTradingFetcher

{neurostats_api-0.0.17 → neurostats_api-0.0.19}/neurostats_API/fetchers/base.py

@@ -1,4 +1,5 @@
 import abc
+from typing import Union
 from pymongo import MongoClient
 import pandas as pd
 import json
@@ -53,8 +54,8 @@ class StatsFetcher:
         season = (month - 1) // 3 + 1
 
         return StatsDateTime(date, year, month, day, season)
-    
-    def has_required_columns(self, df:pd.DataFrame, required_cols=None):
+
+    def has_required_columns(self, df: pd.DataFrame, required_cols=None):
         """
         Check if the required columns are present in the DataFrame.
 
@@ -68,23 +69,22 @@ class StatsFetcher:
         """
         if required_cols is None:
             required_cols = ['date', 'open', 'high', 'low', 'close', 'volume']
-        
+
         return all(col in df.columns for col in required_cols)
 
 
 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})
+        latest_data = self.collection.find_one(
+            {"ticker": ticker}, {
+                "last_update": 1,
+                "_id": 0
+            })
 
         try:
             latest_date = latest_data['last_update']["latest_data_date"]
@@ -93,11 +93,16 @@ class BaseTEJFetcher(abc.ABC):
 
         return latest_date
 
-    def cal_YoY(self, data_dict: dict, start_year: int, end_year: int, season: int):
+    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}"]
+            try:
+                year_data = data_dict[f"{year}Q{season}"].copy()
+            except KeyError as e:
+                continue
+
             year_keys = list(year_data.keys())
             for key in year_keys:
                 if (key in 'season'):
@@ -109,9 +114,11 @@ class BaseTEJFetcher(abc.ABC):
                     for shift in year_shifts:
                         this_value = year_data[key]
                         try:
-                            past_year = str(year - shift)
+                            past_year = 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)
+                            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
 
@@ -149,9 +156,11 @@ class BaseTEJFetcher(abc.ABC):
                     temp_dict = {"value": this_value}
 
                     try:
-                        last_value = data_dict[f"{last_year}Q{last_season}"][key]['value']
+                        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)
+                        temp_dict['growth'] = YoY_Calculator.cal_growth(
+                            this_value, last_value, delta=1)
                     except Exception as e:
                         temp_dict['growth'] = None
 
@@ -169,3 +178,33 @@ class BaseTEJFetcher(abc.ABC):
         for key in data_dict.keys():
             data_dict[key] = pd.DataFrame.from_dict(data_dict[key])
         return data_dict
+
+    def set_time_shift(self, date: Union[str, datetime], period: str):
+        if (isinstance(date, str)):
+            date = datetime.strptime(date, "%Y-%m-%d")
+        if (period == '1d'):
+            return date - timedelta(days=1)
+
+        elif (period == '7d'):
+            return date - timedelta(days=7)
+
+        elif (period == '1m'):
+            return date - timedelta(days=30)
+
+        elif (period == '3m'):
+            return date - timedelta(days=90)
+
+        elif (period == '1y'):
+            return date - timedelta(days=365)
+
+        elif (period == '3y'):
+            return date - timedelta(days=365 * 3)
+
+        elif (period == '5y'):
+            return date - timedelta(days=365 * 5)
+
+        elif (period == '10y'):
+            return date - timedelta(days=365 * 10)
+
+        elif (period == 'all'):
+            return datetime.strptime("1991-01-01", "%Y-%m-%d")