Параметры функций в Python: args, kwargs, / и *

Обновлено:

В предыдущей теме мы познакомились со звёздочкой:

*

и увидели, что она может использоваться для:

  • распаковки итерируемых объектов;
  • упаковки нескольких значений при множественном присваивании.

Теперь посмотрим, как:

*

и:

**

используются при определении функций.


1. Обычная функция принимает определённое количество аргументов

Например:

def add_numbers(
    first,
    second,
):
    return first + second

Функция ожидает два обязательных аргумента:

add_numbers(
    10,
    20,
)

Результат:

30

Если передать только один:

add_numbers(10)

получим:

TypeError

Если передать три:

add_numbers(
    10,
    20,
    30,
)

тоже получим:

TypeError

Обычная функция ожидает то количество аргументов, которое позволяет её сигнатура.


*args

2. Неограниченное количество позиционных аргументов

Иногда заранее неизвестно, сколько позиционных аргументов будет передано.

Для этого перед именем параметра ставится:

*

Например:

def show_numbers(
    *args
):
    print(args)

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

show_numbers()
()

show_numbers(10)
(10,)

show_numbers(
    10,
    20,
    30,
    40,
)
(10, 20, 30, 40)

3. args — это tuple

Проверим:

def show_arguments(
    *args
):
    print(
        type(args)
    )


show_arguments(
    10,
    20,
    30,
)

Результат:

<class 'tuple'>

То есть все дополнительные позиционные аргументы упаковываются в:

tuple

После этого внутри функции с этим кортежем можно работать как с обычным объектом tuple.


4. Имя args не является специальным

Можно написать:

def show_numbers(
    *numbers
):
    print(numbers)

Это будет работать точно так же.

Главное здесь:

*

а не слово:

args

Но в Python существует общепринятая традиция использовать имя:

args

от слова:

arguments

Поэтому чаще всего мы увидим:

*args

5. Пример использования *args

Напишем функцию, которая складывает любое количество чисел:

def calculate_total(
    *numbers
):
    return sum(numbers)

Можно вызвать:

print(
    calculate_total(
        10,
        20,
    )
)

Результат:

30

print(
    calculate_total(
        10,
        20,
        30,
        40,
    )
)

Результат:

100

Даже:

print(
    calculate_total()
)

вернёт:

0

потому что внутри:

numbers

будет пустой кортеж:

()

print() как пример

6. Встроенная функция принимает любое количество объектов

Мы давно используем:

print(
    10,
    20,
    30,
    'Python',
)

Официальная сигнатура начинается так:

print(
    *objects,
    ...
)

То есть функция может принимать произвольное количество позиционных объектов. После них находятся параметры sep, end, file и flush, которые передаются только по имени. :chatgpt-content-reference{index="0"}

Обратите внимание: здесь используется имя:

objects

а не:

args

Это ещё раз показывает, что имя после * можно выбирать самостоятельно.


7. *args не собирает именованные аргументы

Например:

def show_arguments(
    *args
):
    print(args)

Так можно:

show_arguments(
    10,
    20,
)

Но:

show_arguments(
    first=10,
    second=20,
)

приведёт к:

TypeError

Потому что:

*args

собирает именно позиционные аргументы.

Для произвольного количества именованных аргументов существует другая конструкция.


**kwargs

8. Неограниченное количество именованных аргументов

Используем две звёздочки:

**

Например:

def show_user(
    **kwargs
):
    print(kwargs)

Теперь можно:

show_user(
    name='Alex',
    age=30,
    city='Tbilisi',
)

Получим:

{
    'name': 'Alex',
    'age': 30,
    'city': 'Tbilisi'
}

9. kwargs — это dict

def show_arguments(
    **kwargs
):
    print(
        type(kwargs)
    )


show_arguments(
    name='Alex',
    age=30,
)

Результат:

<class 'dict'>

Имена аргументов становятся ключами:

'name'
'age'

а переданные объекты становятся значениями:

'Alex'
30

10. Имя kwargs тоже не специальное

Можно написать:

def show_settings(
    **settings
):
    print(settings)

