sphinx.ext.doctest – Testen von Code-Schnipseln in der Dokumentation

Es ist oft hilfreich, Code-Schnipsel in Ihrer Dokumentation aufzunehmen und die Ergebnisse ihrer Ausführung zu demonstrieren. Aber es ist wichtig sicherzustellen, dass die Dokumentation mit dem Code aktuell bleibt.

Diese Erweiterung ermöglicht es Ihnen, solche Code-Schnipsel in der Dokumentation auf natürliche Weise zu testen. Wenn Sie die Codeblöcke wie hier gezeigt markieren, sammelt der doctest Builder sie und führt sie als doctest-Tests aus.

Innerhalb jedes Dokuments können Sie jedem Schnipsel eine Gruppe zuweisen. Jede Gruppe besteht aus

  • null oder mehr Setup-Code-Blöcken (z. B. Importieren des zu testenden Moduls)

  • ein oder mehrere Test-Blöcke

Beim Erstellen der Dokumentation mit dem doctest Builder werden die Gruppen für jedes Dokument gesammelt und nacheinander ausgeführt, wobei zuerst die Setup-Code-Blöcke und dann die Test-Blöcke in der Reihenfolge ihrer Erscheinung in der Datei ausgeführt werden.

Es gibt zwei Arten von Testblöcken

  • doctest-Stil-Blöcke ahmen interaktive Sitzungen nach, indem sie Python-Code (einschließlich der Interpreter-Eingabeaufforderung) und die Ausgabe abwechseln.

  • Code-Ausgabe-Stil-Blöcke bestehen aus einem gewöhnlichen Stück Python-Code und optional einem Stück Ausgabe für diesen Code.

Direktiven

Das Argument group wird wie folgt interpretiert: Wenn es leer ist, wird der Block der Gruppe namens default zugewiesen. Wenn es * ist, wird der Block allen Gruppen (einschließlich der Gruppe default) zugewiesen. Andernfalls muss es eine durch Kommas getrennte Liste von Gruppennamen sein.

.. testsetup:: [group]

Ein Setup-Code-Block. Dieser Code wird in der Ausgabe für andere Builder nicht angezeigt, aber vor den Doctests der Gruppe(n), zu denen er gehört, ausgeführt.

Optionen

:skipif: bedingung (text)

Überspringe die Direktive, wenn der Python-Ausdruck bedingung True ist. Siehe Tests bedingt überspringen.

.. testcleanup:: [group]

Ein Cleanup-Code-Block. Dieser Code wird in der Ausgabe für andere Builder nicht angezeigt, aber nach den Doctests der Gruppe(n), zu denen er gehört, ausgeführt.

Hinzugefügt in Version 1.1.

Optionen

:skipif: bedingung (text)

Überspringe die Direktive, wenn der Python-Ausdruck bedingung True ist. Siehe Tests bedingt überspringen.

.. doctest:: [group]

Ein Code-Block im Doctest-Stil. Sie können Standard-Flags von doctest verwenden, um zu steuern, wie die tatsächliche Ausgabe mit der von Ihnen angegebenen Ausgabe verglichen wird. Der Standard-Satz von Flags wird durch die Konfigurationsvariable doctest_default_flags bestimmt.

Optionen

:hide:

Verberge den Doctest-Block in anderen Buildern. Standardmäßig wird er als hervorgehobener Doctest-Block angezeigt.

:options: doctest flags (durch Kommas getrennte Liste)

Eine durch Kommas getrennte Liste von Doctest-Flags, die auf jedes Beispiel in den Tests angewendet werden. (Sie können immer noch explizite Flags pro Beispiel mit Doctest-Kommentaren angeben, aber diese werden auch in anderen Buildern angezeigt.)

Alternativ können Sie Inline-Doctest-Optionen angeben, wie in doctest

>>> datetime.date.now()
datetime.date(2008, 1, 1)

Sie werden bei der Ausführung des Tests berücksichtigt, aber standardmäßig aus der Präsentationsausgabe entfernt. Sie können das Entfernen verhindern, indem Sie die Option doctest:no-trim-doctest-flags verwenden.

:pyversion: (text)

Geben Sie die erforderliche Python-Version für das zu testende Beispiel an. Zum Beispiel wird in folgendem Fall das Beispiel nur für Python-Versionen größer als 3.12 getestet

.. doctest::
   :pyversion: > 3.12

Die folgenden Operanden werden unterstützt

  • ~=: Kompatible Release-Klausel

  • ==: Versionsabgleich-Klausel

  • !=: Versions-Ausschlussklausel

  • <=, >=: Inklusive geordneter Vergleichsklausel

  • <, >: Exklusive geordnete Vergleichsklausel

  • ===: Beliebige Gleichheitsklausel.

pyversion Option folgt PEP-440: Versionsspezifizierer.

Hinzugefügt in Version 1.6.

Geändert in Version 1.7: Unterstützte PEP-440 Operanden und Notationen

