¿Cuáles son los buenos usos de las "Anotaciones de funciones" de Python3?

Anotaciones de funciones: PEP-3107

Me encontré con un fragmento de código que demuestra las anotaciones de funciones de Python3. El concepto es simple, pero no puedo pensar por qué se implementaron en Python3 o cualquier buen uso para ellos. ¿Quizás SO puede iluminarme?

Cómo funciona:

def foo(a: 'x', b: 5 + 6, c: list) -> max(2, 9):
    ... function body ...

Todo lo que sigue a los dos puntos después de un argumento es una 'anotación', y la información que sigue ->es una anotación para el valor de retorno de la función.

foo.func_annotations devolvería un diccionario:

{'a': 'x',
 'b': 11,
 'c': list,
 'return': 9}

¿Cuál es el significado de tener esto disponible?

Creo que esto es realmente genial.

Viniendo de una formación académica, puedo decirle que las anotaciones han demostrado ser invaluables para permitir analizadores estáticos inteligentes para lenguajes como Java. Por ejemplo, podría definir la semántica como restricciones de estado, subprocesos a los que se les permite acceder, limitaciones de arquitectura, etc., y hay bastantes herramientas que pueden leerlas y procesarlas para proporcionar garantías más allá de lo que obtiene de los compiladores. Incluso podría escribir cosas que verifiquen las condiciones previas / posteriores.

Siento que algo como esto es especialmente necesario en Python debido a su escritura más débil, pero realmente no hubo construcciones que lo hicieran sencillo y parte de la sintaxis oficial.

Hay otros usos para las anotaciones más allá de la seguridad. Puedo ver cómo puedo aplicar mis herramientas basadas en Java a Python. Por ejemplo, tengo una herramienta que le permite asignar advertencias especiales a los métodos, y le da indicaciones cuando las llama para que lea su documentación (por ejemplo, imagine que tiene un método que no debe invocarse con un valor negativo, pero es no intuitivo por el nombre). Con anotaciones, podría escribir técnicamente algo así para Python. Del mismo modo, se puede escribir una herramienta que organice métodos en una clase grande basada en etiquetas si hay una sintaxis oficial.

Las anotaciones de funciones son lo que haces de ellas.

Se pueden usar para documentación:

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

Se pueden usar para la verificación previa a la condición:

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

Consulte también http://www.python.org/dev/peps/pep-0362/ para ver una forma de implementar la verificación de tipos.

Esta es una respuesta tardía, pero AFAICT, el mejor uso actual de las anotaciones de funciones es PEP-0484 y MyPy .

Mypy es un verificador de tipo estático opcional para Python. Puede agregar sugerencias de tipo a sus programas de Python utilizando el próximo estándar para anotaciones de tipo introducido en Python 3.5 beta 1 (PEP 484), y use mypy para verificarlas de forma estática.

Usado así:

from typing import Iterator

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

Solo para agregar un ejemplo específico de un buen uso de mi respuesta aquí , junto con los decoradores, se puede hacer un mecanismo simple para métodos múltiples.

# 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

y un ejemplo de uso:

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)))

Esto se puede hacer agregando los tipos al decorador como lo muestra la publicación original de Guido , pero anotar los parámetros en sí es mejor ya que evita la posibilidad de una coincidencia incorrecta de parámetros y tipos.

Nota : en Python puede acceder a las anotaciones en function.__annotations__lugar de eliminar function.func_annotationsel func_*estilo en Python 3.

Uri ya ha dado una respuesta adecuada, así que aquí hay una respuesta menos seria: para que pueda acortar sus cadenas de documentos.

La primera vez que vi anotaciones, pensé "¡genial! ¡Finalmente puedo optar por algún tipo de verificación!" Por supuesto, no me había dado cuenta de que las anotaciones no se aplican realmente.

Así que decidí escribir un decorador de funciones simple para hacerlas cumplir :

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'>

Lo agregué a la biblioteca Asegurar .

Ha pasado mucho tiempo desde que se hizo esto, pero el fragmento de ejemplo dado en la pregunta es (como también se indica allí) de PEP 3107 y al final de este ejemplo de PEP También se dan casos de uso que podrían responder a la pregunta desde el punto de PEP vista;)

Lo siguiente se cita de PEP3107

Casos de uso

En el curso de la discusión de las anotaciones, se han planteado varios casos de uso. Algunos de estos se presentan aquí, agrupados por el tipo de información que transmiten. También se incluyen ejemplos de productos y paquetes existentes que podrían hacer uso de anotaciones.

• Proporcionar información de mecanografía
  • Verificación de tipo ([3], [4])
  • Deje que los IDE muestren qué tipos espera y devuelve una función ([17])
  • Sobrecarga de funciones / funciones genéricas ([22])
  • Puentes de lenguas extranjeras ([18], [19])
  • Adaptación ([21], [20])
  • Funciones lógicas predicadas
  • Asignación de consulta de base de datos
  • Clasificación de parámetros RPC ([23])
• Otra información
  • Documentación para parámetros y valores de retorno ([24])

Consulte la PEP para obtener más información sobre puntos específicos (así como sus referencias)

Python 3.X (solo) también generaliza la definición de funciones para permitir que los argumentos y los valores de retorno se anoten con valores de objeto para su uso en extensiones .

Sus datos META para explicar, para ser más explícitos sobre los valores de la función.

