Рано или поздно вы прочитаете функцию типа def handler(*args, **kwargs) и задаетесь вопросом, что она принимает. Python *args и **kwargs позволяют функции принимать гибкое количество аргументов. Они поддерживают декораторы, оболочки и многие библиотечные API.

В этом руководстве рассказывается, как они работают в обоих направлениях, а также о новых способах, которыми Python позволяет управлять вызовом функции. Мы запускали каждый пример на Python 3.13, и показанный результат получен в результате этого запуска.

Что делает *args

Параметр, записанный с одной звездочкой, собирает все дополнительные позиционные аргументы в кортеж:

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

Две звездочки собирают в словарь любые дополнительные аргументы ключевого слова:

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».

Распаковка при звонке

Те же звезды работают в обратном порядке на месте призыва. Одна звездочка распределяет список или кортеж на позиционные аргументы, а две звезды распределяют словарь на аргументы ключевых слов:

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), ничего не сообщает читателям о том, какие параметры существуют, и редакторы не могут их автоматически заполнять. Опечатки могут незаметно пройти через несколько слоев, прежде чем что-то выйдет из строя.

Поэтому отдавайте предпочтение явным параметрам, если вы знаете, что нужно функции. Используйте *args и **kwargs, когда вам действительно нужна гибкость: обертки, декораторы, пересылка аргументов в другую функцию или настоящий ввод переменной длины, например total(*numbers). Если функции требуется много именованных опций, dataclass также может быть более понятным.

Распространенные ошибки

Использование изменяемого значения по умолчанию

Речь идет не о звездах, но она часто появляется возле них. Значение по умолчанию создается один раз при определении функции, а затем распределяется между вызовами:

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

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

Оба вызова вернули один и тот же список, который к тому времени содержал два элемента. Используйте items=None и создайте новый список внутри функции.

Другие ошибки

• Забыл распаковать. При вызове total(nums) передается один список, а не три номера. Напишите total(*nums).
• Проглатывает опечатки. Функция, которая принимает **kwargs, но игнорирует неизвестные ключи, скрывает параметры с ошибками. Подтвердите их или избегайте **kwargs.
• Двукратная передача одного и того же аргумента. 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, рассмотрите возможность замены их явными параметрами, содержащими только ключевые слова. Редакторы могут затем автоматически заполнять их, и ошибки сразу же выявляются.

Итоги

Помните о двух направлениях. По определению, звезды собираются. При звонке распаковывают. Добавьте аргументы, содержащие только ключевые слова, чтобы сделать вызовы более понятными, и зарезервируйте **kwargs для кода, который действительно пересылает аргументы. Для практики напишите небольшой декоратор, который регистрирует аргументы каждого вызова, и используйте его в нескольких различных функциях.

Часто задаваемые вопросы

Продолжайте учиться