FinMind 2.0.12__tar.gz → 2.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. {finmind-2.0.12 → finmind-2.1.0}/FinMind/data/data_loader.py +152 -0
  2. {finmind-2.0.12 → finmind-2.1.0}/FinMind/data/finmind_api.py +25 -3
  3. {finmind-2.0.12 → finmind-2.1.0}/FinMind/schema/data.py +4 -0
  4. {finmind-2.0.12/finmind.egg-info → finmind-2.1.0}/PKG-INFO +2 -2
  5. {finmind-2.0.12 → finmind-2.1.0/finmind.egg-info}/PKG-INFO +2 -2
  6. {finmind-2.0.12 → finmind-2.1.0}/finmind.egg-info/requires.txt +1 -1
  7. {finmind-2.0.12 → finmind-2.1.0}/pyproject.toml +1 -1
  8. {finmind-2.0.12 → finmind-2.1.0}/FinMind/__init__.py +0 -0
  9. {finmind-2.0.12 → finmind-2.1.0}/FinMind/_version.py +0 -0
  10. {finmind-2.0.12 → finmind-2.1.0}/FinMind/crawler/__init__.py +0 -0
  11. {finmind-2.0.12 → finmind-2.1.0}/FinMind/crawler/base.py +0 -0
  12. {finmind-2.0.12 → finmind-2.1.0}/FinMind/crawler/commodities.py +0 -0
  13. {finmind-2.0.12 → finmind-2.1.0}/FinMind/crawler/demo.py +0 -0
  14. {finmind-2.0.12 → finmind-2.1.0}/FinMind/crawler/government_bonds.py +0 -0
  15. {finmind-2.0.12 → finmind-2.1.0}/FinMind/data/__init__.py +0 -0
  16. {finmind-2.0.12 → finmind-2.1.0}/FinMind/data/data_subscriber.py +0 -0
  17. {finmind-2.0.12 → finmind-2.1.0}/FinMind/indicators/__init__.py +0 -0
  18. {finmind-2.0.12 → finmind-2.1.0}/FinMind/indicators/bias.py +0 -0
  19. {finmind-2.0.12 → finmind-2.1.0}/FinMind/indicators/continue_holding.py +0 -0
  20. {finmind-2.0.12 → finmind-2.1.0}/FinMind/indicators/institutional_investors_follower.py +0 -0
  21. {finmind-2.0.12 → finmind-2.1.0}/FinMind/indicators/institutional_investors_over_buy.py +0 -0
  22. {finmind-2.0.12 → finmind-2.1.0}/FinMind/indicators/kd.py +0 -0
  23. {finmind-2.0.12 → finmind-2.1.0}/FinMind/indicators/kd_crossover.py +0 -0
  24. {finmind-2.0.12 → finmind-2.1.0}/FinMind/indicators/ma_cross_orver.py +0 -0
  25. {finmind-2.0.12 → finmind-2.1.0}/FinMind/indicators/short_sale_margin_purchase_ratio.py +0 -0
  26. {finmind-2.0.12 → finmind-2.1.0}/FinMind/plotting/__init__.py +0 -0
  27. {finmind-2.0.12 → finmind-2.1.0}/FinMind/plotting/bar.py +0 -0
  28. {finmind-2.0.12 → finmind-2.1.0}/FinMind/plotting/kline.py +0 -0
  29. {finmind-2.0.12 → finmind-2.1.0}/FinMind/plotting/line.py +0 -0
  30. {finmind-2.0.12 → finmind-2.1.0}/FinMind/plotting/pie.py +0 -0
  31. {finmind-2.0.12 → finmind-2.1.0}/FinMind/schema/__init__.py +0 -0
  32. {finmind-2.0.12 → finmind-2.1.0}/FinMind/schema/indicators.py +0 -0
  33. {finmind-2.0.12 → finmind-2.1.0}/FinMind/schema/info.py +0 -0
  34. {finmind-2.0.12 → finmind-2.1.0}/FinMind/schema/plot.py +0 -0
  35. {finmind-2.0.12 → finmind-2.1.0}/FinMind/schema/rule.py +0 -0
  36. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/__init__.py +0 -0
  37. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/base.py +0 -0
  38. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/bias.py +0 -0
  39. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/continue_holding.py +0 -0
  40. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/institutional_investors_follower.py +0 -0
  41. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/kd.py +0 -0
  42. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/kd_crossover.py +0 -0
  43. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/ma_crossover.py +0 -0
  44. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/macd_crossover.py +0 -0
  45. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/max_min_period_bias.py +0 -0
  46. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/naive_kd.py +0 -0
  47. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/short_sale_margin_purchase_ratio.py +0 -0
  48. {finmind-2.0.12 → finmind-2.1.0}/FinMind/strategies/utils.py +0 -0
  49. {finmind-2.0.12 → finmind-2.1.0}/FinMind/templates/post.html +0 -0
  50. {finmind-2.0.12 → finmind-2.1.0}/FinMind/utility/__init__.py +0 -0
  51. {finmind-2.0.12 → finmind-2.1.0}/FinMind/utility/request.py +0 -0
  52. {finmind-2.0.12 → finmind-2.1.0}/FinMind/utility/rule.py +0 -0
  53. {finmind-2.0.12 → finmind-2.1.0}/LICENSE +0 -0
  54. {finmind-2.0.12 → finmind-2.1.0}/README.md +0 -0
  55. {finmind-2.0.12 → finmind-2.1.0}/finmind.egg-info/SOURCES.txt +0 -0
  56. {finmind-2.0.12 → finmind-2.1.0}/finmind.egg-info/dependency_links.txt +0 -0
  57. {finmind-2.0.12 → finmind-2.1.0}/finmind.egg-info/top_level.txt +0 -0
  58. {finmind-2.0.12 → finmind-2.1.0}/setup.cfg +0 -0
  59. {finmind-2.0.12 → finmind-2.1.0}/setup.py +0 -0
