`warnings` — Warnungssteuerung¶

Quellcode: Lib/warnings.py

Warnmeldungen werden typischerweise in Situationen ausgegeben, in denen es nützlich ist, den Benutzer auf eine Bedingung in einem Programm hinzuweisen, wobei diese Bedingung (normalerweise) keinen Grund darstellt, eine Ausnahme auszulösen und das Programm zu beenden. Man möchte beispielsweise eine Warnung ausgeben, wenn ein Programm ein veraltetes Modul verwendet.

Python-Programmierer geben Warnungen aus, indem sie die in diesem Modul definierte Funktion warn() aufrufen. (C-Programmierer verwenden PyErr_WarnEx(); Einzelheiten finden Sie unter Exception Handling).

Warnmeldungen werden normalerweise nach sys.stderr geschrieben, aber ihre Behandlung kann flexibel geändert werden, vom Ignorieren aller Warnungen bis zum Umwandeln in Ausnahmen. Die Behandlung von Warnungen kann je nach Warnungskategorie, dem Text der Warnmeldung und dem Quellcodeort, an dem sie ausgegeben wird, variieren. Wiederholungen einer bestimmten Warnung für denselben Quellcodeort werden normalerweise unterdrückt.

Es gibt zwei Stufen bei der Warnungssteuerung: Erstens wird jedes Mal, wenn eine Warnung ausgegeben wird, bestimmt, ob eine Meldung ausgegeben werden soll oder nicht; zweitens, wenn eine Meldung ausgegeben werden soll, wird sie formatiert und mit einem vom Benutzer einstellbaren Hook ausgegeben.

Die Bestimmung, ob eine Warnmeldung ausgegeben werden soll, wird durch den Warnungsfilter gesteuert, der eine Sequenz von übereinstimmenden Regeln und Aktionen darstellt. Regeln können dem Filter durch Aufruf von filterwarnings() hinzugefügt und in seinen Standardzustand zurückgesetzt werden, indem resetwarnings() aufgerufen wird.

Die Ausgabe von Warnmeldungen erfolgt durch Aufruf von showwarning(), was überschrieben werden kann; die Standardimplementierung dieser Funktion formatiert die Meldung durch Aufruf von formatwarning(), welche ebenfalls für die Verwendung durch benutzerdefinierte Implementierungen zur Verfügung steht.

Siehe auch

logging.captureWarnings() ermöglicht es Ihnen, alle Warnungen mit der Standard-Protokollierungsinfrastruktur zu behandeln.

Warnungskategorien¶

Es gibt eine Reihe von eingebauten Ausnahmen, die Warnungskategorien darstellen. Diese Kategorisierung ist nützlich, um Gruppen von Warnungen herausfiltern zu können.

Obwohl dies technisch gesehen eingebaute Ausnahmen sind, werden sie hier dokumentiert, da sie konzeptionell zum Warnmechanismus gehören.

Benutzercode kann zusätzliche Warnungskategorien definieren, indem er eine der Standard-Warnungskategorien untererbt. Eine Warnungskategorie muss immer eine Unterklasse der Klasse Warning sein.

Die folgenden Warnungsklassenkategorien sind derzeit definiert

Klasse	Beschreibung
`Warnung`	Dies ist die Basisklasse aller Warnungsklassenkategorien. Sie ist eine Unterklasse von `Exception`.
`UserWarning`	Die Standardkategorie für `warn()`.
`DeprecationWarning`	Basis-Kategorie für Warnungen über veraltete Features, wenn diese Warnungen für andere Python-Entwickler bestimmt sind (standardmäßig ignoriert, es sei denn, sie werden durch Code in `__main__` ausgelöst).
`SyntaxWarning`	Basis-Kategorie für Warnungen über fragwürdige syntaktische Features (typischerweise ausgegeben beim Kompilieren von Python-Quellcode, und daher möglicherweise nicht durch Laufzeitfilter unterdrückt)
`RuntimeWarning`	Basis-Kategorie für Warnungen über fragwürdige Laufzeit-Features.
`FutureWarning`	Basis-Kategorie für Warnungen über veraltete Features, wenn diese Warnungen für Endbenutzer von Anwendungen bestimmt sind, die in Python geschrieben sind.
`PendingDeprecationWarning`	Basis-Kategorie für Warnungen über Features, die in Zukunft veraltet sein werden (standardmäßig ignoriert).
`ImportWarning`	Basis-Kategorie für Warnungen, die während des Imports eines Moduls ausgelöst werden (standardmäßig ignoriert).
`UnicodeWarning`	Basis-Kategorie für Warnungen im Zusammenhang mit Unicode.
`BytesWarning`	Basis-Kategorie für Warnungen im Zusammenhang mit `bytes` und `bytearray`.
`ResourceWarning`	Basis-Kategorie für Warnungen im Zusammenhang mit der Ressourcennutzung (standardmäßig ignoriert).

