Sollte der Docstring nur die Ausnahmen enthalten, die explizit von einer Funktion ausgelöst werden?

Question

Sollte der Docstring nur die Ausnahmen enthalten, die explizit von einer Funktion ausgelöst werden?

8

Beim Schreiben von Doc-Strings in Python frage ich mich, ob der Docstring die Exceptions enthalten soll, die implizit ausgelöst werden oder ob er auch die Exceptions enthalten soll, die ich explizit aufrufe.

Betrachten Sie die Funktion

%Vor%

Also würde ich in einem Docstring unter dem Schlüsselwort "Raises" ZeroDivisionError setzen. Abhängig von der Eingabe würde ich aber auch einen TypeError erwarten. Würdest du das auch in den Docstring legen?

Aufgrund des EAFP-Prinzips (wenn ich es richtig verstehe) möchte ich hier nicht nach Typen suchen, richtig? Jeder Hinweis (auch auf das Codebeispiel) ist willkommen.

python python-3.x docstring raise

Quickbeam2k1 21.10.2015, 15:08

quelle

2 Antworten

Tags und Links python python-3.x docstring raise

Django: Verwenden von Annotate, Count und Distinct in einem Queryset Wie verwende ich Plupload mit Node.js und zeige die Prozentsätze des Uploads?

score 5 · Answer 1

Es hängt davon ab, für wen Sie den Docstring schreiben. Für die automatische Konvertierung in die API-Dokumentation mag ich Google-Stil-Docstrings , die folgendermaßen aussehen würden:

%Vor%

Hier habe ich alle Ausnahmen eingeschlossen, die die Funktion wahrscheinlich auslösen wird . Beachten Sie, dass Sie raise ZeroDivisionError nicht explizit angeben müssen - dies geschieht automatisch, wenn Sie versuchen, durch Null zu teilen.

Wenn Sie jedoch keine Dokumentation über den Docstring erstellen, würde ich wahrscheinlich nur die Beschreibungszeile für eine solche einfache Funktion einfügen:

%Vor%

Jeder, der es benutzt, wird wahrscheinlich wissen, dass Sie z.B. Zeichenfolgen.

Ich möchte hier nicht nach Typen suchen, richtig?

Ich würde nicht - wenn der Benutzer nach dem Lesen Ihrer Dokumentation beschließt, z.B. eine Zeichenfolge in die Funktion, die erwartet sollte TypeError erhalten, und es hat keinen Sinn, den Argumenttyp zu testen, um dann die selbe Exception selbst auszulösen, die der Code sowieso erhöht hätte (siehe auch die ZeroDivisionError !) Das heißt, außer zB float oder complex Zahlen sollten ungültige Eingabe sein, in diesem Fall müssen Sie sie manuell behandeln.

score 1 · Answer 2

Nein. Der Docstring sollte die erwartete Eingabe beschreiben. Wenn dies meine Funktion wäre, würde ich so etwas in den Docstring aufnehmen:

%Vor%

Daher wird angegeben, dass die Eingabe eine ganze Zahl sein soll. Die Angabe, dass die Funktion TypeError erhöhen kann, erschwert den Docstring nur zu sehr.