Wie gebe ich Eingabe- und Ausgabedatentypen in Python-Kommentaren an?

Question

Ich habe mehrere Standards zum Schreiben von Kommentaren über die Art von Daten gesehen, die eine Funktion in Python erwartet und zurückgibt. Gibt es einen Konsens darüber, was man als Best-Practice bezeichnet?

Ist die neue Funktionalität in http://www.python.org/dev/peps/pep-3107/ etwas, was ich anfangen sollte zu verwenden?

Answer 1

Funktion Anmerkungen sind nicht für eine bestimmte Verwendung, sie können für alles verwendet werden.

Werkzeuge können geschrieben werden, um Informationen aus den Annotationen zu extrahieren und alles zu tun, was Sie wollen, einschließlich Prüftypen oder Generierung von Dokumentation. Aber Python selbst macht nichts mit den Informationen. Sie könnten zu einem ganz anderen Zweck verwenden, d. H. Um eine Funktion bereitzustellen, die für den Parameter aufgerufen wird oder um eine Folge möglicher Rückgabewerte zu deklarieren.

Annotations kann jedes Objekt sein:

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

und Sie können die Objekte abrufen mit:

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

Use Case Vorschläge des PEP vorgesehen:

• eingeben Bereitstellung von Informationen
  • Typ Überprüfung
  • IDEs Lassen Sie zeigen, welche Arten eine Funktion erwartet und gibt
  • Funktion Überlastung/generic Funktionen
  • Fremdsprachiger Brücken
  • Anpassung
  • Prädikatslogikfunktionen
  • Datenbankabfrage-Mapping
  • RPC Parameter Marshalling
• Weitere Informationen
  • Dokumentation für Parameter und Rückgabewerte

Da Funktion Anmerkung Syntax zu neu ist, ist es wirklich nicht für Produktionswerkzeuge verwendet.

Ich empfehle andere Methoden, um dies zu dokumentieren. Ich benutze epydoc meine Dokumentation zu erzeugen, und es kann Parameter Typisierung Informationen aus Docstrings lesen:

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 

Dieses Beispiel stammt aus epydoc's website. Es kann Dokumentationen in verschiedenen Formaten generieren und aus Ihren Klassen und Anrufprofilen gute Grafiken erstellen.

Answer 2

Wenn Sie epydoc verwenden, um API-Dokumentation zu erstellen, haben Sie drei Möglichkeiten.

• Epytext.

• ReStructuredText, RST.

• JavaDoc-Notation, die ein wenig wie Epytext aussieht.

Ich empfehle RST, weil es gut mit sphinx zur Erzeugung Gesamtdokumentation Suite, die API arbeitet Referenzen enthält. RST-Markup ist definiert als here. Die verschiedenen epydoc-Felder, die Sie angeben können, sind definiert here.

Beispiel.

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

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

Dieses Update macht Typen ein tatsächliches Teil der Sprache.

Beispiel:

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

Dieser Code läuft normalerweise: Python 3.5 erzwingt keine Eingabe standardmäßig.

Aber es kann jedoch durch statischen Linters verwendet werden, um Probleme zu diagnoze, zB:

sudo pip3 install mypy 
mypy a.py 

gibt:

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" 

Bestehende statische Analysatoren wie PyCharm des bereits Sphinx Dokumentationsart analysieren, aber diese Sprache Update gibt einen offiziellen kanonischen Weg, der wahrscheinlich vorherrschen wird.