Как правильно использовать аннотации функций Python3?

Я считаю, что это действительно здорово.

Исходя из академического опыта, я могу сказать вам, что аннотации оказались неоценимыми для включения интеллектуальных статических анализаторов для таких языков, как Java. Например, вы можете определить семантику, такую ​​как ограничения состояния, потоки, которым разрешен доступ, ограничения архитектуры и т. Д., И есть довольно много инструментов, которые затем могут читать их и обрабатывать их, чтобы обеспечить гарантии, выходящие за рамки того, что вы получаете от компиляторов. Вы даже можете написать вещи, которые проверяют предусловия / постусловия.

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

Есть и другие варианты использования аннотаций, не зависящие от уверенности. Я вижу, как применить свои инструменты на основе Java к Python. Например, у меня есть инструмент, который позволяет вам назначать специальные предупреждения для методов и дает вам указание, когда вы вызываете их, что вы должны прочитать их документацию (например, представьте, что у вас есть метод, который нельзя вызывать с отрицательным значением, но он не интуитивно понятно из названия). С аннотациями я мог бы технически написать что-то подобное для Python. Точно так же инструмент, который организует методы в большом классе на основе тегов, может быть написан при наличии официального синтаксиса.

Аннотации функций - это то, что вы из них делаете.

Их можно использовать для документации:

def kinetic_energy(mass: 'in kilograms', velocity: 'in meters per second'):
     ...

Их можно использовать для проверки предварительных условий:

def validate(func, locals):
    for var, test in func.__annotations__.items():
        value = locals[var]
        msg = 'Var: {0}\tValue: {1}\tTest: {2.__name__}'.format(var, value, test)
        assert test(value), msg


def is_int(x):
    return isinstance(x, int)

def between(lo, hi):
    def _between(x):
            return lo <= x <= hi
    return _between

def f(x: between(3, 10), y: is_int):
    validate(f, locals())
    print(x, y)


>>> f(0, 31.1)
Traceback (most recent call last):
   ... 
AssertionError: Var: y  Value: 31.1 Test: is_int

См. Также http://www.python.org/dev/peps/pep-0362/, чтобы узнать, как реализовать проверку типов.

Это слишком поздний ответ, но, AFAICT, лучшее текущее использование аннотаций функций - PEP-0484 и MyPy.

Mypy - это необязательная программа проверки статического типа для Python. Вы можете добавлять подсказки типов в свои программы Python, используя будущий стандарт для аннотаций типов, представленный в Python 3.5 beta 1 (PEP 484), и использовать mypy для проверки типов статически.

Используется так:

from typing import Iterator

def fib(n: int) -> Iterator[int]:
    a, b = 0, 1
    while a < n:
        yield a
        a, b = b, a + b

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

# This is in the 'mm' module

registry = {}
import inspect

class MultiMethod(object):
    def __init__(self, name):
        self.name = name
        self.typemap = {}
    def __call__(self, *args):
        types = tuple(arg.__class__ for arg in args) # a generator expression!
        function = self.typemap.get(types)
        if function is None:
            raise TypeError("no match")
        return function(*args)
    def register(self, types, function):
        if types in self.typemap:
            raise TypeError("duplicate registration")
        self.typemap[types] = function

def multimethod(function):
    name = function.__name__
    mm = registry.get(name)
    if mm is None:
        mm = registry[name] = MultiMethod(name)
    spec = inspect.getfullargspec(function)
    types = tuple(spec.annotations[x] for x in spec.args)
    mm.register(types, function)
    return mm

и пример использования:

from mm import multimethod

@multimethod
def foo(a: int):
    return "an int"

@multimethod
def foo(a: int, b: str):
    return "an int and a string"

if __name__ == '__main__':
    print("foo(1,'a') = {}".format(foo(1,'a')))
    print("foo(7) = {}".format(foo(7)))

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

Примечание. В Python вы можете обращаться к аннотациям как function.__annotations__, а не как function.func_annotations, поскольку стиль func_* был удален в Python 3.

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

Когда я впервые увидел аннотации, я подумал: «Отлично! Наконец-то я могу принять участие в проверке типов!» Конечно, я не заметил, что аннотации на самом деле не применяются.

Поэтому я решил написать простой декоратор функций для их применения:

def ensure_annotations(f):
    from functools import wraps
    from inspect import getcallargs
    @wraps(f)
    def wrapper(*args, **kwargs):
        for arg, val in getcallargs(f, *args, **kwargs).items():
            if arg in f.__annotations__:
                templ = f.__annotations__[arg]
                msg = "Argument {arg} to {f} does not match annotation type {t}"
                Check(val).is_a(templ).or_raise(EnsureError, msg.format(arg=arg, f=f, t=templ))
        return_val = f(*args, **kwargs)
        if 'return' in f.__annotations__:
            templ = f.__annotations__['return']
            msg = "Return value of {f} does not match annotation type {t}"
            Check(return_val).is_a(templ).or_raise(EnsureError, msg.format(f=f, t=templ))
        return return_val
    return wrapper

