¿Cómo especifico los tipos de datos de entrada y salida en los comentarios de Python?

Question

He visto varios estándares para escribir comentarios sobre el tipo de datos que una función espera y devuelve en Python. ¿Existe un consenso sobre cuál es la mejor práctica?

¿Es la nueva funcionalidad en http://www.python.org/dev/peps/pep-3107/ algo que debería empezar a usar para esto?

Answer 1

Las anotaciones de funciones no son para un uso específico, se pueden usar para cualquier cosa.

Las herramientas se pueden escribir para extraer información de las anotaciones y hacer todo lo que quiera, incluso consultar tipos o generar documentación. Pero Python en sí no hace nada con la información. Podría utilizarlo para un propósito completamente diferente, es decir, para proporcionar una función que se invocará en el parámetro o para declarar una cadena de posibles valores de retorno.

Las anotaciones pueden ser cualquier objeto:

def somefunc(param1: "string annotation", 
      param2: 151631, 
      param3: any_object): -> "some information here": 

y se puede recuperar los objetos usando:

print (somefunc.func_annotations) 
{'param1': "string annotation", 
'param2': 151631, 
'param3': <object any_object>, 
'return': "some information here"} 

sugerencias de casos de uso proporcionadas por el PEP:

• Proporcionar escribir la información
  • Tipo comprobar
  • Vamos IDE muestran qué tipo de una función espera y devuelve
  • sobrecarga de funciones/funciones genéricas
  • puentes en lengua extranjera
  • adaptación
  funciones lógicas
  • predicado
  mapeo consulta
  • base de datos
  • Asignación de referencias de parámetros RPC
• Otra información
  • Documentación para los parámetros y valores de retorno

Desde sintaxis de la función de anotación es demasiado nuevo, en realidad no es utilizada para ningún herramientas de producción.

Sugiero usar otros métodos para documentar eso. Yo uso epydoc para generar mi documentación, y se puede leer la información a escribir parámetros de cadenas de documentación:

def x_intercept(m, b): 
    """ 
    Return the x intercept of the line M{y=m*x+b}. The X{x intercept} 
    of a line is the point at which it crosses the x axis (M{y=0}). 

    This function can be used in conjuction with L{z_transform} to 
    find an arbitrary function's zeros. 

    @type m: number 
    @param m: The slope of the line. 
    @type b: number 
    @param b: The y intercept of the line. The X{y intercept} of a 
       line is the point at which it crosses the y axis (M{x=0}). 
    @rtype: number 
    @return: the x intercept of the line M{y=m*x+b}. 
    """ 
    return -b/m 

Este ejemplo es de epydoc's website. Puede generar documentación en una variedad de formatos y puede generar buenos gráficos de sus clases y perfiles de llamadas.

Answer 2

Si usa epydoc para producir documentación de API, tiene tres opciones.

• Epytext.

• ReStructuredText, RST.

• notación JavaDoc, que se parece un poco a epytext.

recomiendo RST, ya que funciona bien con sphinx para generar suite de la documentación general que incluye referencias de la API. El marcado RST se define here. Los diversos campos epydoc que puede especificar están definidos here.

Ejemplo.

def someFunction(arg1, arg2): 
    """Returns the average of *two* (and only two) arguments. 

    :param arg1: a numeric value 
    :type arg1: **any** numeric type 

    :param arg2: another numeric value 
    :type arg2: **any** numeric type 

    :return: mid-point (or arithmetic mean) between two values 
    :rtype: numeric type compatible with the args. 
    """ 
    return (arg1+arg2)/2 

Answer 3

Python 3.5 oficial typing

https://docs.python.org/3/library/typing.html

Esta actualización hace que los tipos de una parte real de la lengua.

Ejemplo:

#!/usr/bin/env python3 

from typing import List 

def f(x: int, ys: List[float]) -> str: 
    return "abc" 

# Good. 
f(1, [2.0, 3.0]) 

# Bad. 
f("abc", {}) # line 12 

x = 1 
x = "a" # line 15 

y = [] # type: List[int] 
y.append("a") # line 18 

Este código se ejecuta normalmente: Python 3.5 no fuerza la tipificación de forma predeterminada.

Pero sin embargo, puede ser utilizado por borras de estáticos a diagnoze problemas, por ejemplo:

sudo pip3 install mypy 
mypy a.py 

da:

a.py:12: error: Argument 1 to "f" has incompatible type "str"; expected "int" 
a.py:12: error: Argument 2 to "f" has incompatible type Dict[<nothing>, <nothing>]; expected List[float] 
a.py:15: error: Incompatible types in assignment (expression has type "str", variable has type "int") 
a.py:18: error: Argument 1 to "append" of "list" has incompatible type "str"; expected "int" 

existentes analizadores estáticos como PyCharm de que ya pueden analizar los tipos de documentación Sphinx, pero este lenguaje la actualización proporciona una forma canónica oficial que probablemente prevalecerá.