Geändert in Version 3.7: Zuvor wurde zwischen DeprecationWarning und FutureWarning basierend darauf unterschieden, ob ein Feature vollständig entfernt oder sein Verhalten geändert wurde. Sie unterscheiden sich nun basierend auf ihrer Zielgruppe und der Art und Weise, wie sie von den Standard-Warnfiltern behandelt werden.

Der Warnungsfilter¶

Der Warnungsfilter steuert, ob Warnungen ignoriert, angezeigt oder in Fehler umgewandelt werden (Auslösung einer Ausnahme).

Konzeptionell verwaltet der Warnungsfilter eine geordnete Liste von Filterangaben; jede spezifische Warnung wird nacheinander mit jeder Filterangabe in der Liste abgeglichen, bis eine Übereinstimmung gefunden wird; der Filter bestimmt die Behandlung der Übereinstimmung. Jeder Eintrag ist ein Tupel der Form (aktion, meldung, kategorie, modul, zeilennummer), wobei

aktion einer der folgenden Zeichenketten ist

Wert	Behandlung
`"default"`	druckt das erste Vorkommen übereinstimmender Warnungen für jeden Ort (Modul + Zeilennummer), an dem die Warnung ausgegeben wird
`"error"`	verwandelt übereinstimmende Warnungen in Ausnahmen
`"ignore"`	druckt niemals übereinstimmende Warnungen
`"always"`	druckt immer übereinstimmende Warnungen
`"all"`	Alias für "always"
`"module"`	druckt das erste Vorkommen übereinstimmender Warnungen für jedes Modul, in dem die Warnung ausgegeben wird (unabhängig von der Zeilennummer)
`"once"`	druckt nur das erste Vorkommen übereinstimmender Warnungen, unabhängig vom Ort

meldung ist eine Zeichenkette, die einen regulären Ausdruck enthält, mit dem der Anfang der Warnmeldung übereinstimmen muss, unabhängig von der Groß-/Kleinschreibung. In -W und PYTHONWARNINGS ist meldung eine literale Zeichenkette, die der Anfang der Warnmeldung enthalten muss (unabhängig von der Groß-/Kleinschreibung), wobei Whitespace am Anfang oder Ende von meldung ignoriert wird.
kategorie ist eine Klasse (eine Unterklasse von Warning), deren Unterklasse die Warnungskategorie sein muss, um übereinzustimmen.
modul ist eine Zeichenkette, die einen regulären Ausdruck enthält, mit dem der Anfang des vollqualifizierten Modulnamens übereinstimmen muss, Groß-/Kleinschreibung wird berücksichtigt. In -W und PYTHONWARNINGS ist modul eine literale Zeichenkette, der der vollqualifizierte Modulname entsprechen muss (Groß-/Kleinschreibung wird berücksichtigt), wobei Whitespace am Anfang oder Ende von modul ignoriert wird.
zeilennummer ist eine Ganzzahl, mit der die Zeilennummer, an der die Warnung aufgetreten ist, übereinstimmen muss, oder 0, um allen Zeilennummern zu entsprechen.

Da die Klasse Warning von der eingebauten Klasse Exception abgeleitet ist, lösen wir zur Umwandlung einer Warnung in einen Fehler einfach category(message) aus.

