遅かれ早かれ、def handler(*args, **kwargs) のような関数を読んで、それが何を受け入れるのか疑問に思うでしょう。 Python *args と **kwargs を使用すると、関数は柔軟な数の引数を受け取ることができます。これらは、デコレータ、ラッパー、および多くのライブラリ API を強化します。

このガイドでは、Python が関数の呼び出し方法を制御できる新しい方法とともに、それらが両方向でどのように機能するかについて説明します。各例を Python 3.13 で実行し、示されている出力はその実行からのものです。

*args の機能

星 1 つで記述されたパラメータは、追加の位置引数をタプルに収集します。

def total(*args):
    print(type(args).__name__, args)
    return sum(args)

print(total(1, 2, 3))
# tuple (1, 2, 3)
# 6

print(total())
# tuple ()
# 0

引数を指定しない場合は、単に空のタプルを取得するだけなので、関数は引き続き機能します。 args という名前は慣例です。 *numbers も同じように動作しますが、多くの場合、よりわかりやすい名前の方が適しています。

**kwargs が行うこと

2 つの星は、追加のキーワード引数を辞書に収集します。

def describe(**kwargs):
    print(type(kwargs).__name__, kwargs)

describe(name="Asha", city="Pune")
# dict {'name': 'Asha', 'city': 'Pune'}

これは通常の 辞書 であるため、ループして get() でキーを検索し、渡すことができます。キーは渡された順序を維持します。

パラメータの順序

さまざまな種類のパラメーターを混合する場合、Python では特定の順序が必要です。

1. 通常の位置パラメータ
2. *引数
3. キーワードのみのパラメータ
4. **クワーグス

def order(item, qty=1, *extras, priority=False, **notes):
    print(item, qty, extras, priority, notes)

order("pen")
# pen 1 () False {}

order("pen", 2, "gift wrap", "card", priority=True, note="leave at door")
# pen 2 ('gift wrap', 'card') True {'note': 'leave at door'}

priority に注目してください。 *extras の後にあるため、名前でのみ設定できるため、位置引数が間違って設定されてしまう可能性はありません。 **kwargs を前に置くことは許可されておらず、テストでは SyntaxError:「引数を var-keyword 引数の後に続けることはできません」が発生しました。

電話時の開梱

同じスターがコール サイトで逆に機能します。 1 つの星はリストまたはタプルを位置引数に展開し、2 つの星は辞書をキーワード引数に展開します。

nums = [4, 5, 6]
total(*nums)            # same as total(4, 5, 6) -> 15

settings = {"name": "Ben", "city": "Delhi"}
describe(**settings)    # same as describe(name="Ben", city="Delhi")

アンパックは、*args と **kwargs を使用する関数だけでなく、どの関数でも機能します。これは、設定が辞書として届くときに便利です。

def connect(host, port, timeout=5):
    return f"{host}:{port} (timeout {timeout})"

connect(**{"host": "db.local", "port": 5432})
# 'db.local:5432 (timeout 5)'

connect(**{"host": "db.local", "port": 5432, "ssl": True})
# TypeError: connect() got an unexpected keyword argument 'ssl'

そのエラーは役に立ちます。 **kwargs のない関数は不明なオプションを拒否するため、設定名のタイプミスは黙って無視されるのではなく、大声で失敗します。

キーワードのみの引数

署名内の名前のない裸の * は、「これ以降はすべてキーワードで渡す必要がある」ことを意味します。

def make_user(name, *, admin=False):
    return name, admin

make_user("Asha", admin=True)
# ('Asha', True)

make_user("Asha", True)
# TypeError: make_user() takes 1 positional argument but 2 were given

これはブール フラグを保護する優れた方法です。 make_user("Asha", True) のような呼び出しでは、読者は True が何を意味するかを推測する必要があります。 admin=True を要求すると、すべての呼び出しが一目瞭然になります。

位置のみの引数

Python 3.8 以降、/ は位置によってのみ渡すことができるパラメータをマークします。

def area(width, height, /):
    return width * height

area(3, 4)                 # 12
area(width=3, height=4)
# TypeError: area() got some positional-only arguments
#   passed as keyword arguments: 'width, height'

これにより、誰も名前に依存することができないため、ライブラリは誰のコードも壊すことなく、後でこれらのパラメータの名前を変更できます。いくつかの組み込みはこのように動作します。たとえば、len(obj=[1]) は機能しません。

デコレータとラッパー

これが、両方を併用する現実的な主な理由です。ラッパーは多くの場合、元の関数が受け取る引数をすべて受け入れ、変更せずに渡す必要があります。

import functools, time

