Python PEP-8 Rückgabewert Formatierung

Question

Ich bin mir nicht sicher, ich habe eine spezifische Antwort zu diesem Thema gesehen, aber ich habe eine Frage zu den Stil Konventionen auf Rückgabewerte für meine Python Docstrings.

Betrachten Sie eine Funktion wie:

def foo(ex): 
    output = 2*ex 
    return output 

In PyCharm, wenn ich eine docstring für diese Funktion gemacht, würde es wie folgt aussehen:

def foo(ex): 
    """ 
    Sample text.... 
    :param ex: description... 
    :return: description of return value 
    """ 
    output = 2*ex 
    return output 

Meine Frage, ob oder nicht sollte ich Name mein Rückgabewert im Docstring?

dh

: Rückkehr: Beschreibung Rückgabewert

: Rückkehr: Ausgang: Beschreibung der Rückgabewert

Gibt es eine Codierungsstandard für dieses oder ist es meist auf die persönlichen Vorlieben links ?

Answer 1

Docstring Konventionen definiert sind tatsächlich in PEP-257 (und PEP-8 lediglich verweist es), sondern nur die allgemeine Formatierung abgedeckt ist, nicht Inhalt.

• param, parameter, arg, argument, key, keyword: Beschreibung

  Der Gehalt an Docstrings wird in der Regel durch die Python-Dokumentation GeneratorSphinx und in Sphinx nach info fields existieren genannt interpretiert eines Parameters.

• type: Typ eines Parameters. Erstellt einen Link, wenn möglich.
• raises, raise, except, exception: Das (und wann) eine bestimmte Ausnahme ausgelöst wird.
• var, ivar, cvar: Beschreibung einer Variablen.
• vartype: Typ einer Variablen. Erstellt einen Link, wenn möglich.
• returns, return: Beschreibung des Rückgabewerts.
• rtype: Rückgabetyp. Erstellt einen Link, wenn möglich.

Beachten Sie die rtype für die Rückgabetyp.

So können Sie den Rückgabetyp mit rtype angeben, aber der tatsächliche (lokale) Name der Objektrückgabe ist irrelevant.

Answer 2

Wie schon Randomir erwähnt, geben die Python PEPs nicht vor, wie der Inhalt von Docstrings strukturiert sein soll. Große Coding-Projekte haben jedoch normalerweise eigene Richtlinien für Docstring-Inhalte, und Sie könnten eine davon anpassen.

Persönlich mag ich das Numpy Docstring-Format (siehe here und here). Der lokale Name eines Rückgabewerts ist nicht in den Nöpchen-artigen Docstrings enthalten. Das docstring für Ihre Funktion würde wie folgt aussehen:

def foo(ex): 
    """One-line function description. 

    Parameters 
    ---------- 
    ex : float 
     Description of parameter. 

    Returns 
    ------- 
    float 
     Description of return value. 

    """ 
    output = 2*ex 
    return output 

Numpy Stil Docstrings sowie durch Sphinx Dokumentations-Generator unterstützt werden.