Wenn eine Warnung gemeldet wird und keiner registrierten Regel entspricht, wird die Aktion "default" angewendet (daher ihr Name).

Kriterien für die Unterdrückung wiederholter Warnungen¶

Die Filter, die wiederholte Warnungen unterdrücken, wenden die folgenden Kriterien an, um festzustellen, ob eine Warnung als Wiederholung gilt

"default": Eine Warnung gilt nur dann als Wiederholung, wenn (meldung, kategorie, modul, zeilennummer) alle gleich sind.
"module": Eine Warnung gilt als Wiederholung, wenn (meldung, kategorie, modul) gleich sind, wobei die Zeilennummer ignoriert wird.
"once": Eine Warnung gilt als Wiederholung, wenn (meldung, kategorie) gleich sind, wobei Modul und Zeilennummer ignoriert werden.

Beschreibung von Warnfiltern¶

Der Warnungsfilter wird durch -W Optionen, die an die Python-Interpreter-Kommandozeile übergeben werden, und die Umgebungsvariable PYTHONWARNINGS initialisiert. Der Interpreter speichert die Argumente für alle bereitgestellten Einträge ohne Interpretation in sys.warnoptions; das Modul warnings parst diese, wenn es zum ersten Mal importiert wird (ungültige Optionen werden ignoriert, nachdem eine Meldung an sys.stderr ausgegeben wurde).

Individuelle Warnungsfilter werden als eine Sequenz von durch Doppelpunkte getrennten Feldern angegeben

action:message:category:module:line

Die Bedeutung jedes dieser Felder ist wie in Der Warnungsfilter beschrieben. Bei der Angabe mehrerer Filter auf einer einzigen Zeile (wie für PYTHONWARNINGS) werden die einzelnen Filter durch Kommas getrennt, und die später aufgeführten Filter haben Vorrang vor den zuvor aufgeführten (da sie von links nach rechts angewendet werden und die zuletzt angewendeten Filter Vorrang vor den früheren haben).

Häufig verwendete Warnungsfilter gelten entweder für alle Warnungen, Warnungen einer bestimmten Kategorie oder Warnungen, die von bestimmten Modulen oder Paketen ausgelöst werden. Einige Beispiele

default                      # Show all warnings (even those ignored by default)
ignore                       # Ignore all warnings
error                        # Convert all warnings to errors
error::ResourceWarning       # Treat ResourceWarning messages as errors
default::DeprecationWarning  # Show DeprecationWarning messages
ignore,default:::mymodule    # Only report warnings triggered by "mymodule"
error:::mymodule             # Convert warnings to errors in "mymodule"

Standard-Warnfilter¶

Standardmäßig installiert Python mehrere Warnungsfilter, die durch die -W Kommandozeilenoption, die Umgebungsvariable PYTHONWARNINGS und Aufrufe von filterwarnings() überschrieben werden können.

In regulären Release-Builds enthält der Standard-Warnfilter die folgenden Einträge (in der Reihenfolge der Priorität)

default::DeprecationWarning:__main__
ignore::DeprecationWarning
ignore::PendingDeprecationWarning
ignore::ImportWarning
ignore::ResourceWarning

In einem Debug-Build ist die Liste der Standard-Warnfilter leer.

Geändert in Version 3.2: DeprecationWarning wird nun standardmäßig ignoriert, zusätzlich zu PendingDeprecationWarning.

Geändert in Version 3.7: DeprecationWarning wird standardmäßig wieder angezeigt, wenn sie direkt durch Code in __main__ ausgelöst wird.

Geändert in Version 3.7: BytesWarning erscheint nicht mehr in der Standardfilterliste und wird stattdessen über sys.warnoptions konfiguriert, wenn -b zweimal angegeben wird.

Überschreiben des Standardfilters¶

Entwickler von Anwendungen, die in Python geschrieben sind, möchten möglicherweise *alle* Python-Warnungen standardmäßig vor ihren Benutzern verbergen und sie nur beim Ausführen von Tests oder bei der Arbeit an der Anwendung anzeigen. Das Attribut sys.warnoptions, das zur Übergabe von Filterkonfigurationen an den Interpreter verwendet wird, kann als Markierung verwendet werden, um anzuzeigen, ob Warnungen deaktiviert werden sollen oder nicht