Но традиционно используется:

**kwargs

Название происходит от:

keyword arguments

то есть именованных аргументов.

Главное здесь снова не имя переменной, а:

**

11. Можно передать ноль именованных аргументов

def show_data(
    **kwargs
):
    print(kwargs)


show_data()

Результат:

{}

Можно один:

show_data(
    name='Alex'
)

Или много:

show_data(
    name='Alex',
    age=30,
    city='Tbilisi',
    language='Python',
)

dict.update() и **kwargs

12. Знакомый пример

Мы уже использовали:

user.update(
    age=30,
    city='Tbilisi',
)

Официальная документация действительно описывает варианты update() с:

**kwargs

в том числе:

update(**kwargs)

и:

update(mapping, /, **kwargs)

Метод может получать пары из отображения или итерируемого объекта, а дополнительные именованные аргументы превращаются в пары словаря. :chatgpt-content-reference{index="1"}

Поэтому:

user.update(
    age=30,
    city='Tbilisi',
)

хорошо демонстрирует принцип работы:

**kwargs

Обычные параметры вместе с *args

13. Сначала заполняются обычные параметры

Например:

def show_data(
    first,
    second,
    *args,
):
    print(first)
    print(second)
    print(args)

Вызов:

show_data(
    10,
    20,
    30,
    40,
    50,
)

даст:

10
20
(30, 40, 50)

Первые аргументы пошли в:

first
second

а всё оставшееся оказалось в:

args

14. Необязательный параметр перед *args

Можно написать:

def show_data(
    first,
    second=20,
    *args,
):
    print(
        first,
        second,
        args,
    )

Например:

show_data(10)

Получим:

10 20 ()

А:

show_data(
    10,
    30,
    40,
    50,
)

даст:

10 30 (40, 50)

Второй позиционный аргумент сначала заменил значение:

second=20

и только оставшиеся аргументы попали в:

args

Параметры после *args

15. Они становятся keyword-only

Рассмотрим:

def show_data(
    *args,
    mode,
):
    print(
        args,
        mode,
    )

Параметр:

mode

находится после:

*args

Поэтому его уже нельзя передать позиционно.

Правильно:

show_data(
    10,
    20,
    mode='short',
)

Получим:

(10, 20) short

Если написать:

show_data(
    10,
    20,
    'short',
)

то строка:

'short'

тоже попадёт в:

args

а параметр:

mode

останется без значения.

В результате возникнет:

TypeError

Параметры после *args являются keyword-only — их необходимо передавать по имени. :chatgpt-content-reference{index="2"}


Большой пример

16. Разбираем сигнатуру

Рассмотрим:

def f(
    a,
    b=2,
    *args,
    x,
    y=9,
    **kwargs,
):
    return (
        f'a={a}, '
        f'b={b}, '
        f'args={args}, '
        f'x={x}, '
        f'y={y}, '
        f'kwargs={kwargs}'
    )

Здесь находятся практически все основные виды параметров.


17. Параметр a

a

обязательный.

Но важно: поскольку перед ним нет специального:

/

это параметр типа:

positional-or-keyword

То есть его можно передать позиционно:

f(
    10,
    x=50,
)

или по имени:

f(
    a=10,
    x=50,
)

Оба варианта технически корректны.

Если нужно запретить:

a=10

понадобится /, который рассмотрим ниже.


18. Параметр b

b=2

необязательный.

Если значение не передано:

f(
    10,
    x=50,
)

используется:

b = 2

Но можно передать другое значение позиционно:

f(
    10,
    20,
    x=50,
)

Тогда:

a = 10
b = 20

Можно и по имени:

f(
    10,
    b=20,
    x=50,
)

Потому что b, как и a, находится до *args и не ограничен /.


19. *args

Все лишние позиционные аргументы после заполнения a и b попадут сюда:

args

Например:

print(
    f(
        10,
        20,
        30,
        40,
        50,
        x=100,
    )
)

Получим:

a=10,
b=20,
args=(30, 40, 50),
x=100,
y=9,
kwargs={}

20. Параметр x

x

находится после:

*args

и не имеет значения по умолчанию.

Поэтому это:

обязательный keyword-only параметр.

Его обязательно нужно передать:

x=...

Например:

f(
    10,
    x=50,
)

Так не получится:

f(
    10,
    20,
    30,
    40,
)

Дополнительные позиционные значения будут попадать в:

args

Они никогда не попадут в x.

В итоге Python сообщит, что обязательный keyword-only аргумент:

x

не был передан.


21. Параметр y

y=9

тоже находится после:

*args

Поэтому он keyword-only.

Но у него есть значение по умолчанию:

9

Можно ничего не передавать:

f(
    10,
    x=50,
)

или заменить значение:

f(
    10,
    x=50,
    y=100,
)

22. **kwargs

После всех известных параметров:

a
b
x
y

остальные именованные аргументы попадут в:

kwargs

Например:

print(
    f(
        10,
        x=50,
        color='blue',
        debug=True,
    )
)

Получим:

a=10,
b=2,
args=(),
x=50,
y=9,
kwargs={'color': 'blue', 'debug': True}

Обратите внимание:

x=50

не попало в kwargs.

Почему?

Потому что функция уже имеет отдельный параметр:

x

**kwargs собирает оставшиеся именованные аргументы, которые не были связаны с другими параметрами.


23. Более сложный вызов

print(
    f(
        1,
        5,
        10,
        20,
        30,
        x=100,
        y=200,
        debug=True,
        language='ru',
    )
)

Распределение:

a      → 1

b      → 5

args   → (10, 20, 30)

x      → 100

y      → 200

kwargs → {
    'debug': True,
    'language': 'ru',
}

Общая последовательность параметров

24. Полная схема

Функция в общем случае может выглядеть примерно так:

def function(
    positional_only,
    /,
    positional_or_keyword,
    *args,
    keyword_only,
    **kwargs,
):
    ...

Получаются несколько групп:

до /
↓
только позиционные


между / и *
↓
позиционные или именованные


*args
↓
дополнительные позиционные


после *args или *
↓
только именованные


**kwargs
↓
дополнительные именованные

Официальная документация Python разделяет параметры именно на эти категории. :chatgpt-content-reference{index="3"}


/ — positional-only

25. Запрещаем передачу по имени

Рассмотрим функцию:

def create_report(
    title,
    pages,
    /,
    *,
    file_type,
    copies,
):
    print(
        title,
        pages,
        file_type,
        copies,
    )

Здесь четыре обязательных параметра.


26. Параметры перед /

Перед:

/

находятся:

title
pages

Это параметры:

positional-only

Их можно передавать только позиционно.

Правильно:

create_report(
    'Python',
    120,
    file_type='pdf',
    copies=2,
)

Так нельзя:

create_report(
    title='Python',
    pages=120,
    file_type='pdf',
    copies=2,
)

Возникнет:

TypeError

Потому что параметры перед / запрещено передавать по имени. :chatgpt-content-reference{index="4"}


27. Что будет, если убрать /

Напишем:

def create_report(
    title,
    pages,
    *,
    file_type,
    copies,
):
    ...

Теперь:

title
pages

снова становятся обычными:

positional-or-keyword

И можно:

create_report(
    title='Python',
    pages=120,
    file_type='pdf',
    copies=2,
)

* без args

28. Звёздочку можно использовать отдельно

Необязательно писать:

*args

Можно поставить просто:

*

Например:

def create_report(
    title,
    pages,
    *,
    file_type,
    copies,
):
    ...

Здесь * ничего не собирает.

Она выполняет роль разделителя.

Все параметры после неё:

file_type
copies

становятся:

keyword-only

29. Их обязательно передавать по имени

Правильно:

create_report(
    'Python',
    120,
    file_type='pdf',
    copies=2,
)

Нельзя:

create_report(
    'Python',
    120,
    'pdf',
    2,
)

Возникнет:

TypeError

Параметры после отдельной * могут получать аргументы только по имени. :chatgpt-content-reference{index="5"}


30. Если убрать *

def create_report(
    title,
    pages,
    file_type,
    copies,
):
    ...

все четыре параметра становятся обычными:

positional-or-keyword

И такой вызов уже допустим:

create_report(
    'Python',
    120,
    'pdf',
    2,
)

Зачем ограничивать способ передачи аргументов

31. Читаемость

Представим:

create_report(
    'Python',
    120,
    True,
    False,
    5,
)

Не очень понятно, что означают:

True
False
5

Но:

create_report(
    'Python',
    120,
    color=True,
    double_sided=False,
    copies=5,
)

читается намного понятнее.

Поэтому некоторые параметры специально делают:

keyword-only

sorted() как реальный пример

32. Сигнатура

У встроенной функции:

sorted()

сигнатура выглядит так:

sorted(
    iterable,
    /,
    *,
    key=None,
    reverse=False,
)

То есть:

iterable

находится до / и является positional-only.

А:

key
reverse

находятся после * и являются keyword-only. :chatgpt-content-reference{index="6"}


Поэтому мы пишем:

numbers = [
    30,
    10,
    20,
]

sorted(
    numbers,
    reverse=True,
)

Так сразу понятно:

True

относится к параметру:

reverse

Нельзя написать:

sorted(
    iterable=numbers
)

потому что:

iterable

позиционный-only параметр.


sum() и /

33. Ещё один настоящий пример

В современных версиях Python сигнатура:

sum(
    iterable,
    /,
    start=0,
)

Здесь только:

iterable

является positional-only. :chatgpt-content-reference{index="7"}

Поэтому:

numbers = [
    10,
    20,
    30,
]

sum(numbers)

корректно.


Так нельзя:

sum(
    iterable=numbers
)

При этом параметр:

start

не находится после *, поэтому его можно передавать позиционно:

sum(
    numbers,
    100,
)

или по имени:

sum(
    numbers,
    start=100,
)

То есть наличие / не означает, что абсолютно все параметры функции становятся только позиционными.

Только параметры перед /.


Почему / и * полезны в собственных функциях

34. Более предсказуемый интерфейс

Например:

def calculate_price(
    price,
    quantity,
    /,
    *,
    discount=0,
    delivery=0,
):
    ...

Теперь:

price
quantity

передаются просто по позиции:

calculate_price(
    100,
    5,
    discount=10,
    delivery=20,
)

А необязательные настройки:

discount
delivery

обязательно имеют имена.

Такой вызов легко читать даже без просмотра определения функции.


** при вызове функции

35. Распаковка словаря

Две звёздочки используются не только в определении:

def function(
    **kwargs
):
    ...

но и при вызове функции.

Предположим:

def show_user(
    name,
    age,
    city,
):
    print(
        name,
        age,
        city,
        sep=' | ',
    )

Есть словарь:

user = {
    'name': 'Alex',
    'age': 30,
    'city': 'Tbilisi',
}

Можно написать:

show_user(
    **user
)

Результат:

Alex | 30 | Tbilisi

36. Что произошло

Словарь:

{
    'name': 'Alex',
    'age': 30,
    'city': 'Tbilisi',
}

при:

**user

распаковывается как именованные аргументы.

Можно представить вызов:

show_user(
    **user
)

примерно как:

show_user(
    name='Alex',
    age=30,
    city='Tbilisi',
)

Ключи становятся именами аргументов.

Значения становятся передаваемыми объектами.


37. Ключи должны подходить параметрам

Например:

user = {
    'username': 'Alex',
    'age': 30,
    'city': 'Tbilisi',
}

А функция ожидает:

def show_user(
    name,
    age,
    city,
):
    ...

Вызов:

show_user(
    **user
)

приведёт к:

TypeError

Потому что функция не имеет параметра:

username

и при этом обязательный параметр:

name

не получил значения.


38. Если ключа не хватает

user = {
    'name': 'Alex',
    'age': 30,
}

Функция:

def show_user(
    name,
    age,
    city,
):
    ...

Вызов:

show_user(
    **user
)

тоже приведёт к:

TypeError

Потому что обязательный параметр:

city

не получил аргумента.


39. Значения по умолчанию учитываются

Если функция:

def show_user(
    name,
    age,
    city='Unknown',
):
    print(
        name,
        age,
        city,
    )

то словаря:

user = {
    'name': 'Alex',
    'age': 30,
}

уже достаточно:

show_user(
    **user
)

Результат:

Alex 30 Unknown

Поэтому не обязательно, чтобы количество элементов словаря всегда точно совпадало с количеством параметров функции.

Важно, чтобы все обязательные параметры получили значения и не появилось неподдерживаемых именованных аргументов.


**dict вместе с **kwargs

40. Функция может принять дополнительные ключи

Например:

def show_user(
    name,
    **kwargs,
):
    print(
        name
    )

    print(
        kwargs
    )

Словарь:

user = {
    'name': 'Alex',
    'age': 30,
    'city': 'Tbilisi',
    'language': 'Python',
}

Вызываем:

show_user(
    **user
)

Получаем:

Alex

и:

{
    'age': 30,
    'city': 'Tbilisi',
    'language': 'Python'
}

Ключ:

name

был связан с отдельным параметром.

Остальные именованные аргументы попали в:

kwargs

* и ** при вызове

41. Можно распаковывать и список, и словарь

Функция:

def create_user(
    name,
    age,
    *,
    city,
    language,
):
    print(
        name,
        age,
        city,
        language,
    )

Есть:

main_data = [
    'Alex',
    30,
]

settings = {
    'city': 'Tbilisi',
    'language': 'Python',
}

Можно вызвать:

create_user(
    *main_data,
    **settings,
)

По смыслу получится:

create_user(
    'Alex',
    30,
    city='Tbilisi',
    language='Python',
)

То есть:

*iterable
→ распаковка в позиционные аргументы

**mapping
→ распаковка в именованные аргументы

Пять основных видов параметров

42. Итоговая классификация

Positional-only

Находятся перед:

/
def function(
    first,
    second,
    /,
):
    ...

Можно передавать только по позиции.


Positional-or-keyword

Обычные параметры:

def function(
    first,
    second,
):
    ...

Можно передавать:

function(
    10,
    20,
)

или:

function(
    first=10,
    second=20,
)

Var-positional

*args

Собирает дополнительные позиционные аргументы в:

tuple

Keyword-only

Находятся после:

*

или:

*args

Передаются только по имени.


Var-keyword

**kwargs

Собирает дополнительные именованные аргументы в:

dict

Главное по *args

def function(
    *args
):
    ...

позволяет функции получить произвольное количество позиционных аргументов.

Внутри:

args

является:

tuple

Имя:

args

является соглашением, а не специальным словом.


Главное по **kwargs

def function(
    **kwargs
):
    ...

позволяет получить произвольное количество дополнительных именованных аргументов.

Внутри:

kwargs

является:

dict

Имя:

kwargs

тоже является соглашением.


Главное по /

def function(
    first,
    second,
    /,
):
    ...

всё, что находится перед /, можно передать только позиционно:

function(
    10,
    20,
)

Главное по *

def function(
    first,
    *,
    second,
    third,
):
    ...

всё, что находится после *, нужно передавать по имени:

function(
    10,
    second=20,
    third=30,
)

Если вместо отдельной звёздочки есть:

*args

она одновременно:

  1. собирает дополнительные позиционные аргументы;
  2. делает следующие параметры keyword-only.

Главное по распаковке словаря

При вызове:

function(
    **dictionary
)

словарь распаковывается в именованные аргументы.

Например:

data = {
    'name': 'Alex',
    'age': 30,
}
show_user(
    **data
)

по смыслу соответствует:

show_user(
    name='Alex',
    age=30,
)

Полную сигнатуру можно читать слева направо:

def function(
    positional_only,
    /,
    positional_or_keyword,
    *args,
    keyword_only,
    **kwargs,
):
    ...
позиционные-only
        ↓
        /
        ↓
позиционные или именованные
        ↓
      *args
        ↓
только именованные
        ↓
     **kwargs

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