def timed(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        print(f"{func.__name__} took {time.perf_counter() - start:.4f}s")
        return result
    return wrapper

@timed
def slow_add(a, b, delay=0.01):
    time.sleep(delay)
    return a + b

print(slow_add(2, 3, delay=0.02))
# slow_add took 0.0205s
# 5

ラッパーは slow_add のパラメータをまったく知る必要がないため、どの関数でも機能します。タイミング図は若干異なります。 Python デコレータ に関するガイドでは、functools.wraps とその他の詳細について説明しています。

結合オプション

** は辞書リテラル内でも機能し、デフォルトに加えてオーバーライドを適用する巧妙な方法を提供します。

defaults = {"theme": "light", "lang": "en"}

def build(**overrides):
    return {**defaults, **overrides}

build(theme="dark")
# {'theme': 'dark', 'lang': 'en'}

後のキーが優先されるため、オーバーライドによってデフォルトが置き換えられます。 super().__init__(*args, **kwargs) のように、サブクラスもこのパターンを使用して、追加の引数を親クラスに渡します。 super() の詳細については、Python のクラスとオブジェクトを参照してください。

チートシート

それらを避けるべき場合

柔軟性には代償が伴います。 def create(**kwargs) として定義された関数は、どのオプションが存在するかについて読者に何も伝えず、編集者はオプションをオートコンプリートできません。タイプミスは、何かが失敗する前に、いくつかのレイヤーを静かに通過する可能性があります。

したがって、関数に必要なものがわかっている場合は、明示的なパラメーターを使用することをおすすめします。ラッパー、デコレーター、別の関数への引数の転送、または total(*numbers) のような真の可変長入力など、本当に柔軟性が必要な場合は *args と **kwargs を使用してください。関数に多くの名前付きオプションが必要な場合は、dataclass を使用するとわかりやすい場合もあります。

よくある間違い

変更可能なデフォルトの使用

これは星の話ではありませんが、星の近くに現れることがよくあります。デフォルト値は関数の定義時に一度作成され、呼び出し間で共有されます。

def bad(items=[]):
    items.append(1)
    return items

print(bad(), bad())
# [1, 1] [1, 1]

どちらの呼び出しでもまったく同じリストが返され、その時点で 2 つの項目が保持されていました。 items=None を使用して、関数内に新しいリストを作成します。

その他のエラー

• 解凍するのを忘れています。 total(nums) を呼び出すと、3 つの番号ではなく 1 つのリストが渡されます。 total(*nums)と書きます。
• タイプミスを飲み込みます。 **kwargs は受け入れますが、不明なキーを無視する関数は、スペルミスのあるオプションを非表示にします。それらを検証するか、**kwargs を避けてください。
• 同じ引数を 2 回渡す f(1, **{"a": 2}) (a が最初のパラメーター) と、「複数の値」エラーが発生します。
• ラッパーで転送しません。 func(args, kwargs) を呼び出すと、タプルと辞書が渡されます。正しい形式はfunc(*args, **kwargs)です。

*args と **kwargs の型ヒント

*args と **kwargs のタイプ ヒントは、コレクション全体ではなく、個々の値を説明します。これは多くの人を驚かせます:

def total(*prices: float) -> float:
    return sum(prices)      # prices is tuple[float, ...]

def tag(**attrs: str) -> str:
    return " ".join(f'{k}="{v}"' for k, v in attrs.items())   # dict[str, str]

total(1.5, 2.5)                  # 4.0
tag(id="x", role="button")       # id="x" role="button"

ここで、prices は浮動小数点数のタプルとして扱われ、attrs は文字列の辞書として扱われます。キーワード引数に異なる型がある場合、Python 3.12 では TypedDict と Unpack を組み合わせた正確なオプションが追加されました。

from typing import TypedDict, Unpack

class Options(TypedDict, total=False):
    timeout: float
    retries: int

def fetch(url: str, **opts: Unpack[Options]) -> None: ...

mypy や Pyright などの型チェッカーは、fetch(url, retries="3") やスペルミスのあるオプション名を拒否できますが、プレーンな **kwargs では決して拒否できません。ただし、実行時の動作は変わりません。 fetch("u", retries="3") を Python 3.13 で実行したところ、Python 自体は型ヒントを強制しないため、問題なく実行されました。

**kwargs で受け入れられるキーの長いリストを文書化している場合は、それらを明示的なキーワードのみのパラメーターに置き換えることを検討してください。編集者はそれらをオートコンプリートできるため、間違いはすぐに発見されます。

まとめ

2 つの方向を覚えておいてください。定義では、星は集まります。通話中に、彼らは開梱します。呼び出しを明確にするためにキーワードのみの引数を追加し、実際に引数を転送するコード用に **kwargs を予約します。練習するには、すべての呼び出しの引数を記録する小さなデコレーターを作成し、それをいくつかの異なる関数で使用します。

よくある質問

学び続ける