import sys

if not sys.warnoptions:
    import warnings
    warnings.simplefilter("ignore")

Entwickler von Testrunnern für Python-Code sollten stattdessen sicherstellen, dass *alle* Warnungen für den zu testenden Code standardmäßig angezeigt werden, indem sie Code wie folgt verwenden

import sys

if not sys.warnoptions:
    import os, warnings
    warnings.simplefilter("default") # Change the filter in this process
    os.environ["PYTHONWARNINGS"] = "default" # Also affect subprocesses

Schließlich wird Entwicklern von interaktiven Shells, die Benutzercode in einem anderen Namensraum als __main__ ausführen, empfohlen, sicherzustellen, dass DeprecationWarning-Nachrichten standardmäßig sichtbar gemacht werden, indem sie Code wie den folgenden verwenden (wobei user_ns das Modul ist, das zur Ausführung von interaktiv eingegebenem Code verwendet wird)

import warnings
warnings.filterwarnings("default", category=DeprecationWarning,
                                   module=user_ns.get("__name__"))

Warnungen vorübergehend unterdrücken¶

Wenn Sie Code verwenden, von dem Sie wissen, dass er eine Warnung auslöst, z. B. eine veraltete Funktion, aber die Warnung nicht sehen möchten (auch wenn Warnungen explizit über die Kommandozeile konfiguriert wurden), können Sie die Warnung mit dem Kontextmanager catch_warnings unterdrücken

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    fxn()

Innerhalb des Kontextmanagers werden alle Warnungen einfach ignoriert. Dies ermöglicht es Ihnen, bekannten veralteten Code zu verwenden, ohne die Warnung sehen zu müssen, während anderer Code, der sich möglicherweise nicht seiner Verwendung von veraltetem Code bewusst ist, nicht unterdrückt wird.

Hinweis

Siehe Concurrent safety of Context Managers für Details zur Nebenläufigkeitssicherheit des Kontextmanagers catch_warnings bei der Verwendung in Programmen mit mehreren Threads oder asynchronen Funktionen.

Warnungen testen¶

Um von Code ausgelöste Warnungen zu testen, verwenden Sie den Kontextmanager catch_warnings. Damit können Sie den Warnfilter vorübergehend ändern, um Ihre Tests zu erleichtern. Zum Beispiel können Sie Folgendes tun, um alle ausgelösten Warnungen zu erfassen und zu überprüfen

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings(record=True) as w:
    # Cause all warnings to always be triggered.
    warnings.simplefilter("always")
    # Trigger a warning.
    fxn()
    # Verify some things
    assert len(w) == 1
    assert issubclass(w[-1].category, DeprecationWarning)
    assert "deprecated" in str(w[-1].message)

Man kann auch alle Warnungen in Ausnahmen umwandeln, indem man anstelle von always error verwendet. Eine Sache, die man beachten muss, ist, dass wenn eine Warnung bereits aufgrund einer once/default Regel ausgelöst wurde, dann wird die Warnung, egal welche Filter gesetzt sind, nicht wieder gesehen, es sei denn, die Warnregistrierung im Zusammenhang mit der Warnung wurde gelöscht.

Nachdem der Kontextmanager beendet wurde, wird der Warnungsfilter in seinen Zustand zurückversetzt, als der Kontext betreten wurde. Dies verhindert, dass Tests den Warnungsfilter auf unerwartete Weise zwischen den Tests ändern und zu unbestimmten Testergebnissen führen.

Hinweis

Siehe Concurrent safety of Context Managers für Details zur Nebenläufigkeitssicherheit des Kontextmanagers catch_warnings bei der Verwendung in Programmen mit mehreren Threads oder asynchronen Funktionen.

Beim Testen mehrerer Operationen, die die gleiche Art von Warnung auslösen, ist es wichtig, sie so zu testen, dass jede Operation eine neue Warnung auslöst (z. B. Warnungen als Ausnahmen auslösen und prüfen, ob die Operationen Ausnahmen auslösen, prüfen, ob die Länge der Warnungsliste nach jeder Operation weiter ansteigt, oder die vorherigen Einträge aus der Warnungsliste vor jeder neuen Operation löschen).