Las anotaciones se codifican :valuedespués del nombre del argumento y antes de un valor predeterminado, y ->valuedespués de la lista de argumentos.

Se recopilan en un __annotations__atributo de la función, pero Python no los trata como algo especial:

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

Fuente: Python Pocket Reference, quinta edición

EJEMPLO:

El typeannotationsmódulo proporciona un conjunto de herramientas para la verificación de tipos y la inferencia de tipos de código Python. También proporciona un conjunto de tipos útiles para anotar funciones y objetos.

Estas herramientas están diseñadas principalmente para ser utilizadas por analizadores estáticos como linters, bibliotecas de finalización de código e IDE. Además, se proporcionan decoradores para realizar comprobaciones de tiempo de ejecución. La comprobación de tipos en tiempo de ejecución no siempre es una buena idea en Python, pero en algunos casos puede ser muy útil.

https://github.com/ceronman/typeannotations

Cómo escribir ayuda a escribir un mejor código

Escribir puede ayudarlo a hacer análisis de código estático para detectar errores de tipo antes de enviar su código a producción y evitar algunos errores obvios. Existen herramientas como mypy, que puede agregar a su caja de herramientas como parte de su ciclo de vida del software. mypy puede verificar los tipos correctos ejecutando su base de código parcial o totalmente. mypy también lo ayuda a detectar errores como verificar el tipo Ninguno cuando el valor es devuelto por una función. Escribir ayuda a que su código sea más limpio. En lugar de documentar su código usando comentarios, donde especifica tipos en una cadena de documentos, puede usar tipos sin ningún costo de rendimiento.

Clean Python: Codificación elegante en Python ISBN: ISBN-13 (pbk): 978-1-4842-4877-5

PEP 526 - Sintaxis para anotaciones variables

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

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

A pesar de todos los usos descritos aquí, el uso obligatorio y, muy probablemente, el uso obligatorio de las anotaciones será para sugerencias de tipo .

Actualmente, esto no se aplica de ninguna manera, pero, a juzgar por PEP 484, las futuras versiones de Python solo permitirán tipos como el valor de las anotaciones.

Citando ¿Qué pasa con los usos existentes de las anotaciones? :

Esperamos que las sugerencias de tipo se conviertan en el único uso para las anotaciones, pero esto requerirá una discusión adicional y un período de desaprobación después del lanzamiento inicial del módulo de escritura con Python 3.5. El PEP actual tendrá un estado provisional (ver PEP 411) hasta que se libere Python 3.6. El esquema concebible más rápido introduciría la desaprobación silenciosa de las anotaciones sin sugerencia de tipo en 3.6, la desaprobación completa en 3.7 y declararía las sugerencias de tipo como el único uso permitido de anotaciones en Python 3.8.

Aunque todavía no he visto ninguna depreciación silenciosa en 3.6, esto podría muy bien pasar a 3.7.

Por lo tanto, a pesar de que puede haber algunos otros buenos casos de uso, es mejor mantenerlos únicamente para sugerencias de tipo si no desea cambiar todo en un futuro donde esta restricción esté vigente.

Como una respuesta un poco retrasada, varios de mis paquetes (marrow.script, WebCore, etc.) usan anotaciones donde están disponibles para declarar la conversión de texto (es decir, transformar los valores entrantes desde la web, detectar qué argumentos son modificadores booleanos, etc.) como para realizar un marcado adicional de argumentos.

Marrow Script crea una interfaz de línea de comandos completa para funciones y clases arbitrarias y permite definir documentación, conversión y valores predeterminados derivados de la devolución de llamada mediante anotaciones, con un decorador para admitir tiempos de ejecución más antiguos. Todas mis bibliotecas que usan anotaciones admiten los formularios:

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

El soporte "desnudo" para las cadenas de documentos o las funciones de conversión de texto permite una mezcla más fácil con otras bibliotecas que reconocen las anotaciones. (Es decir, tengo un controlador web que usa la conversión de texto que también está expuesto como un script de línea de comandos).

Editado para agregar: también he comenzado a utilizar el paquete TypeGuard utilizando aserciones de tiempo de desarrollo para la validación. Beneficio: cuando se ejecuta con "optimizaciones" habilitadas ( -O/ PYTHONOPTIMIZEenv var), se omiten las comprobaciones, que pueden ser costosas (por ejemplo, recursivas), con la idea de que ha probado adecuadamente su aplicación en desarrollo, por lo que las comprobaciones deberían ser innecesarias en la producción.

Las anotaciones se pueden usar para modularizar fácilmente el código. Por ejemplo, un módulo para un programa que estoy manteniendo podría definir un método como:

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

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

y podríamos pedirle al usuario algo llamado "param1" que es "Necesario para contar" y debería ser un "int". Al final, incluso podemos convertir la cadena dada por el usuario al tipo deseado para obtener la experiencia más libre de problemas.

Vea nuestro objeto de metadatos de función para una clase de código abierto que ayuda con esto y puede recuperar automáticamente los valores necesarios y convertirlos a cualquier tipo deseado (porque la anotación es un método de conversión). Incluso los IDE muestran los autocompletos correctamente y suponen que los tipos están de acuerdo con las anotaciones, un ajuste perfecto.

Si observa la lista de beneficios de Cython, una de las principales es la capacidad de decirle al compilador qué tipo de objeto es Python.

Puedo imaginar un futuro en el que Cython (o herramientas similares que compilan parte de su código Python) utilizarán la sintaxis de anotación para hacer su magia.