@ensure_annotations
def f(x: int, y: float) -> float:
    return x+y

print(f(1, y=2.2))

>>> 3.2

print(f(1, y=2))

>>> ensure.EnsureError: Argument y to <function f at 0x109b7c710> does not match annotation type <class 'float'>

Я добавил его в библиотеку Ensure.

Прошло много времени с тех пор, как об этом спрашивали, но приведенный в вопросе фрагмент примера (как указано там) из PEP 3107, а в конце этого примера PEP также приведены варианты использования, которые могут ответить на вопрос из точки PEP Посмотреть ;)

Ниже приводится цитата из PEP3107.

Примеры использования

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

• Providing typing information
  • Type checking ([3], [4])
  • Пусть IDE показывают, какие типы ожидает и возвращает функция ([17])
  • Перегрузка функций / общие функции ([22])
  • Иноязычные мосты ([18], [19])
  • Адаптация ([21], [20])
  • Функции логики предикатов
  • Отображение запросов к базе данных
  • Маршалинг параметров RPC ([23])
• Other information
  • Documentation for parameters and return values ([24])

См. PEP для получения дополнительной информации по конкретным вопросам (а также их ссылки).

Python 3.X (только) также обобщает определение функции, позволяя аннотировать аргументы и возвращаемые значения значениями объектов для использования в расширениях.

Его МЕТА-данные для объяснения, чтобы быть более точными в отношении значений функции.

Аннотации кодируются как :value после имени аргумента и перед значением по умолчанию и как ->value после списка аргументов.

Они собираются в атрибут __annotations__ функции, но в противном случае сам Python не рассматривает их как особые:

>>> def f(a:99, b:'spam'=None) -> float:
... print(a, b)
...
>>> f(88)
88 None
>>> f.__annotations__
{'a': 99, 'b': 'spam', 'return': <class 'float'>}

Источник: карманный справочник Python, пятое издание.

ПРИМЕР:

Модуль typeannotations предоставляет набор инструментов для проверки типов и вывода типов кода Python. Он также предоставляет набор типов, полезных для аннотирования функций и объектов.

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

https://github.com/ceronman/typeannotations

Как набор текста помогает писать лучший код

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

Чистый Python: элегантное кодирование на Python ISBN: ISBN-13 (pbk): 978-1-4842-4877-5

PEP 526 - синтаксис для аннотаций переменных

https://www.python.org/dev/peps/pep-0526/ < / а>

https://www.attrs.org/en/stable/types.html

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

В настоящее время это никоим образом не применяется, но, судя по PEP 484, будущие версии Python будут разрешать только типы в качестве значения для аннотаций.

Цитата Как насчет существующего использования аннотаций ?:

Мы действительно надеемся, что подсказки типов в конечном итоге станут единственным средством использования аннотаций, но это потребует дополнительного обсуждения и периода прекращения поддержки после первоначального развертывания модуля ввода с Python 3.5. Текущий PEP будет иметь предварительный статус (см. PEP 411) до тех пор, пока не будет выпущен Python 3.6. Самая быстрая из мыслимых схем будет вводить молчаливое прекращение поддержки аннотаций без подсказок типа в 3.6, полное исключение в 3.7 и объявление подсказок типов как единственное разрешенное использование аннотаций в Python 3.8.

Хотя я еще не видел никаких скрытых устаревших версий в 3.6, вместо этого вполне можно было бы повысить его до 3.7.

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

В качестве немного отложенного ответа некоторые из моих пакетов (marrow.script, WebCore и т. Д.) Также используют аннотации, где они доступны, для объявления преобразования типов (т. Е. Преобразования входящих значений из Интернета, определения того, какие аргументы являются логическими переключателями и т. Д.). как выполнить дополнительную разметку аргументов.

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

any_string  # documentation
any_callable  # typecast / callback, not called if defaulting
(any_callable, any_string)  # combination
AnnotationClass()  # package-specific rich annotation object
[AnnotationClass(), AnnotationClass(), …]  # cooperative annotation

«Чистая» поддержка строк документации или функций приведения типов упрощает смешивание с другими библиотеками, поддерживающими аннотации. (То есть есть веб-контроллер, использующий приведение типов, которое также может быть представлено в виде сценария командной строки.)

Отредактировано для добавления: Я также начал использовать TypeGuard пакет с использованием утверждений времени разработки для проверки. Преимущество: при запуске с включенной "оптимизацией" (-O / PYTHONOPTIMIZE env var) проверки, которые могут быть дорогостоящими (например, рекурсивными), опускаются, с мыслью о том, что вы правильно протестировали свое приложение в процессе разработки, поэтому проверки не нужны в производство.

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

def run(param1: int):
    """
    Does things.

    :param param1: Needed for counting.
    """
    pass

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

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

Если вы посмотрите на список преимуществ Cython, основным из них является возможность указать компилятору, к какому типу относится объект Python.

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