Code für neue Versionen von Abhängigkeiten aktualisieren¶

Warnungskategorien, die hauptsächlich für Python-Entwickler (und nicht für Endbenutzer von in Python geschriebenen Anwendungen) von Interesse sind, werden standardmäßig ignoriert.

Insbesondere beinhaltet diese Liste "standardmäßig ignoriert" DeprecationWarning (für alle Module außer __main__), was bedeutet, dass Entwickler sicherstellen sollten, ihre Tests mit normalerweise ignorierten Warnungen sichtbar zu machen, um rechtzeitige Benachrichtigungen über zukünftige, abwärtskompatible API-Änderungen (entweder in der Standardbibliothek oder in Drittanbieterpaketen) zu erhalten.

Im Idealfall verfügt der Code über eine geeignete Testsuite, und der Testrunner kümmert sich implizit um die Aktivierung aller Warnungen beim Ausführen von Tests (der vom Modul unittest bereitgestellte Testrunner tut dies).

In weniger idealen Fällen können Anwendungen auf die Verwendung veralteter Schnittstellen überprüft werden, indem -Wd an den Python-Interpreter übergeben wird (dies ist eine Kurzform für -W default) oder indem PYTHONWARNINGS=default in der Umgebung gesetzt wird. Dies aktiviert die Standardbehandlung für alle Warnungen, einschließlich derjenigen, die standardmäßig ignoriert werden. Um zu ändern, welche Aktion für aufgetretene Warnungen ausgeführt wird, können Sie ändern, welches Argument an -W übergeben wird (z. B. -W error). Weitere Details zu den Möglichkeiten finden Sie im -W Flag.

Verfügbare Funktionen¶

warnings.warn(message, category=None, stacklevel=1, source=None, *, skip_file_prefixes=())¶

Gibt eine Warnung aus, oder ignoriert sie oder löst eine Ausnahme aus. Das Argument category muss, falls gegeben, eine Warnungskategorie-Klasse sein; es ist standardmäßig UserWarning. Alternativ kann message eine Instanz von Warning sein, in diesem Fall wird category ignoriert und message.__class__ wird verwendet. In diesem Fall ist der Nachrichtentext str(message). Diese Funktion löst eine Ausnahme aus, wenn die spezifische ausgegebene Warnung durch den Warnungsfilter in einen Fehler umgewandelt wird. Das Argument stacklevel kann von Wrapper-Funktionen in Python wie folgt verwendet werden

def deprecated_api(message):
    warnings.warn(message, DeprecationWarning, stacklevel=2)

Dies bewirkt, dass die Warnung auf den Aufrufer von deprecated_api verweist, anstatt auf die Quelle von deprecated_api selbst (da letzteres den Zweck der Warnmeldung verfehlen würde).

Das Schlüsselwortargument skip_file_prefixes kann verwendet werden, um anzugeben, welche Stack-Frames beim Zählen von Stack-Levels ignoriert werden. Dies kann nützlich sein, wenn Sie möchten, dass die Warnung immer an Aufrufer-Sites außerhalb eines Pakets erscheint, wenn ein konstantes stacklevel nicht für alle Aufrufwege passt oder anderweitig schwierig zu warten ist. Wenn angegeben, muss es ein Tupel von Zeichenketten sein. Wenn Präfixe angegeben werden, wird `stacklevel` implizit auf max(2, stacklevel) überschrieben. Um eine Warnung dem Aufrufer außerhalb des aktuellen Pakets zuzuordnen, könnten Sie schreiben

# example/lower.py
_warn_skips = (os.path.dirname(__file__),)

def one_way(r_luxury_yacht=None, t_wobbler_mangrove=None):
    if r_luxury_yacht:
        warnings.warn("Please migrate to t_wobbler_mangrove=.",
                      skip_file_prefixes=_warn_skips)

# example/higher.py
from . import lower

