Comment spécifier les types de données d'entrée et de sortie dans les commentaires python?

Question

J'ai vu plusieurs standards pour écrire des commentaires sur le type de données attendues et retournées par Python. Y a-t-il un consensus sur lequel est la meilleure pratique?

Est-ce que la nouvelle fonctionnalité http://www.python.org/dev/peps/pep-3107/ est quelque chose que je devrais commencer à utiliser pour cela?

Answer 1

Les annotations de fonctions ne sont pas destinées à un usage spécifique, elles peuvent être utilisées pour n'importe quoi.

Des outils peuvent être écrits pour extraire des informations des annotations et faire tout ce que vous voulez, y compris vérifier les types ou générer de la documentation. Mais python lui-même ne fait rien avec l'information. Vous pouvez utiliser un objectif complètement différent, c'est-à-dire fournir une fonction qui sera appelée sur le paramètre ou déclarer une chaîne de valeurs de retour possibles.

Les annotations peuvent être un objet:

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

et vous pouvez récupérer les objets à l'aide:

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

Utilisez des suggestions de cas fournies par le PEP:

• Fournir la saisie des informations
  • Typage
  • Let IDEs montrent quels types une fonction attend et retourne
  • la surcharge des fonctions/fonctions génériques
  • ponts en langue étrangère
  • Adaptation
  • fonctions logiques de prédicats
  • Base de données cartographie de requête
  • Paramètre RPC marshaling
• Autres informations
  • Documentation des paramètres et de retour des valeurs

Depuis la syntaxe d'annotation de fonction est trop nouvelle, il est vraiment pas utilisé pour tous les outils de production.

Je suggère d'utiliser d'autres méthodes pour documenter cela. J'utilise epydoc pour générer mes documents, et il peut lire les informations de frappe paramètre de docstrings:

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 

Cet exemple est de epydoc's website. Il peut générer de la documentation dans divers formats et générer de bons graphiques à partir de vos classes et de vos profils d'appel.

Answer 2

Si vous utilisez epydoc pour produire la documentation de l'API, vous avez trois choix.

• Epytext.

• ReStructuredText, RST.

• Notation JavaDoc, qui ressemble un peu à epytext.

Je recommande la TVD, car il fonctionne bien avec sphinx pour générer la suite d'ensemble de la documentation qui comprend des références de l'API. Le balisage RST est défini here. Les différents champs epydoc que vous pouvez spécifier sont définis here.

Exemple.

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 officiel typing

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

Cette mise à jour des types d'une partie réelle de la langue.

Exemple:

#!/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 

Ce code fonctionne normalement: Python 3.5 n'applique pas la saisie par défaut.

Mais il peut cependant être utilisé par bourres statiques pour diagnoze problèmes, par exemple:

sudo pip3 install mypy 
mypy a.py 

donne:

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" 

existants analyseurs statiques comme de PyCharm peuvent déjà analyser les types de documentation Sphinx, mais cette langue mise à jour donne un chemin canonique officiel qui prévaudra probablement.