Всем привет. Я решил полностью разобраться в пайтоновских аннотациях и заодно перевести цикл PEP-ов, документирующих эту тему. Мы начнём со стандартов версии 3.X и закончим нововведениями в python 3.8. Сразу говорю, что этот PEP — один из самых базовых и его прочтение пригодится лишь новичкам. Ну что же, поехали:
Данный PEP вводит синтаксис для добавления произвольных аннотаций (метаданных) к функциям в Python.
У функций в версии Python 2.x отсутствовал встроенный способ аннотирования параметров и возвращаемых значений. Для устранения этого пробела появилось множество инструментов и библиотек. Некоторые из них используют декораторы, описанные в PEP 318, в то время как другие анализируют docstring функции и ищут там информацию.
Этот PEP призван обеспечить единый, стандартный способ аннотирования функций, чтобы уменьшить существовавшую до этого момента путаницу, вызванную широким разбросом в механизмах и синтаксисе.
Прежде чем приступить к обсуждению аннотаций функций Python 3.0, давайте сначала в общих чертах поговорим об их особенностях:
Аннотации параметров представляют из себя необязательные выражения, следующие за именем самого параметра:
В псевдограмматике параметры теперь выглядят как: параметр [: выражение] [= выражение]. То есть аннотации, как и значения по умолчанию, являются необязательными и всегда предшествуют последним. В точности также, как знак равенства используется для обозначения значения по умолчанию, двоеточие используется для аннотаций. Все аннотационные выражения, как и значения по умолчанию, оцениваются при выполнении определения функции. Получение «дополнительных» аргументов (т.е. *args и **kwargs) имеет такой же синтаксис:
Аннотации для вложенных параметров всегда следуют за именем параметра, а не за последней скобкой. Аннотирование каждого «имени» во вложенном параметре не требуется:
До сих пор мы не привели пример того, как аннотировать тип возвращаемого значения в функциях. Это делается так:
То есть за списком параметров теперь может следовать литерал -> и какое-то выражение. Как и аннотации параметров, это выражение будет оцениваться при выполнении определения функции.
Полная грамматика объявления функций теперь такова:
Lambda функции не поддерживают аннотации. Конечно, синтаксис можно было поправить, добавив возможность «оборачивать» аргументы в скобки, однако было решено не вносить такие изменение, потому что:
После компиляции, аннотации функции становятся доступны через атрибут __annotations__. Этот атрибут представляет собой изменяемый словарь, сопоставляющий имена переменных и значения указанных к ним аннотаций.
В словаре __annotations__ есть специальный ключ «return». Этот ключ присутствует только в том случае, если для возвращаемого значения функции была также определена ??аннотация. Например, следующая аннотация:
Будет возвращена через атрибут __annotations__ как:
Имя ключа «return» было выбрано из-за того, что оно не может конфликтовать с именем параметра (любая попытка использовать return в качестве имени параметра приведет к исключению SyntaxError).
Атрибут __annotations__ будет пустым, если в функции нет аннотаций или же функция была создана через лямбда-выражение.
В ходе обсуждения аннотаций, мы рассмотрели несколько вариантов их использования. Некоторые из них представлены здесь и сгруппированы в зависимости от «класса» информации, которую передают. Также сюда были включены примеры существующих продуктов и пакетов, которые могут использовать аннотирование.
Модуль pydoc будет отображать аннотации в справочной информации о функциях. Модуль inspect изменится и будет поддерживать аннотации.
Объекты подписи функции должны предоставлять аннотации функций. Объект Parameter и другие вещи могут измениться. [прим. Подпись (Сигнатура) функции — часть её общего объявления, позволяющая средствам трансляции идентифицировать функцию среди других]
Эталонная реализация была включена в ветку py3k (ранее «p3yk») как ревизия 53170
PEP 572 — Аннотации в функциях
| PEP | 3107 |
| Название: | Аннотации в функциях |
| Авторы: | Collin Winter <collinwinter at google.com>, Tony Lownds <tony at lownds.com> |
| Статус: | Окончательный |
| Тип: | Стандарт |
| Создано: | 2-Dec-2006 |
| Версия Python: | 3.0 |
Аннотация к стандарту
Данный PEP вводит синтаксис для добавления произвольных аннотаций (метаданных) к функциям в Python.
Обоснование
У функций в версии Python 2.x отсутствовал встроенный способ аннотирования параметров и возвращаемых значений. Для устранения этого пробела появилось множество инструментов и библиотек. Некоторые из них используют декораторы, описанные в PEP 318, в то время как другие анализируют docstring функции и ищут там информацию.
Этот PEP призван обеспечить единый, стандартный способ аннотирования функций, чтобы уменьшить существовавшую до этого момента путаницу, вызванную широким разбросом в механизмах и синтаксисе.
Основы аннотаций в функциях
Прежде чем приступить к обсуждению аннотаций функций Python 3.0, давайте сначала в общих чертах поговорим об их особенностях:
- Аннотации для параметров и возвращаемых значений функций являются полностью необязательными.
- Аннотации — не более чем способ связать произвольные выражения к различными частями функции во время компиляции.
Сам по себе Python не обращает никакого внимания на аннотации. Единственное, он позволяет получить доступ к ним, что описано в разделе «Получаем доступ к аннотациям функций» ниже.
Аннотации приобретают смысл лишь когда интерпретируются сторонними библиотеками. Они могут делать с аннотациями функций всё, что захотят. Например, одна библиотека может использовать строковые аннотации, чтобы предоставить улучшенные справочные данные, например:
def compile(source: "something compilable", filename: "where the compilable thing comes from", mode: "is this a single statement or a suite?"): ...
Другая же библиотека может использовать аннотации функций и методов Python для проверки соответствия типов. Эта библиотека может использовать аннотации для того чтобы показать, какие типы входных данных она ожидает и какой тип данных она вернёт. Возможно, это будет что-то в таком духе:
def haul(item: Haulable, *vargs: PackAnimal) -> Distance: ...
Ещё раз повторимся: аннотации ни одного из примеров сами по себе не имеют никакого значения. Настоящий смысл они приобретают только в комбинации со сторонними библиотеками.
- Как следует из пункта 2, этот PEP не пытается ввести какой-либо стандартный механизм обработки аннотаций даже для встроенных типов. Вся эта работа возлагается на сторонние библиотеки
Синтаксис
Параметры
Аннотации параметров представляют из себя необязательные выражения, следующие за именем самого параметра:
def foo (a: выражение, b: выражение = 5):
...В псевдограмматике параметры теперь выглядят как: параметр [: выражение] [= выражение]. То есть аннотации, как и значения по умолчанию, являются необязательными и всегда предшествуют последним. В точности также, как знак равенства используется для обозначения значения по умолчанию, двоеточие используется для аннотаций. Все аннотационные выражения, как и значения по умолчанию, оцениваются при выполнении определения функции. Получение «дополнительных» аргументов (т.е. *args и **kwargs) имеет такой же синтаксис:
def foo(*args: expression, **kwargs: expression):
...Аннотации для вложенных параметров всегда следуют за именем параметра, а не за последней скобкой. Аннотирование каждого «имени» во вложенном параметре не требуется:
def foo((x1, y1: expression),
(x2: expression, y2: expression)=(None, None)):
...Возвращаемые значения
До сих пор мы не привели пример того, как аннотировать тип возвращаемого значения в функциях. Это делается так:
def sum() -> expression:
...То есть за списком параметров теперь может следовать литерал -> и какое-то выражение. Как и аннотации параметров, это выражение будет оцениваться при выполнении определения функции.
Полная грамматика объявления функций теперь такова:
decorator: '@' dotted_name [ '(' [arglist] ')' ] NEWLINE
decorators: decorator+
funcdef: [decorators] 'def' NAME parameters ['->' test] ':' suite
parameters: '(' [typedargslist] ')'
typedargslist: ((tfpdef ['=' test] ',')*
('*' [tname] (',' tname ['=' test])* [',' '**' tname]
| '**' tname)
| tfpdef ['=' test] (',' tfpdef ['=' test])* [','])
tname: NAME [':' test]
tfpdef: tname | '(' tfplist ')'
tfplist: tfpdef (',' tfpdef)* [',']Лямбды
Lambda функции не поддерживают аннотации. Конечно, синтаксис можно было поправить, добавив возможность «оборачивать» аргументы в скобки, однако было решено не вносить такие изменение, потому что:
- Это нарушило бы обратную совместимость.
- Лямбды нейтральны и анонимны по своему определению
- Лямбды можно всегда переписать в виде функций
Получаем доступ к аннотациям функций
После компиляции, аннотации функции становятся доступны через атрибут __annotations__. Этот атрибут представляет собой изменяемый словарь, сопоставляющий имена переменных и значения указанных к ним аннотаций.
В словаре __annotations__ есть специальный ключ «return». Этот ключ присутствует только в том случае, если для возвращаемого значения функции была также определена ??аннотация. Например, следующая аннотация:
def foo (a: 'x', b: 5 + 6, c: list) -> max (2, 9):
...Будет возвращена через атрибут __annotations__ как:
{'a': 'x',
'b': 11,
'c': list,
'return': 9}Имя ключа «return» было выбрано из-за того, что оно не может конфликтовать с именем параметра (любая попытка использовать return в качестве имени параметра приведет к исключению SyntaxError).
Атрибут __annotations__ будет пустым, если в функции нет аннотаций или же функция была создана через лямбда-выражение.
Случаи использования
В ходе обсуждения аннотаций, мы рассмотрели несколько вариантов их использования. Некоторые из них представлены здесь и сгруппированы в зависимости от «класса» информации, которую передают. Также сюда были включены примеры существующих продуктов и пакетов, которые могут использовать аннотирование.
- Предоставление информации о типах
- Проверка типа
- Подсказки от IDE об ожидаемых и возвращаемых типах аргументов
- Перегрузка функций/generic функции [прим. перегрузка функций популярна в других языках и заключается в существовании нескольких функций с одинаковыми именами, но при этом, количество принимаемых ими параметров различается]
- «Мосты» между разными языками программирования
- Адаптация
- Предикатные логические функции
- Mapping запроса к базе данных
- Маршалинг параметров RPC [прим. Маршалинг — процесс преобразования информации, хранящейся в оперативной памяти, в формат, пригодный для хранения или передачи. RPC — удалённый вызов процедур]
- Предоставление другой информации
- Документирование параметров и возвращаемых значений
Стандартная библиотека
Модули pydoc и inspect
Модуль pydoc будет отображать аннотации в справочной информации о функциях. Модуль inspect изменится и будет поддерживать аннотации.
Связь с другими PEP
Объекты подписи функций
Объекты подписи функции должны предоставлять аннотации функций. Объект Parameter и другие вещи могут измениться. [прим. Подпись (Сигнатура) функции — часть её общего объявления, позволяющая средствам трансляции идентифицировать функцию среди других]
Реализация
Эталонная реализация была включена в ветку py3k (ранее «p3yk») как ревизия 53170
Отклоненные предложения
- BDFL [прим. великодушный пожизненный диктатор] отклонил идею автора о добавлении специального синтаксиса, который позволил бы писать аннотации к генераторам, по причине: «Слишком уродливо»
- Хоть включение специальных объектов в stdlib для аннотирования функций генераторов и функций более высокого порядка и обсуждалось на ранних этапах, в конечном итоге эта идея была отклонена, как более подходящая для сторонних библиотек. Включение такого в стандартную библиотеку вызвало бы слишком много острых вопросов.
- Несмотря на значительные дискуссии о стандартном синтаксисе параметризации типов, было решено, что эту реализацию также следует оставить за сторонними библиотеками.
- Несмотря на дальнейшее обсуждение, было решено не стандартизировать механизм взаимодействия аннотаций. Такое соглашение на данном этапе было бы преждевременным. Мы хотим позволить этим соглашениям развиваться органично, основываясь на реальной ситуации, а не пытаться заставить всех пользоваться какой-то надуманной схемой.