def another_way(**kw):
    lower.one_way(**kw)

Dies bewirkt, dass sich die Warnung auf die Aufruf-Sites example.lower.one_way() und example.higher.another_way() bezieht, aber nur von aufrufendem Code außerhalb des example Pakets.

source, falls angegeben, ist das zerstörte Objekt, das eine ResourceWarning ausgelöst hat.

Geändert in Version 3.6: Parameter source hinzugefügt.

Geändert in Version 3.12: Parameter skip_file_prefixes hinzugefügt.

warnings.warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)¶

Dies ist eine Low-Level-Schnittstelle zur Funktionalität von warn(), bei der Nachricht, Kategorie, Dateiname und Zeilennummer explizit übergeben werden, sowie optional der Modulname und die Registrierung (welche das __warningregistry__-Dictionary des Moduls sein sollte). Der Modulname ist standardmäßig der Dateiname mit angehängtem .py; wenn keine Registrierung übergeben wird, wird die Warnung nie unterdrückt. message muss eine Zeichenkette sein und category eine Unterklasse von Warning oder message kann eine Instanz von Warning sein, in diesem Fall wird category ignoriert.

module_globals, falls angegeben, sollte der globale Namensraum sein, der vom Code verwendet wird, für den die Warnung ausgegeben wird. (Dieses Argument wird verwendet, um die Anzeige von Quellen für Module zu unterstützen, die in Zip-Dateien oder anderen nicht-Dateisystem-Importquellen gefunden werden).

source, falls angegeben, ist das zerstörte Objekt, das eine ResourceWarning ausgelöst hat.

Geändert in Version 3.6: Parameter source hinzugefügt.

warnings.showwarning(message, category, filename, lineno, file=None, line=None)¶: Schreibt eine Warnung in eine Datei. Die Standardimplementierung ruft formatwarning(message, category, filename, lineno, line) auf und schreibt die resultierende Zeichenkette in file, die standardmäßig sys.stderr ist. Sie können diese Funktion durch jeden aufrufbaren Wert ersetzen, indem Sie warnings.showwarning zuweisen. line ist eine Zeile Quellcode, die in die Warnmeldung aufgenommen werden soll; wenn line nicht angegeben ist, versucht showwarning(), die von filename und lineno angegebene Zeile zu lesen.

warnings.formatwarning(message, category, filename, lineno, line=None)¶: Formatiert eine Warnung auf die übliche Weise. Dies gibt eine Zeichenkette zurück, die eingebettete Zeilenumbrüche enthalten kann und mit einem Zeilenumbruch endet. line ist eine Zeile Quellcode, die in die Warnmeldung aufgenommen werden soll; wenn line nicht angegeben ist, versucht formatwarning(), die von filename und lineno angegebene Zeile zu lesen.

warnings.filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False)¶: Fügt einen Eintrag zur Liste der Warnfilter-Spezifikationen hinzu. Der Eintrag wird standardmäßig vorne eingefügt; wenn append true ist, wird er am Ende eingefügt. Dies überprüft die Typen der Argumente, kompiliert die regulären Ausdrücke für message und module und fügt sie als Tupel in die Liste der Warnfilter ein. Einträge, die näher am Anfang der Liste stehen, überschreiben Einträge, die später in der Liste stehen, wenn beide eine bestimmte Warnung abgleichen. Fehlende Argumente haben den Standardwert, der alles abgleicht.

warnings.simplefilter(action, category=Warning, lineno=0, append=False)¶: Fügt einen einfachen Eintrag zur Liste der Warnfilter-Spezifikationen hinzu. Die Bedeutung der Funktionsparameter ist wie bei filterwarnings(), aber reguläre Ausdrücke sind nicht erforderlich, da der eingefügte Filter immer eine beliebige Nachricht in einem beliebigen Modul abgleicht, solange die Kategorie und die Zeilennummer übereinstimmen.

warnings.resetwarnings()¶: Setzt den Warnfilter zurück. Dies verwirft die Wirkung aller vorherigen Aufrufe von filterwarnings(), einschließlich der Befehlszeilenoptionen -W und der Aufrufe von simplefilter().

