Рекомендации по использованию аннотаций

Доступ к словарю аннотаций объекта в Python 3.10 и новее

Python 3.10 добавляет новую функцию в стандартную библиотеку: inspect.get_annotations(). В версиях Python 3.10 и новее использование этой функции является лучшей практикой для доступа к словарю аннотаций любого объекта, поддерживающего аннотации. Эта функция также может «развернуть» строковые аннотации для вас.

Если по какой-то причине inspect.get_annotations() не подходит для вашего случая, вы можете получить доступ к __annotations__ члену вручную. Лучшая практика для этого также изменилась в Python 3.10: начиная с Python 3.10, o.__annotations__ гарантированно всегда работает с Python-функциями, классами и модулями. Если вы уверены, что исследуемый вами объект является одним из этих трех конкретных объектов, вы можете просто использовать o.__annotations__ для получения словаря аннотаций объекта.

Однако, другие типы вызываемых объектов – например, вызываемые объекты, созданные с помощью functools.partial() – могут не иметь определенного атрибута __annotations__. При доступе к __annotations__ потенциально неизвестного объекта лучшей практикой в версиях Python 3.10 и новее является вызов getattr() с тремя аргументами, например, getattr(o, '__annotations__', None).

До Python 3.10 доступ к __annotations__ класса, который не определяет аннотаций, но у которого есть родительский класс с аннотациями, возвращал аннотации родительского класса __annotations__. В Python 3.10 и новее аннотации дочернего класса будут пустым словарем.

Доступ к словарю аннотаций объекта в Python 3.9 и более ранних версиях

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

Лучшая практика доступа к словарю аннотаций других объектов — функций, других вызываемых объектов и модулей — такая же, как и для версии 3.10, если вы не вызываете inspect.get_annotations(): вы должны использовать getattr() с тремя аргументами для доступа к атрибуту __annotations__ объекта.

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

class Base:
    a: int = 3
    b: str = 'abc'

class Derived(Base):
    pass

print(Derived.__annotations__)

Это выведет словарь аннотаций из Base, а не из Derived.

Ваш код должен иметь отдельный путь, если исследуемый вами объект является классом (isinstance(o, type)). В этом случае лучшая практика основана на реализации детали Python 3.9 и более ранних версий: если у класса определены аннотации, они хранятся в словаре __dict__ класса. Поскольку у класса могут или могут не быть определены аннотации, лучшая практика заключается в вызове метода get для словаря класса.

Для обобщения, вот пример кода, который безопасно получает доступ к атрибуту __annotations__ любого объекта в Python 3.9 и более ранних версиях:

if isinstance(o, type):
    ann = o.__dict__.get('__annotations__', None)
else:
    ann = getattr(o, '__annotations__', None)

После выполнения этого кода, ann должен быть либо словарем, либо None. Рекомендуется проверять тип ann с помощью isinstance() перед дальнейшим исследованием.

Обратите внимание, что некоторые экзотические или неправильно сформированные типы объектов могут не иметь атрибута __dict__, поэтому для дополнительной безопасности вы также можете использовать getattr() для доступа к __dict__.

Ручное разворачивание строковых аннотаций

В ситуациях, когда некоторые аннотации могут быть «строковыми», и вы хотите оценить эти строки для получения представляющих их значений Python, лучше всего вызвать inspect.get_annotations() для выполнения этой работы.

Если вы используете Python 3.9 или более раннюю версию, или по какой-то причине не можете использовать inspect.get_annotations(), вам нужно будет дублировать его логику. Рекомендуется изучить реализацию inspect.get_annotations() в текущей версии Python и следовать аналогичному подходу.

Вкратце, если вы хотите оценить строковую аннотацию произвольного объекта o:

• Если o — модуль, используйте o.__dict__ в качестве globals при вызове eval().
• Если o — класс, используйте sys.modules[o.__module__].__dict__ в качестве globals, и dict(vars(o)) в качестве locals, при вызове eval().
• Если o — обернутая функция, использующая functools.update_wrapper(), functools.wraps() или functools.partial(), рекурсивно разворачивайте ее, обращаясь к o.__wrapped__ или o.func по мере необходимости, пока не найдете исходную необработанную функцию.
• Если o — вызываемый объект (но не класс), используйте o.__globals__ в качестве глобальных значений при вызове eval().

Однако не все строковые значения, используемые в качестве аннотаций, могут быть успешно преобразованы в значения Python с помощью eval(). Теоретически строковые значения могут содержать любые допустимые строки, и на практике существуют допустимые варианты использования подсказок типов, требующие аннотирования строками, которые не могут быть оценены. Например:

• PEP 604 типы объединения с использованием |, до добавления поддержки в Python 3.10.
• Определения, которые не нужны во время выполнения, а импортируются только когда typing.TYPE_CHECKING истинно.

Если eval() пытается оценить такие значения, это приведет к ошибке и исключению. Поэтому при разработке API библиотеки, работающей с аннотациями, рекомендуется пытаться оценивать строковые значения только по явному запросу вызывающего лица.

Рекомендации по аннотациям в любой версии Python

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

__annotations__ Причуды

Во всех версиях Python 3 объекты функций лениво создают словарь аннотаций, если аннотации не определены для этого объекта. Вы можете удалить атрибут __annotations__ с помощью del fn.__annotations__, но если вы затем обратитесь к fn.__annotations__, объект создаст новый пустой словарь, который он сохранит и вернёт в качестве своих аннотаций. Удаление аннотаций функции до того, как она лениво создала свой словарь аннотаций, вызовет AttributeError; использование del fn.__annotations__ дважды подряд гарантированно всегда вызовет AttributeError.

Всё вышесказанное также относится к объектам классов и модулей в Python 3.10 и более поздних версиях.

Во всех версиях Python 3 вы можете установить __annotations__ для объекта функции в None. Однако последующий доступ к аннотациям этого объекта с помощью fn.__annotations__ лениво создаст пустой словарь, как указано в первом абзаце этого раздела. Это не относится к модулям и классам в любой версии Python; эти объекты позволяют установить __annotations__ в любое значение Python и сохранят то значение, которое было установлено.

Если Python строит ваши аннотации для вас (используя from __future__ import annotations), и вы указываете строку в качестве аннотации, строка сама будет заключена в кавычки. По сути, аннотация заключена в дважды кавычки. Например:

from __future__ import annotations
def foo(a: "str"): pass

print(foo.__annotations__)

Это выведет {'a': "'str'"}. Это на самом деле не следует считать «причудой»; это упомянуто здесь просто потому, что это может быть неожиданным.