跳轉到

積木 Block 總覽

所屬章節：積木 Block 以 2026-09-21 實際執行結果為準（台股 405 個積木、美股 260 個）

Overview

api.Block 把選股條件包成「積木」：每個積木是一個具名條件，帶固定的參數與合法值。 組好一組積木後交給 screener，回傳符合條件的股票清單、中間計算值，以及等價的可執行程式碼。

台股與美股各一組同名結尾的方法，market 已綁定，呼叫端不用再傳：

台股 美股 用途
get_table_tw() get_table_us() 每個積木的參數與合法值
con_tw(name, **params) con_us(name, **params) 組出一個積木 dict
screener_tw(block_list, pool=None, date='now') screener_us(block_list, date='now') 執行選股

找不到合用的積木？ 405 顆原生積木都把窗格、聚合、位移、倍數寫死在 class 裡， 參數合法值清單外的需求一律無解。這時用通用積木的 a1/a2/a3—— 把這些全部參數化，29 條常見條件（KD／MACD／RSI／布林／ADX／K棒型態／財報／營收／排行） 實測全部組得出來。

標準流程

# 1. 查有哪些積木、參數能填什麼
api.Block.get_table_tw()['今日收盤價<>開高低P%']
# {'id': 'o1',
#  'operator': ['<', '>'],
#  'ohlc_field': ['adj_Open', 'adj_High', 'adj_Low'],
#  'percent': [1, 2, 3, 5, 7, 9]}

# 2. 組積木（不指定的參數走預設值；也可用 id='o1' 或整包 dict 指定積木）
b1 = api.Block.con_tw('今日收盤價<>開高低P%',
                      operator='>', ohlc_field='adj_High', percent=3)
# {'id': 'o1', 'operator': '>', 'ohlc_field': 'adj_High', 'percent': 3,
#  'close_field': 'adj_Close', 'period': 1}      <- 尾端是規格固定值，con 自動補

# 3. 執行（多個積木是 AND）
r = api.Block.screener_tw([b1])

# 4. 取用
r['dataframe']   # 符合的股票 + 各積木的中間值
r['date']        # 這批結果對應的資料日期
r['sig']         # 完整訊號矩陣（日期 × 股票代號 的 bool）
r['code']        # 等價的可執行 python（作用域有 api 就能跑）

Manual Sample Input/Output

Example 1：積木數量

input

len(api.Block.get_table_tw()), len(api.Block.get_table_us())

output

(405, 260)

input

from snowyowl.blocks import list_conditions
len(list_conditions(market='tw')), len(list_conditions(market='us'))

output

(409, 301)

list_conditions 比 get_table 多，因為前者讀 condition registry（程式碼裡註冊的 全部類別），後者讀 block_spec.json（只收 Excel 中「狀態＝啟用」的積木）。 多出來的積木無法用 con 建立，詳見 積木清單查詢。 list_conditions 不是 api.Block 的方法，要從 snowyowl.blocks 匯入。

Example 2：完整一次選股

input

b1 = api.Block.con_tw('今日收盤價<>開高低P%',
                      operator='>', ohlc_field='adj_High', percent=3)
b2 = api.Block.con_tw('今日收盤價(開低高)與近D日內最高價<P%',
                      period=20, percent=5)
r = api.Block.screener_tw([b1, b2])
print(r['date'], r['dataframe'].shape)
r['dataframe'].head(3)

output

2026-08-19 00:00:00 (816, 13)

  stock_id   sig  cond1_sig  cond1_close  cond1_ohlcData  cond1_olhc_metrics  cond1_comparison_ratio  cond2_sig  cond2_close  cond2_high  cond2_rolling_high  cond2_distance_pct
0   00400A  True       True      14.7200         14.3600             10.7500                  1.3294       True      14.5100     14.7200             15.1700              4.5486
1   00401A  True       True      13.3800         13.1500             10.5000                  1.2372       True      13.2600     13.3800             13.8200              4.2232
2   00402A  True       True       9.7200          9.6300              8.9000                  1.0603       True       9.6400      9.7200              9.9800              3.5270

積木彼此是 AND，可以自己驗證：

積木1 單獨 = 2343 檔
積木2 單獨 = 1040 檔
兩者 AND  =  816 檔

相關文件