FinMind 2.0.5__tar.gz → 2.0.7__tar.gz

{finmind-2.0.5 → finmind-2.0.7}/FinMind/data/data_loader.py

@@ -2172,6 +2172,50 @@ class DataLoader(FinMindApi):
         )
         return tw_total_exchange_mMargin_maintenance
 
+    def taiwan_stock_margin_maintenance(
+        self,
+        stock_id: str = "",
+        start_date: str = "",
+        end_date: str = "",
+        timeout: int = None,
+        use_async: bool = False,
+        stock_id_list: typing.List[str] = None,
+    ) -> pd.DataFrame:
+        """get 個股融資維持率（Sponsor）
+
+        個股融資維持率為估算指標：僅個股融資餘額張數為公開資訊，個股融資
+        金額並未公開，因此本資料集無官方真值可對照，與其他服務的估算結果
+        不會完全一致。融資成數以法定上限計（上市六成；上櫃 2014-11-10 起
+        六成、之前五成），警示股／處置股實際成數可能較低。融資成本線為
+        名目值，已調整股數事件（分割／面額變更／減資／配股）並扣除現金
+        股利。上市自 2001-01-05 起、上櫃自 2007-01-04 起。
+
+        :param stock_id (str): 股票代號("2330")
+        :param start_date (str): 起始日期("2024-01-02")
+        :param end_date (str): 結束日期("2024-01-31")
+        :param timeout (int): timeout seconds, default None
+
+        :return: 個股融資維持率 TaiwanStockMarginMaintenance
+        :rtype pd.DataFrame
+        :rtype column date (str): 日期
+        :rtype column stock_id (str): 股票代號
+        :rtype column margin_balance (int): 融資餘額（張）
+        :rtype column margin_cost (float): 融資成本線，
+            估算的融資部位移動加權平均成本
+        :rtype column margin_ratio (float): 融資成數，實際採用值(0.6 / 0.5)
+        :rtype column margin_maintenance (float): 融資維持率(%)，例 156.1
+        """
+        stock_margin_maintenance = self.get_data(
+            dataset=Dataset.TaiwanStockMarginMaintenance,
+            data_id=stock_id,
+            start_date=start_date,
+            end_date=end_date,
+            timeout=timeout,
+            use_async=use_async,
+            data_id_list=stock_id_list,
+        )
+        return stock_margin_maintenance
+
     def us_stock_info(self, timeout: int = None) -> pd.DataFrame:
         """get 美國股票代碼總覽
         :param timeout (int): timeout seconds, default None
@@ -2755,6 +2799,38 @@ class DataLoader(FinMindApi):
         )
         return stock_industry_chain
 
+    def taiwan_stock_industry_chain_money_flow(
+        self,
+        date: str = "",
+        timeout: int = None,
+    ) -> pd.DataFrame:
+        """get 台股產業鏈資金流向（Sponsor）
+
+        計算每日交易資金在各產業鏈的分佈：以個體公司所屬產業鏈
+        （industry／sub_industry）彙總每日個股成交。sub_industry 為空字串的
+        列為該產業鏈總計（成分股不重複計算，不等於子產業列加總）；一檔股票
+        可屬多條產業鏈，各產業鏈佔比加總會超過 100%。
+
+        :param date (str): 資料日期("2026-07-17")；資料量大，一次提供一天
+        :param timeout (int): timeout seconds, default None
+
+        :return: 台股產業鏈資金流向 TaiwanStockIndustryChainMoneyFlow
+        :rtype pd.DataFrame
+        :rtype column date (str): 日期
+        :rtype column industry (str): 產業鏈
+        :rtype column sub_industry (str): 子產業；空字串代表該產業鏈總計列
+        :rtype column stock_count (int): 成分股數（當日有成交）
+        :rtype column trading_volume (int): 成交股數合計
+        :rtype column trading_money (int): 成交金額合計
+        :rtype column trading_money_pct (float): 佔當日全市場個股成交金額比重(%)
+        """
+        industry_chain_money_flow = self.get_data(
+            dataset=Dataset.TaiwanStockIndustryChainMoneyFlow,
+            start_date=date,
+            timeout=timeout,
+        )
+        return industry_chain_money_flow
+
     def cnn_fear_greed_index(
         self,
         start_date: str = "",
@@ -3053,6 +3129,36 @@ class DataLoader(FinMindApi):
         )
         return taiwan_stock_convertible_bond_monthly_analysis
 
+    def taiwan_stock_convertible_bond_put_provision(
+        self,
+        cb_id: str = "",
+        start_date: str = "",
+        end_date: str = "",
+        timeout: int = None,
+    ) -> pd.DataFrame:
+        """get 可轉債賣回權時程（含未來已公告場次）
+        :param cb_id (str): 可轉債代號("14773")
+        :param start_date (str): 起始日期("2011-06-01")
+        :param end_date (str): 結束日期("2011-06-30")，可設未來日期查詢即將到來的賣回場次
+        :param timeout (int): timeout seconds, default None
+
+        :return: 可轉債賣回權時程 TaiwanStockConvertibleBondPutProvision
+        :rtype pd.DataFrame
+        :rtype column date (str): 賣回基準日
+        :rtype column cb_id (str): 可轉債代號
+        :rtype column cb_name (str): 可轉債名稱
+        :rtype column PutPrice (float): 賣回金額
+        :rtype column PutYieldRate (float): 賣回收益率
+        """
+        taiwan_stock_convertible_bond_put_provision = self.get_data(
+            dataset=Dataset.TaiwanStockConvertibleBondPutProvision,
+            data_id=cb_id,
+            start_date=start_date,
+            end_date=end_date,
+            timeout=timeout,
+        )
+        return taiwan_stock_convertible_bond_put_provision
+
     def taiwan_option_vix(
         self,
         start_date: str = "",
@@ -3079,6 +3185,82 @@ class DataLoader(FinMindApi):
         )
         return taiwan_option_vix
 
+    def taiwan_asset_swap_fixed_income_daily(
+        self,
+        stock_id: str = "",
+        start_date: str = "",
+        end_date: str = "",
+        timeout: int = None,
+        use_async: bool = False,
+        stock_id_list: typing.List[str] = None,
+    ) -> pd.DataFrame:
+        """get 資產交換固定收益日成交資訊
+        :param stock_id: 股票代號("17172")
+        :param start_date (str): 起始日期("2025-01-01")
+        :param end_date (str): 結束日期("2025-12-31")
+        :param timeout (int): timeout seconds, default None
+
+        :return: 資產交換固定收益日成交資訊 TaiwanAssetSwapFixedIncomeDaily
+        :rtype pd.DataFrame
+        :rtype column date (str): 日期
+        :rtype column stock_id (str): 股票代碼
+        :rtype column stock_name (str): 股票名稱
+        :rtype column notional_amount (int): 名目本金
+        :rtype column number_of_transactions (int): 成交筆數
+        :rtype column rate_lowest (float): 最低利率
+        :rtype column rate_highest (float): 最高利率
+        :rtype column rate_average (float): 平均利率
+        :rtype column contract_term_years (float): 合約期間(年)
+        """
+        data = self.get_data(
+            dataset=Dataset.TaiwanAssetSwapFixedIncomeDaily,
+            data_id=stock_id,
+            start_date=start_date,
+            end_date=end_date,
+            timeout=timeout,
+            use_async=use_async,
+            data_id_list=stock_id_list,
+        )
+        return data
+
+    def taiwan_asset_swap_option_daily(
+        self,
+        stock_id: str = "",
+        start_date: str = "",
+        end_date: str = "",
+        timeout: int = None,
+        use_async: bool = False,
+        stock_id_list: typing.List[str] = None,
+    ) -> pd.DataFrame:
+        """get 資產交換選擇權日成交資訊
+        :param stock_id: 股票代號("17172")
+        :param start_date (str): 起始日期("2025-01-01")
+        :param end_date (str): 結束日期("2025-12-31")
+        :param timeout (int): timeout seconds, default None
+
+        :return: 資產交換選擇權日成交資訊 TaiwanAssetSwapOptionDaily
+        :rtype pd.DataFrame
+        :rtype column date (str): 日期
+        :rtype column stock_id (str): 股票代碼
+        :rtype column stock_name (str): 股票名稱
+        :rtype column notional_amount (int): 名目本金
+        :rtype column number_of_transactions (int): 成交筆數
+        :rtype column premium_lowest (float): 最低權利金
+        :rtype column premium_highest (float): 最高權利金
+        :rtype column premium_average (float): 平均權利金
+        :rtype column contract_term_years (float): 合約期間(年)
+        """
+        data = self.get_data(
+            dataset=Dataset.TaiwanAssetSwapOptionDaily,
+            data_id=stock_id,
+            start_date=start_date,
+            end_date=end_date,
+            timeout=timeout,
+            use_async=use_async,
+            data_id_list=stock_id_list,
+        )
+        return data
+
     def _get_stock_id_list(
         self, date: str, timeout: int = None
     ) -> typing.List[str]:

{finmind-2.0.5 → finmind-2.0.7}/FinMind/schema/data.py

@@ -124,6 +124,7 @@ class Dataset(str, Enum):
         "TaiwanStockDispositionSecuritiesPeriod"
     )
     TaiwanStockIndustryChain = "TaiwanStockIndustryChain"
+    TaiwanStockIndustryChainMoneyFlow = "TaiwanStockIndustryChainMoneyFlow"
     TaiwanStockTradingDate = "TaiwanStockTradingDate"
     TaiwanStockInfoWithWarrantSummary = "TaiwanStockInfoWithWarrantSummary"
     TaiwanStockSplitPrice = "TaiwanStockSplitPrice"
@@ -143,7 +144,13 @@ class Dataset(str, Enum):
     TaiwanStockConvertibleBondMonthlyAnalysis = (
         "TaiwanStockConvertibleBondMonthlyAnalysis"
     )
+    TaiwanStockConvertibleBondPutProvision = (
+        "TaiwanStockConvertibleBondPutProvision"
+    )
     TaiwanOptionVix = "TaiwanOptionVix"
+    TaiwanAssetSwapFixedIncomeDaily = "TaiwanAssetSwapFixedIncomeDaily"
+    TaiwanAssetSwapOptionDaily = "TaiwanAssetSwapOptionDaily"
+    TaiwanStockMarginMaintenance = "TaiwanStockMarginMaintenance"
 
 
 class Version(str, Enum):

finmind-2.0.7/FinMind/strategies/utils.py

@@ -0,0 +1,72 @@
+import datetime
+
+import numpy as np
+
+from FinMind.data import DataLoader
+
+
+# TaiwanStockInfo 對部分上市股票會回超過一列，industry_category 不只放產業別：
+#   電子工業 / 化學生技醫療 是 TWSE 類股選單裡的「產業總稱」，各自是底下子類的
+#     聯集（電子工業 = 半導體業~其他電子業、化學生技醫療 = 化學工業+生技醫療業），
+#     所以 2330 會同時有「半導體業」和「電子工業」兩列
+#   創新板股票 是板別不是產業，該檔在自己的產業別也還有一列
+#   創新版股票 是舊資料的錯字（板 vs 版）
+# 直接取第一列會因為回傳順序而不穩定，先把這些非產業別的值排掉。
+NOT_INDUSTRY_CATEGORY = [
+    "電子工業",
+    "化學生技醫療",
+    "創新板股票",
+    "創新版股票",
+]
+
+
+def get_asset_underlying_type(stock_id: str, data_loader: DataLoader) -> str:
+    taiwan_stock_info = data_loader.taiwan_stock_info()
+    industry_category = taiwan_stock_info[
+        taiwan_stock_info["stock_id"] == stock_id
+    ]["industry_category"]
+    real_industry_category = industry_category[
+        ~industry_category.isin(NOT_INDUSTRY_CATEGORY)
+    ]
+    # 全部都被排掉時（例如只收到總稱那列）就退回原本的值，寧可回總稱也不要回空
+    if len(real_industry_category) > 0:
+        industry_category = real_industry_category
+    # 排序後取第一個，確保同一檔股票每次都回一樣的結果
+    return sorted(industry_category.values)[0]
+
+
+def get_underlying_trading_tax(underlying_type: str) -> float:
+    mapping = {"ETF": 0.001, "上櫃指數股票型基金(ETF)": 0.001}
+    return mapping.get(underlying_type, 0.003)
+
+
+def calculate_datenbr(day1: str, day2: str) -> int:
+    assert day1 <= day2, "day2 必須大於等於 day1"
+
+    dis_day = datetime.datetime.strptime(
+        day2, "%Y-%m-%d"
+    ) - datetime.datetime.strptime(day1, "%Y-%m-%d")
+    return int(dis_day.days)
+
+
+def calculate_sharp_ratio(strategy_return: float, std: float) -> float:
+    risk_free_rate = 0
+    return (
+        0
+        if std == 0
+        else round(((strategy_return - risk_free_rate) / std) * np.sqrt(252), 2)
+    )
+
+
+def period_return2annual_return(
+    period_return: float, period_years: float
+) -> float:
+    annual_return = round(
+        ((period_return + 1) ** (1 / period_years) - 1),
+        4,
+    )
+    return annual_return
+
+
+def days2years(days: int) -> float:
+    return days / 365

{finmind-2.0.5/finmind.egg-info → finmind-2.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finmind
-Version: 2.0.5
+Version: 2.0.7
 Summary: financial mining
 Author-email: linsam <finmind.tw@gmail.com>
 License:                                  Apache License

{finmind-2.0.5 → finmind-2.0.7/finmind.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finmind
-Version: 2.0.5
+Version: 2.0.7
 Summary: financial mining
 Author-email: linsam <finmind.tw@gmail.com>
 License:                                  Apache License

finmind-2.0.5/FinMind/strategies/utils.py

@@ -1,50 +0,0 @@
-import datetime
-
-import numpy as np
-
-from FinMind.data import DataLoader
-
-
-def get_asset_underlying_type(stock_id: str, data_loader: DataLoader) -> str:
-    taiwan_stock_info = data_loader.taiwan_stock_info()
-    underlying_type = taiwan_stock_info[
-        taiwan_stock_info["stock_id"] == stock_id
-    ]["industry_category"].values[0]
-    return underlying_type
-
-
-def get_underlying_trading_tax(underlying_type: str) -> float:
-    mapping = {"ETF": 0.001, "上櫃指數股票型基金(ETF)": 0.001}
-    return mapping.get(underlying_type, 0.003)
-
-
-def calculate_datenbr(day1: str, day2: str) -> int:
-    assert day1 <= day2, "day2 必須大於等於 day1"
-
-    dis_day = datetime.datetime.strptime(
-        day2, "%Y-%m-%d"
-    ) - datetime.datetime.strptime(day1, "%Y-%m-%d")
-    return int(dis_day.days)
-
-
-def calculate_sharp_ratio(strategy_return: float, std: float) -> float:
-    risk_free_rate = 0
-    return (
-        0
-        if std == 0
-        else round(((strategy_return - risk_free_rate) / std) * np.sqrt(252), 2)
-    )
-
-
-def period_return2annual_return(
-    period_return: float, period_years: float
-) -> float:
-    annual_return = round(
-        ((period_return + 1) ** (1 / period_years) - 1),
-        4,
-    )
-    return annual_return
-
-
-def days2years(days: int) -> float:
-    return days / 365