:trim-doctest-flags:
:no-trim-doctest-flags:

Ob Doctest-Flags (Kommentare, die wie # doctest: FLAG, ... aussehen) am Ende von Zeilen und <BLANKLINE> Marker einzeln entfernt werden sollen. Standard ist trim-doctest-flags.

Beachten Sie, dass Sie, wie bei standardmäßigen Doctests, <BLANKLINE> verwenden müssen, um eine Leerzeile in der erwarteten Ausgabe zu signalisieren. Die <BLANKLINE> wird beim Erstellen der Präsentationsausgabe (HTML, LaTeX etc.) entfernt.

:skipif: bedingung (text)

Überspringe die Direktive, wenn der Python-Ausdruck bedingung True ist. Siehe Tests bedingt überspringen.

.. testcode:: [group]

Ein Code-Block für einen Test im Code-Ausgabe-Stil.

Optionen

:hide:

Verberge den Code-Block in anderen Buildern. Standardmäßig wird er als hervorgehobener Code-Block angezeigt.

:trim-doctest-flags:
:no-trim-doctest-flags:

Ob Doctest-Flags (Kommentare, die wie # doctest: FLAG, ... aussehen) am Ende von Zeilen und <BLANKLINE> Marker einzeln entfernt werden sollen. Standard ist trim-doctest-flags.

:skipif: bedingung (text)

Überspringe die Direktive, wenn der Python-Ausdruck bedingung True ist. Siehe Tests bedingt überspringen.

Hinweis

Code in einem testcode Block wird immer auf einmal ausgeführt, egal wie viele Anweisungen er enthält. Daher wird keine Ausgabe für leere Ausdrücke generiert – verwenden Sie print. Beispiel

.. testcode::

   1+1         # this will give no output!
   print(2+2)  # this will give output

.. testoutput::

   4

Bitte beachten Sie auch, dass, da das doctest-Modul das Mischen von regulärer Ausgabe und Fehlermeldungen im selben Schnipsel nicht unterstützt, dies auch für testcode/testoutput gilt.

.. testoutput:: [group]

Die entsprechende Ausgabe oder die Fehlermeldung für den letzten testcode Block.

:hide:

Verberge den Doctest-Block in anderen Buildern. Standardmäßig wird er als hervorgehobener Doctest-Block angezeigt.

:options: doctest flags (durch Kommas getrennte Liste)

Eine durch Kommas getrennte Liste von Doctest-Flags.

:trim-doctest-flags:
:no-trim-doctest-flags:

Ob Doctest-Flags (Kommentare, die wie # doctest: FLAG, ... aussehen) am Ende von Zeilen und <BLANKLINE> Marker einzeln entfernt werden sollen. Standard ist trim-doctest-flags.

:skipif: bedingung (text)

Überspringe die Direktive, wenn der Python-Ausdruck bedingung True ist. Siehe Tests bedingt überspringen.

Beispiel

.. testcode::

   print('Output     text.')

.. testoutput::
   :hide:
   :options: -ELLIPSIS, +NORMALIZE_WHITESPACE

   Output text.

Das Folgende ist ein Beispiel für die Verwendung der Direktiven. Der Test über doctest und der Test über testcode und testoutput sind äquivalent.

The parrot module
=================

.. testsetup:: *

   import parrot

The parrot module is a module about parrots.

Doctest example:

.. doctest::

   >>> parrot.voom(3000)
   This parrot wouldn't voom if you put 3000 volts through it!

Test-Output example:

.. testcode::

   parrot.voom(3000)

This would output:

.. testoutput::

   This parrot wouldn't voom if you put 3000 volts through it!

Tests bedingt überspringen

skipif, eine String-Option, kann verwendet werden, um Direktiven bedingt zu überspringen. Dies kann nützlich sein, z. B. wenn ein anderer Satz von Tests ausgeführt werden soll, abhängig von der Umgebung (Hardware, Netzwerk/VPN, optionale Abhängigkeiten oder verschiedene Versionen von Abhängigkeiten). Die Option skipif wird von allen Doctest-Direktiven unterstützt. Unten sind typische Anwendungsfälle für skipif aufgeführt, wenn sie für verschiedene Direktiven verwendet wird

  • testsetup und testcleanup

    • Test-Setup und/oder -Cleanup bedingt überspringen

    • Setup/Cleanup-Code pro Umgebung anpassen

  • doctest

    • sowohl einen Test als auch seine Ausgabeüberprüfung bedingt überspringen

  • testcode

    • einen Test bedingt überspringen

    • Testcode pro Umgebung anpassen

  • testoutput

    • Ausgabeüberprüfung für einen übersprungenen Test bedingt überspringen

    • unterschiedliche Ausgaben je nach Umgebung erwarten

Der Wert der Option skipif wird als Python-Ausdruck ausgewertet. Wenn das Ergebnis ein wahrer Wert ist, wird die Direktive aus dem Testlauf weggelassen, so als wäre sie gar nicht in der Datei vorhanden.

Anstatt einen Ausdruck zu wiederholen, kann die Konfigurationsoption doctest_global_setup verwendet werden, um ihn einer Variablen zuzuweisen, die dann stattdessen verwendet werden kann.

Hier ist ein Beispiel, das einige Tests überspringt, wenn Pandas nicht installiert ist

conf.py
extensions = ['sphinx.ext.doctest']
doctest_global_setup = '''
try:
    import pandas as pd
except ImportError:
    pd = None
'''
contents.rst
.. testsetup::
   :skipif: pd is None

   data = pd.Series([42])

.. doctest::
   :skipif: pd is None

   >>> data.iloc[0]
   42

.. testcode::
   :skipif: pd is None

   print(data.iloc[-1])

.. testoutput::
   :skipif: pd is None

   42

Konfiguration

Die Doctest-Erweiterung verwendet die folgenden Konfigurationswerte

doctest_default_flags
Typ:
int
Standard:
ELLIPSIS | IGNORE_EXCEPTION_DETAIL | DONT_ACCEPT_TRUE_FOR_1

Standardmäßig sind diese Optionen aktiviert

  • ELLIPSIS, wodurch Sie Ellipsen in der erwarteten Ausgabe platzieren können, die mit allem in der tatsächlichen Ausgabe übereinstimmen;

  • IGNORE_EXCEPTION_DETAIL, wodurch alles nach dem linken Doppelpunkt und jegliche Modulinformationen im Ausnahmetyp ignoriert werden;

  • DONT_ACCEPT_TRUE_FOR_1, wodurch "True" in der Ausgabe abgelehnt wird, wo "1" angegeben ist – das Standardverhalten, diese Ersetzung zu akzeptieren, ist ein Relikt aus Zeiten vor Python 2.2.

Hinzugefügt in Version 1.5.

doctest_show_successes
Typ:
bool
Standard:
True

Steuert, ob Erfolge gemeldet werden.

Für ein Projekt mit vielen Doctests kann es sinnvoll sein, dies auf False zu setzen, um nur Fehler hervorzuheben.

Hinzugefügt in Version 7.2.

doctest_path
Typ:
Sequenz[str]
Standard:
()

Eine Liste von Verzeichnissen, die zu sys.path hinzugefügt werden, wenn der Doctest-Builder verwendet wird. (Stellen Sie sicher, dass er absolute Pfade enthält.)

doctest_global_setup
Typ:
str
Standard:
''

Python-Code, der so behandelt wird, als ob er in einer testsetup Direktive für jede zu testende Datei und für jede Gruppe platziert worden wäre. Sie können dies verwenden, um z. B. Module zu importieren, die Sie in Ihren Doctests immer benötigen.

Hinzugefügt in Version 0.6.

doctest_global_cleanup
Typ:
str
Standard:
''

Python-Code, der so behandelt wird, als ob er in einer testcleanup Direktive für jede zu testende Datei und für jede Gruppe platziert worden wäre. Sie können dies verwenden, um z. B. alle temporären Dateien zu entfernen, die die Tests hinterlassen.

Hinzugefügt in Version 1.1.

doctest_test_doctest_blocks
Typ:
str
Standard:
'default'

Wenn dies ein nicht leerer String ist, werden auch Standard-reStructuredText-Doctest-Blöcke getestet. Sie werden der angegebenen Gruppennummer zugewiesen.

reStructuredText-Doctest-Blöcke sind einfach Doctests, die in einem eigenen Absatz platziert werden, wie hier

Some documentation text.

>>> print(1)
1

Some more documentation text.

(Beachten Sie, dass kein spezielles :: verwendet wird, um einen Doctest-Block einzuleiten; docutils erkennt sie anhand des führenden >>>. Außerdem wird keine zusätzliche Einrückung verwendet, obwohl sie nicht schadet.)

Wenn dieser Wert auf seinem Standardwert belassen wird, wird der obige Schnipsel vom Doctest-Builder genau wie der folgende interpretiert

Some documentation text.

.. doctest::

   >>> print(1)
   1

Some more documentation text.

Diese Funktion erleichtert Ihnen das Testen von Doctests in Docstrings, die mit der autodoc Erweiterung enthalten sind, ohne sie mit einer speziellen Direktive zu markieren.

Beachten Sie jedoch, dass Sie keine Leerzeilen in reStructuredText-Doctest-Blöcken haben können. Sie werden als Ende eines Blocks und Beginn eines neuen interpretiert. Außerdem funktioniert das Entfernen von <BLANKLINE> und # doctest: Optionen nur in doctest Blöcken, obwohl Sie trim_doctest_flags setzen können, um dies in allen Codeblöcken mit Python-Konsoleninhalt zu erreichen.

doctest_fail_fast
Typ:
bool
Standard:
False

Beenden, wenn der erste Fehler auftritt.

Hinzugefügt in Version 9.0.