【Python】デフォルト引数の正しい設定方法とNGパターンを一気に理解する

def greet(name, message="こんにちは"):
    """name 宛てに挨拶メッセージを表示する関数"""
    print(f"{name}さん、{message}")

greet("太郎")          # message を省略 → "こんにちは" が使われる
greet("花子", "おはよう")  # message を明示的に指定

def log(message, level="INFO"):
    """シンプルなログ出力関数"""
    print(f"[{level}] {message}")

log("処理を開始します")        # level を省略 → "INFO"
log("ファイルが見つかりません", level="WARNING")

def fetch_items(page=1, per_page=20):
    """page ページ目のデータを、per_page 件ずつ取得するイメージ関数"""
    print(f"{page=}, {per_page=}")

fetch_items()           # page=1, per_page=20
fetch_items(page=3)     # page=3, per_page=20
fetch_items(2, 50)      # page=2, per_page=50

def add_item(item, items=[]):
    """items に item を追加して返す(バグを含むNG例)"""
    items.append(item)
    return items

print(add_item("apple"))
print(add_item("banana"))
print(add_item("orange"))

import datetime

def log_created(message, created_at=datetime.datetime.now()):
    """作成時刻をログに出力する(バグを含むNG例)"""
    print(f"{created_at}: {message}")

import time

log_created("1回目のログ")
time.sleep(2)  # 2秒待つ
log_created("2回目のログ")
time.sleep(2)
log_created("3回目のログ")

def process(*items, limit=10):
    """items を最大 limit 件まで処理する関数"""
    print(f"{items=}, {limit=}")

process(1, 2, 3)
process(1, 2, 3, limit=5)

def process(limit=10, *items):
    """NGに近い例: 読み手にとって分かりづらい"""
    print(f"{items=}, {limit=}")

process(1, 2, 3)

def log_with_options(message, level="INFO", **kwargs):
    """kwargs に level を入れてしまう誤用例"""
    if "level" in kwargs:
        # kwargs 経由の level があると、引数 level と二重になる
        print("level が二重に指定されています")
    print(f"[{level}] {message} {kwargs=}")

def send_message(user_id: int = None):
    """型ヒントとデフォルト値が矛盾しているNG例"""
    ...

from typing import Optional

def send_message(user_id: Optional[int] = None):
    """None も OK であることを型にも反映した例"""
    ...

def send_message(user_id: int | None = None):
    ...

from typing import Optional, List

def add_item(item: str, items: Optional[List[str]] = None) -> list[str]:
    """items が None なら新しいリストを作って item を追加する"""
    if items is None:
        items = []  # 呼び出しごとに新しいリストを作る
    items.append(item)
    return items

print(add_item("apple"))
print(add_item("banana"))
print(add_item("orange", items=["grape"]))

def connect(host="localhost", port=5432, use_ssl=False):
    """データベース接続のためのパラメータ例"""
    print(f"host={host}, port={port}, use_ssl={use_ssl}")

connect()
connect(port=3306)
connect("db.example.com", use_ssl=True)

def download(url, timeout=5.0, retries=3):
    """
    URL からデータをダウンロードする関数

    timeout: 接続タイムアウト秒数(通常は 5 秒程度が妥当)
    retries: 一時的なエラー時のリトライ回数(3 回程度)
    """
    ...

def fetch_resource(
    user_id: int,
    resource: str,
    page: int = 1,
    per_page: int = 20,
    *,
    cache: bool = True,
    timeout: float = 5.0,
):
    """API からリソースを取得する関数の例"""
    ...

def download(
    url: str,
    page: int = 1,
    per_page: int = 100,
    cache: bool = True,
    timeout: float = 5.0,
):
    ...

download("https://example.com", 2, 50, False, 10.0)

download(
    "https://example.com",
    page=2,
    per_page=50,
    cache=False,
    timeout=10.0,
)

# v1
def search(query: str, limit: int = 10):
    """
    検索API v1
    - query: 検索クエリ
    - limit: 最大件数(デフォルト 10)
    """
    ...

# v2: fuzzy オプションを追加
def search(
    query: str,
    limit: int = 10,
    *,
    fuzzy: bool = False,  # 新機能はキーワード専用 + デフォルト値付き
):
    """
    検索API v2
    - fuzzy: あいまい検索を有効にするかどうか(デフォルト False)
    """
    ...

def parse_config(path: str, strict: bool | None = None):
    """
    設定ファイルを読み込む関数

    strict:
        - None の場合: 将来の挙動変更に備えて警告を出しつつ、現状は False と同じ扱い
        - True の場合: 厳密チェックを有効化
        - False の場合: 従来通りゆるいチェック
    """
    if strict is None:
        import warnings
        warnings.warn(
            "strict のデフォルト挙動は将来変更されます。"
            "明示的に True または False を指定してください。",
            DeprecationWarning,
            stacklevel=2,
        )
        strict = False  # 既存挙動
    ...

# app.py
from dataclasses import dataclass

@dataclass
class DownloadOptions:
    url: str
    page: int = 1
    per_page: int = 100
    cache: bool = True
    timeout: float = 5.0

def build_options(
    url: str,
    page: int = 1,
    per_page: int = 100,
    cache: bool = True,
    timeout: float = 5.0,
) -> DownloadOptions:
    """実際にダウンロードする代わりに、オプション構造体を返す"""
    return DownloadOptions(url, page, per_page, cache, timeout)

# test_app.py
from app import build_options

def test_build_options_default():
    """引数省略時にデフォルト値が正しく設定されることをテスト"""
    opt = build_options("https://example.com")
    assert opt.page == 1
    assert opt.per_page == 100
    assert opt.cache is True
    assert opt.timeout == 5.0

def test_build_options_override():
    """キーワード引数でデフォルト値を上書きできることをテスト"""
    opt = build_options(
        "https://example.com",
        page=2,
        per_page=50,
        cache=False,
        timeout=10.0,
    )
    assert opt.page == 2
    assert opt.per_page == 50
    assert opt.cache is False
    assert opt.timeout == 10.0