@@ -379,6 +379,55 @@ class DataLoader(FinMindApi):
379
379
  )
380
380
  return stock_block_trade
381
381
 
382
+ def taiwan_stock_after_hours_fixed_price_trading(
383
+ self,
384
+ stock_id: str = "",
385
+ start_date: str = "",
386
+ end_date: str = "",
387
+ timeout: int = None,
388
+ use_async: bool = False,
389
+ stock_id_list: typing.List[str] = None,
390
+ ) -> pd.DataFrame:
391
+ """get 盤後定價交易(Backer)
392
+ Taiwan Stock After-Hours Fixed-Price Trading
393
+
394
+ 上市 2004-12-24 ~ now;上櫃自 2011-01-03 起。
395
+ 收錄官方表全部證券,含當天無盤後成交(volume=0)的列;
396
+ 上市無成交列的 price 為當日定價(收盤價),上櫃無成交列 price 為 0。
397
+
398
+ :param stock_id (str): 股票代號("2330")
399
+ :param start_date (str): 起始日期("2025-09-01")
400
+ :param end_date (str): 結束日期("2025-09-30")
401
+ :param timeout (int): timeout seconds, default None
402
+
403
+ :return: 盤後定價交易 TaiwanStockAfterHoursFixedPriceTrading
404
+ :rtype pd.DataFrame
405
+ :rtype column date (str): 日期 Date
406
+ :rtype column stock_id (str): 股票代號 Stock ID
407
+ :rtype column market (str): 市場別,twse 上市、tpex 上櫃
408
+ Market (twse: listed, tpex: OTC)
409
+ :rtype column price (float): 成交價,盤後定價成交價(元)
410
+ Fixed trading price (TWD)
411
+ :rtype column volume (int): 成交量,單位:張(交易單位),非股
412
+ Trading volume (lots)
413
+ :rtype column trading_turnover (int): 成交筆數 Number of transactions
414
+ :rtype column trading_money (int): 成交金額(元) Trading value (TWD)
415
+ :rtype column unfilled_buy_volume (int): 未成交買量,
416
+ 撮合後剩餘委買量(張) Unfilled buy volume (lots)
417
+ :rtype column unfilled_sell_volume (int): 未成交賣量,
418
+ 撮合後剩餘委賣量(張) Unfilled sell volume (lots)
419
+ """
420
+ stock_after_hours_fixed_price_trading = self.get_data(
421
+ dataset=Dataset.TaiwanStockAfterHoursFixedPriceTrading,
422
+ data_id=stock_id,
423
+ start_date=start_date,
424
+ end_date=end_date,
425
+ timeout=timeout,
426
+ use_async=use_async,
427
+ data_id_list=stock_id_list,
428
+ )
429
+ return stock_after_hours_fixed_price_trading
430
+
382
431
  def taiwan_stock_loan_collateral_balance(
383
432
  self,
384
433
  stock_id: str = "",
@@ -946,6 +995,109 @@ class DataLoader(FinMindApi):
946
995
  )
