# -*- coding: utf-8 -*-
"""yfinance 台股用法實測腳本（對應文章「yfinance 台股怎麼抓」與「常用用法與陷阱」兩節）。

對應文章:
  https://finlab.finance/blog/python-global-index-yfinance-tutorial

執行方式（任一 Python 3.10+ 環境）:
  pip install yfinance
  python tw_usage_probe.py

或用 uv 免安裝執行:
  uv run --with yfinance python tw_usage_probe.py

口徑說明:
  - 文章數字由 yfinance 1.5.1 於 2026-07-09 實跑產出
  - 分鐘線／小時線的可取得範圍是 Yahoo 伺服器端的滾動限制，
    重跑時日期窗口會隨當天日期移動，筆數會略有不同
  - 還原收盤價（auto_adjust=True）會隨未來每次配息往下重算，
    不同日期抓到的歷史還原價數字不同，這是正常行為

投資警語: 本程式僅供教學用途，不構成投資建議，過去績效不代表未來表現。
"""
import warnings

import yfinance as yf

print("yfinance version:", yf.__version__)

# ---------- 1. 上櫃股票實抓: 5483.TWO 中美晶 ----------
print("\n=== 1. 5483.TWO 中美晶 period=max ===")
df_otc = yf.Ticker("5483.TWO").history(period="max")
print("rows:", len(df_otc))
print("first date:", df_otc.index[0], "first close:", round(df_otc["Close"].iloc[0], 2))
print("last date:", df_otc.index[-1], "last close:", round(df_otc["Close"].iloc[-1], 2))

# 寫錯後綴不會丟例外, 只會回傳空表
print("\n=== 1b. 寫錯後綴 5483.TW ===")
with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    df_wrong = yf.Ticker("5483.TW").history(period="max")
print("rows:", len(df_wrong))  # 0

# ---------- 2. 成交量單位: 股 vs 張 ----------
print("\n=== 2. 2330.TW 最近 3 日 Volume(股) ===")
df_t = yf.Ticker("2330.TW").history(period="1mo")
for idx, row in df_t[["Close", "Volume"]].tail(3).iterrows():
    print(idx.date(), "Close:", row["Close"],
          "Volume:", int(row["Volume"]), "股 =", round(row["Volume"] / 1000), "張")

# ---------- 3. 除權息紀錄 ----------
print("\n=== 3. 2330.TW Dividends ===")
div = yf.Ticker("2330.TW").history(period="max")["Dividends"]
div = div[div > 0]
print("total dividend events:", len(div))
print(div.tail(6))
print("2025 年配息合計:", round(div["2025"].sum(), 2), "元, 次數:", len(div["2025"]))

# ---------- 4. auto_adjust 同一檔同一天對照 ----------
print("\n=== 4. 2330.TW 2010-01-04 raw vs adjusted close ===")
raw = yf.Ticker("2330.TW").history(start="2010-01-01", end="2010-01-10", auto_adjust=False)
adj = yf.Ticker("2330.TW").history(start="2010-01-01", end="2010-01-10", auto_adjust=True)
print("raw close 2010-01-04:", round(raw["Close"].iloc[0], 2))   # 64.9
print("adj close 2010-01-04:", round(adj["Close"].iloc[0], 2))   # 39.71(截至 2026-07-09)

# ---------- 5. period / interval 實測限制 ----------
print("\n=== 5. interval 限制實測 (2330.TW) ===")
cases = [
    ("1m", "7d"),
    ("1m", "8d"),
    ("1m", "30d"),   # 超限 -> 空表
    ("5m", "60d"),
    ("5m", "61d"),   # 超限 -> 空表
    ("1h", "730d"),
    ("1h", "800d"),  # 超限 -> 空表
    ("1d", "max"),
]
for interval, period in cases:
    with warnings.catch_warnings():
        warnings.simplefilter("ignore")
        d = yf.Ticker("2330.TW").history(period=period, interval=interval)
    if len(d):
        print(f"interval={interval:>3} period={period:>4} -> rows={len(d):>6}  "
              f"{d.index[0]} ~ {d.index[-1]}")
    else:
        print(f"interval={interval:>3} period={period:>4} -> EMPTY")

# ---------- 6. 台股多檔批次下載(上市上櫃混抓) ----------
print("\n=== 6. yf.download 台股多檔批次 ===")
tickers = ["2330.TW", "2317.TW", "5483.TWO"]
batch = yf.download(tickers, start="2020-01-01", auto_adjust=True, progress=False)
close = batch["Close"]
print("shape:", close.shape)
print(close.tail(2).round(2))