@warnings.deprecated(msg, *, category=DeprecationWarning, stacklevel=1)¶

Decorator, um anzugeben, dass eine Klasse, Funktion oder Überladung veraltet ist.

Wenn dieser Decorator auf ein Objekt angewendet wird, können zur Laufzeit bei der Verwendung des Objekts Veraltungswarnungen ausgegeben werden. Statische Typprüfer generieren ebenfalls eine Diagnose bei der Verwendung des veralteten Objekts.

Verwendung

from warnings import deprecated
from typing import overload

@deprecated("Use B instead")
class A:
    pass

@deprecated("Use g instead")
def f():
    pass

@overload
@deprecated("int support is deprecated")
def g(x: int) -> int: ...
@overload
def g(x: str) -> int: ...

Die durch category angegebene Warnung wird zur Laufzeit bei der Verwendung veralteter Objekte ausgegeben. Bei Funktionen geschieht dies bei Aufrufen; bei Klassen bei der Instanziierung und bei der Erstellung von Unterklassen. Wenn category None ist, wird zur Laufzeit keine Warnung ausgegeben. stacklevel bestimmt, wo die Warnung ausgegeben wird. Wenn es 1 (Standard) ist, wird die Warnung beim direkten Aufrufer des veralteten Objekts ausgegeben; wenn es höher ist, wird es weiter oben im Stapel ausgegeben. Das Verhalten statischer Typprüfer wird von den Argumenten category und stacklevel nicht beeinflusst.

Die dem Decorator übergebene Veraltungsmeldung wird im Attribut __deprecated__ des dekorierten Objekts gespeichert. Wenn sie auf eine Überladung angewendet wird, muss der Decorator nach dem Decorator @~typing.overload erfolgen, damit das Attribut auf der von typing.get_overloads() zurückgegebenen Überladung vorhanden ist.

Hinzugefügt in Version 3.13: Siehe PEP 702.

Verfügbare Kontextmanager¶

class warnings.catch_warnings(*, record=False, module=None, action=None, category=Warning, lineno=0, append=False)¶

Ein Kontextmanager, der den Warnfilter und die Funktion showwarning() kopiert und beim Beenden wiederherstellt. Wenn das Argument record False (Standard) ist, gibt der Kontextmanager beim Eintritt None zurück. Wenn record True ist, wird eine Liste zurückgegeben, die schrittweise mit Objekten gefüllt wird, wie sie von einer benutzerdefinierten showwarning()-Funktion gesehen werden (die auch die Ausgabe an sys.stdout unterdrückt). Jedes Objekt in der Liste hat Attribute mit denselben Namen wie die Argumente von showwarning().

Das Argument module nimmt ein Modul entgegen, das anstelle des Moduls verwendet wird, das zurückgegeben wird, wenn Sie warnings importieren, dessen Filter geschützt wird. Dieses Argument existiert hauptsächlich zum Testen des warnings-Moduls selbst.

Wenn das Argument action nicht None ist, werden die verbleibenden Argumente an simplefilter() übergeben, als ob es unmittelbar beim Betreten des Kontexts aufgerufen worden wäre.

Siehe Der Warnfilter für die Bedeutung der Parameter category und lineno.

Hinweis

Siehe Concurrent safety of Context Managers für Details zur Nebenläufigkeitssicherheit des Kontextmanagers catch_warnings bei der Verwendung in Programmen mit mehreren Threads oder asynchronen Funktionen.

Geändert in Version 3.11: Hinzugefügt wurden die Parameter action, category, lineno und append.

Gleichzeitige Sicherheit von Kontextmanagern¶

Das Verhalten des Kontextmanagers catch_warnings hängt vom Flag sys.flags.context_aware_warnings ab. Wenn das Flag true ist, verhält sich der Kontextmanager gleichzeitigkeitsicher, andernfalls nicht. Gleichzeitigkeitsicher bedeutet, dass er sowohl thread-sicher als auch sicher in asyncio-Coroutinen und Tasks ist. Thread-sicher zu sein bedeutet, dass das Verhalten in einem Multithread-Programm vorhersehbar ist. Das Flag ist standardmäßig für freie Thread-Builds true und andernfalls false.