947
996
  return stock_balance_sheet
948
997
 
998
+ def taiwan_stock_financial_report_file_download(
999
+ self,
1000
+ stock_id: str,
1001
+ year: int,
1002
+ quarter: int,
1003
+ report_category: str,
1004
+ timeout: int = None,
1005
+ ) -> bytes:
1006
+ """下載台股財報與年報 PDF(Sponsor Pro)
1007
+
1008
+ 一次下載一個檔案(指定 stock_id + year + quarter + report_category),
1009
+ 回傳檔案內容 bytes。檔案多為 PDF,少數 2013 年財報為 Word 檔(.doc)。
1010
+ - financial_report(財務報告書):quarter 1~4 皆有,
1011
+ quarter 4 為年度財報
1012
+ - annual_report(股東會年報):只有 quarter=4
1013
+ 財報收中文合併財報,無子公司的公司收中文個別財報;不含個體財報與
1014
+ 英文版。不是財報數字;財報數字請用 taiwan_stock_financial_statement /
1015
+ taiwan_stock_balance_sheet / taiwan_stock_cash_flows_statement。
1016
+ 資料區間:財報 2013 Q1 ~ now(每季)、年報 2013 ~ now(每年)。
1017
+ 部分年報 PDF 的文字層可能亂碼或殘缺(來源檔本身如此),
1018
+ 需要文字時可能要 OCR。
1019
+
1020
+ 該期沒有該檔案時,API 回 HTTP 404,SDK 不重試、直接丟出 Exception,
1021
+ 訊息開頭為 "Final response status: 404";權限不足或參數不合法
1022
+ (HTTP 400)同樣丟 Exception,訊息帶對應狀態碼。
1023
+ 參數不合法時 SDK 端先丟 ValueError,不打 API。
1024
+
1025
+ 存檔範例:
1026
+ content = api.taiwan_stock_financial_report_file_download(
1027
+ stock_id="2330",
1028
+ year=2025,
1029
+ quarter=4,
1030
+ report_category="annual_report",
1031
+ )
1032
+ path = "2330_2025-12-31_annual_report.pdf"
1033
+ open(path, "wb").write(content)
1034
+
1035
+ 逐年逐季下載範例(跳過沒有檔案的期別):
1036
+ quarter_end = {1: "03-31", 2: "06-30", 3: "09-30", 4: "12-31"}
1037
+ for year in range(2023, 2026):
1038
+ for quarter in (1, 2, 3, 4):
1039
+ categories = ["financial_report"]
1040
+ if quarter == 4:
1041
+ categories.append("annual_report")
1042
+ for report_category in categories:
1043
+ try:
1044
+ content = (
1045
+ api.taiwan_stock_financial_report_file_download(
1046
+ stock_id="2330",
1047
+ year=year,
1048
+ quarter=quarter,
1049
+ report_category=report_category,
1050
+ )
1051
+ )
1052
+ except Exception as error:
1053
+ if "status: 404" in str(error):
1054
+ continue # 該期沒有檔案
1055
+ raise
1056
+ path = (
1057
+ f"2330_{year}-{quarter_end[quarter]}_"
1058
+ f"{report_category}.pdf"
1059
+ )
1060
+ open(path, "wb").write(content)
1061
+
1062
+ :param stock_id (str): 股票代號("2330"),必填
1063
+ :param year (int): 西元年(2025),必填
1064
+ :param quarter (int): 季別,只能 1~4,必填
1065
+ :param report_category (str): 報告類別,必填,
1066
+ financial_report(財務報告書)或 annual_report(股東會年報);
1067
+ annual_report 只有 quarter=4
1068
+ :param timeout (int): timeout seconds, default None
1069
+
1070
+ :return: 檔案內容
1071
+ :rtype bytes
1072
+ """
1073
+ if isinstance(quarter, bool) or quarter not in (1, 2, 3, 4):
1074
+ raise ValueError(
1075
+ f"quarter 只能是 1~4 (quarter must be 1, 2, 3 or 4), "
1076
+ f"got {quarter!r}"
1077
+ )
1078
+ if report_category not in ("financial_report", "annual_report"):
1079
+ raise ValueError(
1080
+ "report_category 只能是 financial_report 或 annual_report "
1081
+ "(report_category must be 'financial_report' or "
1082
+ f"'annual_report'), got {report_category!r}"
1083
+ )
1084
+ if report_category == "annual_report" and quarter != 4:
1085
+ raise ValueError(
1086
+ "annual_report 只有 quarter=4 "
1087
+ f"(annual_report is only available for quarter 4), "
1088
+ f"got quarter={quarter!r}"
1089
+ )
1090
+ return self.get_storage_object_content(
1091
+ params={
1092
+ "dataset": Dataset.TaiwanStockFinancialReportFile,
1093
+ "data_id": stock_id,
1094
+ "year": int(year),
1095
+ "quarter": int(quarter),
1096
+ "report_category": report_category,
1097
+ },
1098
+ timeout=timeout,
1099
+ )
1100
+
949
1101
  def taiwan_stock_dividend(
950
1102
  self,
951
1103
  stock_id: str = "",
@@ -419,16 +419,38 @@ class FinMindApi:
419
419
  :return: 該日期所有資料
420
420
  :rtype: pd.DataFrame
421
421
  """
422
- url = f"{self.__api_url}/{self.__api_version}/storage_objects"
423
422
  params = {
424
423
  "dataset": dataset,
425
424
  "date": date,
426
425
  }
427
- content = download_storage_object(
426
+ content = self.get_storage_object_content(
427
+ params=params,
428
+ timeout=timeout,
429
+ max_retry_times=max_retry_times,
430
+ )
431
+ return pd.read_parquet(io.BytesIO(content))
432
+
433
+ def get_storage_object_content(
434
+ self,
435
+ params: typing.Dict[str, typing.Union[int, str]],
436
+ timeout: int = None,
437
+ max_retry_times: int = 10,
438
+ ) -> bytes:
439
+ """呼叫 storage_objects 並跟隨 307 轉址下載檔案,回傳原始 bytes
440
+ 傳輸中斷時會自動重試,並以 HTTP Range 從中斷處續傳
441
+ :param params (dict): storage_objects 查詢參數,需含 dataset,
442
+ 其餘依資料集而定 (e.g. date,或 data_id / year / quarter)
443
+ :param timeout (int): request timeout 秒數
444
+ :param max_retry_times (int): 最多重試次數
445
+
446
+ :return: 檔案內容
447
+ :rtype: bytes
448
+ """
449
+ url = f"{self.__api_url}/{self.__api_version}/storage_objects"
450
+ return download_storage_object(
428
451
  self.__session,
429
452
  url,
430
453
  params=params,
431
454
  timeout=timeout,
432
455
  max_retry_times=max_retry_times,
433
456
  )
434
- return pd.read_parquet(io.BytesIO(content))
@@ -139,6 +139,9 @@ class Dataset(str, Enum):
139
139
  TaiwanFuturesFinalSettlementPrice = "TaiwanFuturesFinalSettlementPrice"
140
140
  TaiwanOptionFinalSettlementPrice = "TaiwanOptionFinalSettlementPrice"
141
141
  TaiwanStockBlockTrade = "TaiwanStockBlockTrade"
142
+ TaiwanStockAfterHoursFixedPriceTrading = (
143
+ "TaiwanStockAfterHoursFixedPriceTrading"
144
+ )
142
145
  TaiwanStockLoanCollateralBalance = "TaiwanStockLoanCollateralBalance"
143
146
  TaiwanStockActiveETFHolding = "TaiwanStockActiveETFHolding"
144
147
  TaiwanStockActiveETFHoldingChange = "TaiwanStockActiveETFHoldingChange"
@@ -153,6 +156,7 @@ class Dataset(str, Enum):
153
156
  TaiwanAssetSwapOptionDaily = "TaiwanAssetSwapOptionDaily"
154
157
  TaiwanStockMarginMaintenance = "TaiwanStockMarginMaintenance"
155
158
  TaiwanStockBrokerDailyConcentration = "TaiwanStockBrokerDailyConcentration"
159
+ TaiwanStockFinancialReportFile = "TaiwanStockFinancialReportFile"
156
160
 
157
161
 
158
162
  class Version(str, Enum):
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: finmind
3
- Version: 2.0.12
3
+ Version: 2.1.0
4
4
  Summary: financial mining
5
5
  Author-email: linsam <finmind.tw@gmail.com>
6
6
  License: Apache License
@@ -227,7 +227,7 @@ Requires-Dist: pydantic<3.0.0,>=2.0.0
227
227
  Requires-Dist: ta<1.0.0,>=0.11.0
228
228
  Requires-Dist: lxml<7.0.0,>=4.6.3
229
229
  Requires-Dist: pyecharts<2.0.0,>=1.9.0
230
- Requires-Dist: ipython<8.0.0,>=7.16.1
230
+ Requires-Dist: ipython<10.0.0,>=8.10.0
231
231
  Requires-Dist: loguru<1.0.0,>=0.5.3
232
232
  Requires-Dist: aiohttp<4.0.0,>=3.7.4.post0
233
233
  Requires-Dist: importlib-metadata<9.0.0,>=4.8.1
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: finmind
3
- Version: 2.0.12
3
+ Version: 2.1.0
4
4
  Summary: financial mining
5
5
  Author-email: linsam <finmind.tw@gmail.com>
6
6
  License: Apache License
@@ -227,7 +227,7 @@ Requires-Dist: pydantic<3.0.0,>=2.0.0
227
227
  Requires-Dist: ta<1.0.0,>=0.11.0
228
228
  Requires-Dist: lxml<7.0.0,>=4.6.3
229
229
  Requires-Dist: pyecharts<2.0.0,>=1.9.0
230
- Requires-Dist: ipython<8.0.0,>=7.16.1
230
+ Requires-Dist: ipython<10.0.0,>=8.10.0
231
231
  Requires-Dist: loguru<1.0.0,>=0.5.3
232
232
  Requires-Dist: aiohttp<4.0.0,>=3.7.4.post0
233
233
  Requires-Dist: importlib-metadata<9.0.0,>=4.8.1
@@ -5,7 +5,7 @@ pydantic<3.0.0,>=2.0.0
5
5
  ta<1.0.0,>=0.11.0
6
6
  lxml<7.0.0,>=4.6.3
7
7
  pyecharts<2.0.0,>=1.9.0
8
- ipython<8.0.0,>=7.16.1
8
+ ipython<10.0.0,>=8.10.0
9
9
  loguru<1.0.0,>=0.5.3
10
10
  aiohttp<4.0.0,>=3.7.4.post0
11
11
  importlib-metadata<9.0.0,>=4.8.1
@@ -32,7 +32,7 @@ dependencies = [
32
32
  "ta>=0.11.0,<1.0.0",
33
33
  "lxml>=4.6.3,<7.0.0",
34
34
  "pyecharts>=1.9.0,<2.0.0",
35
- "ipython>=7.16.1,<8.0.0",
35
+ "ipython>=8.10.0,<10.0.0",
36
36
  "loguru>=0.5.3,<1.0.0",
37
37
  "aiohttp>=3.7.4.post0,<4.0.0",
38
38
  "importlib-metadata>=4.8.1,<9.0.0",
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes