【Python】warningsモジュール入門: 非推奨の通知と使い方

# sample_deprecation.py
import warnings

def old_sum(a, b):
    # 非推奨を通知(最小例)
    warnings.warn("old_sum(a, b) は非推奨です。new_sum(a, b) を使用してください。", DeprecationWarning)
    return a + b

print(old_sum(1, 2))

# sample_message.py
import warnings

REMOVAL_VERSION = "2.0"

def old_api(x):
    # 分かりやすい移行案内を含める
    msg = (
        f"old_api(x) は非推奨です (削除予定: v{REMOVAL_VERSION})。"
        "代わりに new_api(x) を使用してください。"
        "移行ガイド: https://example.com/migration#old_api"
    )
    warnings.warn(msg, DeprecationWarning, stacklevel=2)  # stacklevel は後述
    return new_api(x)

def new_api(x):
    return x * 2

# 利用側
print(old_api(10))

# lib.py
import warnings

def old_api(x):
    # ユーザーの呼び出し位置を示したいので stacklevel=2
    warnings.warn("old_api(x) は非推奨です。new_api(x) を使ってください。", DeprecationWarning, stacklevel=2)
    return new_api(x)

def new_api(x):
    return x * 2

# main.py
from lib import old_api

def run():
    return old_api(5)

if __name__ == "__main__":
    print(run())

# sample_simplefilter.py
import warnings

def will_warn(msg):
    warnings.warn(f"注意: {msg}", UserWarning)

# 1) 既定相当(default): 同一箇所の警告は最初だけ表示
warnings.simplefilter("default")
print("\n=== filter: default ===")
will_warn("default")
will_warn("default")  # 同じ場所でも2回目は出ないことが多い

# 2) 常に表示(always)
warnings.simplefilter("always")
print("\n=== filter: always ===")
will_warn("always")
will_warn("always")  # 毎回表示される

# 3) 無視(ignore)
warnings.simplefilter("ignore")
print("\n=== filter: ignore ===")
will_warn("ignore フィルタ")  # 表示されない

# sample_filterwarnings.py
import warnings

def old_feature():
    warnings.warn("v2.0で削除予定: old_feature は非推奨", DeprecationWarning)

def risky_but_ok():
    warnings.warn("設定AとBの併用は非推奨です", UserWarning)

# まずは全体方針を default に
warnings.simplefilter("default")

# 1) DeprecationWarning のうち、old_feature に関するものは常に表示
warnings.filterwarnings(
    action="always",
    message=r".*old_feature.*",
    category=DeprecationWarning
)

# 2) UserWarning はこのモジュールでは無視
warnings.filterwarnings(
    action="ignore",
    category=UserWarning,
    module=r"^sample_filterwarnings$"
)

old_feature()     # 表示される(常に)
risky_but_ok()    # 無視される

# DeprecationWarning を常に表示
python -W always::DeprecationWarning your_script.py

# DeprecationWarning を例外に昇格(テストで有効)
python -W error::DeprecationWarning -m pytest

# 既定の挙動にする(一部環境で有効)
python -W default your_script.py

# Linux/macOS
export PYTHONWARNINGS="always::DeprecationWarning,ignore::UserWarning"
python your_script.py

# Windows (PowerShell)
$env:PYTHONWARNINGS="error::DeprecationWarning"
python your_script.py

# sample_catch_warnings.py
import warnings

def old_api():
    warnings.warn("old_api は非推奨です", DeprecationWarning)

# 1) 一時的に無視
with warnings.catch_warnings():
    warnings.simplefilter("ignore", DeprecationWarning)
    old_api()  # ここでは表示されない

# 2) 一時的に記録して検証
with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")  # 必ず記録されるように
    old_api()
    assert len(w) == 1
    rec = w[0]
    # rec.category, rec.message, rec.filename などで詳細を確認できる
    print(rec.category.__name__, str(rec.message))

# conftest.py や テストの先頭など
import warnings
warnings.simplefilter("error", DeprecationWarning)

pytest -W error::DeprecationWarning

export PYTHONWARNINGS="error::DeprecationWarning"
pytest