Wenn das Flag context_aware_warnings false ist, modifiziert catch_warnings die globalen Attribute des warnings-Moduls. Dies ist nicht sicher, wenn es in einem gleichzeitigen Programm (mit mehreren Threads oder mit asyncio-Coroutinen) verwendet wird. Wenn beispielsweise zwei oder mehr Threads gleichzeitig die Klasse catch_warnings verwenden, ist das Verhalten undefiniert.

Wenn das Flag true ist, modifiziert catch_warnings keine globalen Attribute und verwendet stattdessen eine ContextVar, um den neu etablierten Warnfilterzustand zu speichern. Eine Kontextvariable bietet Thread-lokalen Speicher und macht die Verwendung von catch_warnings thread-sicher.

Der Parameter record des Kontext-Handlers verhält sich ebenfalls unterschiedlich, abhängig vom Wert des Flags. Wenn record true ist und das Flag false ist, arbeitet der Kontextmanager, indem er die showwarning()-Funktion des Moduls ersetzt und später wiederherstellt. Dies ist nicht gleichzeitigkeitsicher.

Wenn record true ist und das Flag true ist, wird die showwarning()-Funktion nicht ersetzt. Stattdessen wird der Aufzeichnungsstatus durch eine interne Eigenschaft in der Kontextvariablen angezeigt. In diesem Fall wird die showwarning()-Funktion beim Verlassen des Kontext-Handlers nicht wiederhergestellt.

Das Flag context_aware_warnings kann über die Befehlszeilenoption -X context_aware_warnings oder die Umgebungsvariable PYTHON_CONTEXT_AWARE_WARNINGS gesetzt werden.

Hinweis

Es ist wahrscheinlich, dass die meisten Programme, die ein thread-sicheres Verhalten des Warnmoduls wünschen, auch das Flag sys.flags.thread_inherit_context auf true setzen möchten. Dieses Flag bewirkt, dass Threads, die von threading.Thread erstellt werden, mit einer Kopie der Kontextvariablen des startenden Threads beginnen. Wenn true, gilt der in einem Thread von catch_warnings eingerichtete Kontext auch für neue Threads, die von ihm gestartet werden. Wenn false, starten neue Threads mit einer leeren Warnungskontextvariable, was bedeutet, dass jede Filterung, die von einem catch_warnings-Kontextmanager eingerichtet wurde, nicht mehr aktiv ist.

Geändert in Version 3.14: Hinzugefügt wurden das Flag sys.flags.context_aware_warnings und die Verwendung einer Kontextvariablen für catch_warnings, wenn das Flag true ist. Frühere Versionen von Python verhielten sich so, als wäre das Flag immer auf false gesetzt.

`warnings` — Warnungssteuerung¶

Warnungskategorien¶

Der Warnungsfilter¶

Kriterien für die Unterdrückung wiederholter Warnungen¶

Beschreibung von Warnfiltern¶

Standard-Warnfilter¶

Überschreiben des Standardfilters¶

Warnungen vorübergehend unterdrücken¶

Warnungen testen¶

Code für neue Versionen von Abhängigkeiten aktualisieren¶

Verfügbare Funktionen¶

Verfügbare Kontextmanager¶

Gleichzeitige Sicherheit von Kontextmanagern¶

Inhaltsverzeichnis

Vorheriges Thema

Nächstes Thema

Diese Seite

warnings — Warnungssteuerung¶

Warnungskategorien¶

Der Warnungsfilter¶

Kriterien für die Unterdrückung wiederholter Warnungen¶

Beschreibung von Warnfiltern¶

Standard-Warnfilter¶

Überschreiben des Standardfilters¶

Warnungen vorübergehend unterdrücken¶

Warnungen testen¶

Code für neue Versionen von Abhängigkeiten aktualisieren¶

Verfügbare Funktionen¶

Verfügbare Kontextmanager¶

Gleichzeitige Sicherheit von Kontextmanagern¶

`warnings` — Warnungssteuerung¶