Аннотации функций Python 3

Russian (Pусский) translation by Ilya Nikov (you can also view the original English article)

Аннотации функций - это функция Python 3, которая позволяет добавлять произвольные метаданные к аргументам функции и возвращаемому значению. Они были частью оригинальной спецификации Python 3.0.

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

Аннотации функций

Аннотации функций указаны в PEP-3107. Основная мотивация заключалась в том, чтобы обеспечить стандартный способ связывания метаданных с аргументами функции и возвращаемым значением. Многие члены сообщества обнаружили новые варианты использования, но использовали различные методы, такие как пользовательские декораторы, пользовательские форматы docstring и добавление пользовательских атрибутов к объекту функции.

Важно понимать, что Python не благословляет аннотации какой-либо семантикой. Он всего лишь обеспечивает синтаксическую поддержку для связывания метаданных, а также простой способ доступа к ней. Кроме того, аннотации полностью необязательны.

Давайте посмотрим на пример. Вот функция foo(), которая принимает три аргумента, называемых a, b и c, и печатает их сумму. Обратите внимание: foo() ничего не возвращает. Первый аргумент a не аннотируется. Второй аргумент b аннотируется строкой 'annotating b', а третий аргумент c аннотируется с типом int. Возвращаемое значение аннотируется типом float. Обратите внимание на синтаксис «->» для аннотирования возвращаемого значения.

1	def foo(a, b: 'annotating b', c: int) -> float:
2	print(a + b + c)

Аннотации не влияют на выполнение функции. Давайте назовем foo() дважды: один раз с аргументами int и один раз с строковыми аргументами. В обоих случаях foo() делает правильную вещь, и аннотации просто игнорируются.

foo('Hello', ', ', 'World!')
Hello, World!

foo(1, 2, 3)
6

Аргументы по умолчанию

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

def foo(x: 'an argument that defaults to 5' = 5):
    print(x)

foo(7)
7

foo()
5

Доступ к аннотации функций

Объект функции имеет атрибут 'annotations'. Это сопоставление, сопоставляющее каждое имя аргумента с его аннотацией. Аннотации возвращаемого значения сопоставляются с ключом «return», который не может конфликтовать с любым именем аргумента, потому что «return» является зарезервированным словом, которое не может служить именем аргумента. Обратите внимание, что можно передать аргумент ключевого слова с именем return в функцию:

def bar(*args, **kwargs: 'the keyword arguments dict'):
    print(kwargs['return'])

d = {'return': 4}
bar(**d)
4

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

def foo(a, b: 'annotating b', c: int) -> float:
    print(a + b + c)
    
print(foo.__annotations__)
{'c': <class 'int'>, 'b': 'annotating b', 'return': <class 'float'>}

Это довольно просто. Если вы аннотируете функцию с массивом аргументов и / или массивом аргументов аргументов, то, очевидно, вы не можете аннотировать отдельные аргументы.

def foo(*args: 'list of unnamed arguments', **kwargs: 'dict of named arguments'):
    print(args, kwargs)

print(foo.__annotations__)
{'args': 'list of unnamed arguments', 'kwargs': 'dict of named arguments'}

Если вы прочитали раздел о доступе к аннотации функций в PEP-3107, он говорит, что вы обращаетесь к ним через атрибут func_annotations объекта функции. Для Python 3.2 это устарело. Не путайте. Это просто атрибут annotations.

Что вы можете сделать с аннотациями?

Это большой вопрос. Аннотации не имеют стандартного значения или семантики. Существует несколько категорий общих применений. Вы можете использовать их в качестве лучшей документации и переместить аргумент и вернуть значение документации из docstring. Например, эта функция:

def div(a, b):
    """Divide a by b  
    args:
        a - the dividend
        b - the divisor (must be different than 0)
    return:
        the result of dividing a by b
    """
    return a / b

Может быть преобразована в:

1	def div(a: 'the dividend',
2	b: 'the divisor (must be different than 0)') -> 'the result of dividing a by b':
3	"""Divide a by b"""
4	return a / b

При сохранении той же информации в версии аннотаций есть несколько преимуществ:

Если вы переименуете аргумент, версия docstring документации может быть устаревшей.
Легче понять, не аргументирован ли аргумент.
Нет необходимости придумывать специальный формат аргументационной документации внутри docstring для анализа инструментами. Атрибут annotations обеспечивает прямой, стандартный механизм доступа.

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

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

Еще одно преимущество аннотаций над docstring заключается в том, что вы можете прикреплять различные типы метаданных в виде кортежей или dicts. Опять же, вы можете сделать это с помощью docstring, но он будет основан на тексте и потребует специального анализа.

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

Несколько аннотаций

Предположим, вы хотите аннотировать аргумент как своим типом, так и строкой справки. Это очень просто с аннотациями. Вы можете просто аннотировать аргумент с помощью dict, который имеет два ключа: «type» и «help».

def div(a: dict(type=float, help='the dividend'),
        b: dict(type=float, help='the divisor (must be different than 0)')
    ) -> dict(type=float, help='the result of dividing a by b'):
    """Divide a by b"""
    return a / b
    
print(div.__annotations__)
{'a': {'help': 'the dividend', 'type': float},
 'b': {'help': 'the divisor (must be different than 0)', 'type': float},
 'return': {'help': 'the result of dividing a by b', 'type': float}}

Комбинирование аннотаций и декораторов Python

Аннотации и декораторы идут рука об руку. Для хорошего ознакомления с декораторами Python ознакомьтесь со своими двумя учебниками: Погружаемся в декораторы Python и Пишем свои собственные декораторы Python.

Во-первых, аннотации могут быть полностью реализованы в качестве декораторов. Вы можете просто определить декоратор @annotate и взять его аргумент и выражение Python в качестве аргументов, а затем сохранить в атрибуте annotations целевой функции. Это можно сделать и для Python 2.

Однако реальная сила декораторов заключается в том, что они могут воздействовать на аннотации. Это требует координации, конечно, о семантике аннотаций.

Давайте посмотрим на примере. Предположим, мы хотим проверить, что аргументы находятся в определенном диапазоне. Аннотирование будет кортежем с минимальным и максимальным значением для каждого аргумента. Затем нам нужен декоратор, который будет проверять аннотацию каждого аргумента ключевого слова, проверять, что значение находится в пределах диапазона, и в противном случае кидать исключение. Начнем с декоратора:

def check_range(f):
    def decorated(*args, **kwargs):
        for name, range in f.__annotations__.items():
            min_value, max_value = range
            if not (min_value <= kwargs[name] <= max_value):
                msg = 'argument {} is out of range [{} - {}]'
                raise ValueError(msg.format(name, min_value, max_value))
        return f(*args, **kwargs)
    return decorated

Теперь давайте определим нашу функцию и украсим ее декораторами @check_range.

1	@check_range
2	def foo(a: (0, 8), b: (5, 9), c: (10, 20)):
3	return a * b - c

Вызовем foo() с разными аргументами и посмотрим, что произойдет. Когда все аргументы находятся в пределах их диапазона, проблем нет.

1	foo(a=4, b=6, c=15)
2	9

Но если мы установим c в 100 (вне диапазона (10, 20)), то возникает исключение:

1	foo(a=4, b=6, c=100)
2	ValueError: argument c is out of range [10 - 20]

Когда следует использовать декораторы вместо аннотаций?

Есть несколько ситуаций, когда декораторы лучше, чем аннотации для прикрепления метаданных.

Один очевидный случай: если ваш код должен быть совместим с Python 2.

Другой случай - если у вас много метаданных. Как вы видели ранее, хотя можно добавить любое количество метаданных с помощью dicts в виде аннотаций, это довольно громоздко и на самом деле вредит читабельности.

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

Динамические аннотации

Аннотации - это просто атрибут dict функции.

1	type(foo.__annotations__)
2	dict

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

def add(a, b) -> 0:
    result = a + b
    add.__annotations__['return'] += result
    return result
    
print(add.__annotations__['return'])
0

add(3, 4)
7
print(add.__annotations__['return'])
7

add(5, 5)
10
print(add.__annotations__['return'])
17

Заключение

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