29.5. warnings — Contrôle des alertes

Code source: Lib/warnings.py

Les messages d’avertissement sont généralement émis dans les situations où il est utile d’alerter l’utilisateur d’un problème dans un programme, mais qu’il n’est pas justifié de lever une exception et de le terminer. Par exemple, on peut vouloir émettre un avertissement lorsqu’un programme utilise un module obsolète.

Les développeurs Python émettent des avertissements en appelant la fonction warn() définie dans ce module. (Les développeurs C utilisent PyErr_WarnEx() ; voir Gestion des exceptions pour plus d’informations).

Les messages d’avertissement sont normalement écrits sur sys.stderr, mais leurs effets peuvent être modifiés, il est possible d’ignorer tous les avertissements ou au contraire les transformer en exceptions. L’effet des avertissements peut varier en fonction de la catégorie d’avertissement (voir ci-dessous), de son texte et d’où il est émis. Les répétitions d’un même avertissement d’une même source sont généralement ignorés.

La gestion des avertissements se fait en deux étapes : premièrement, chaque fois qu’un avertissement est émis, le module détermine si un message doit être émis ou non ; ensuite, si un message doit être émis, il est formaté et affiché en utilisant une fonction qui peut être définie par l’utilisateur.

Un filtre (une séquence de règles) est utilisé pour décider si un message d’avertissement doit être émis ou non. Des règles peuvent être ajoutées au filtre en appelant filterwarnings() et remises à leur état par défaut en appelant resetwarnings().

L’affichage des messages d’avertissement se fait en appelant la fonction showwarning(), qui peut être redéfinie ; l’implémentation par défaut formate le message en appelant formatwarning(), qui peut également être réutilisée par une implémentation personnalisée.

Voir aussi

logging.captureWarnings() vous permet de gérer tous les avertissements avec l’infrastructure de journalisation standard.

29.5.1. Catégories d’avertissement

There are a number of built-in exceptions that represent warning categories. This categorization is useful to be able to filter out groups of warnings. The following warnings category classes are currently defined:

Classe

Description

Warning

Il s’agit de la classe de base de toutes les classes de catégories d’avertissement. C’est une sous-classe de Exception.

UserWarning

Catégorie par défaut pour warn().

DeprecationWarning

Base category for warnings about deprecated features (ignored by default).

SyntaxWarning

Catégorie de base pour les avertissements concernant les syntaxes douteuses.

RuntimeWarning

Catégorie de base pour les avertissements concernant les fonctionnalités douteuses à l’exécution.

FutureWarning

Base category for warnings about constructs that will change semantically in the future.

PendingDeprecationWarning

Catégorie de base pour les avertissements concernant les fonctionnalités qui seront obsolètes dans le futur (ignorée par défaut).

ImportWarning

Catégorie de base pour les avertissements déclenchés lors de l’importation d’un module (ignoré par défaut).

UnicodeWarning

Catégorie de base pour les avertissements relatifs à Unicode.

BytesWarning

Catégorie de base pour les avertissements relatifs à bytes et bytearray.

ResourceWarning

Catégorie de base pour les avertissements relatifs à l’utilisation des ressources.

While these are technically built-in exceptions, they are documented here, because conceptually they belong to the warnings mechanism.

Le code utilisateur peut définir des catégories d’avertissement supplémentaires en héritant l’une des catégories d’avertissement standard. Une catégorie d’avertissement doit toujours hériter de la classe Warning.

29.5.2. Le filtre des avertissements

Le filtre des avertissements contrôle si les avertissements sont ignorés, affichés ou transformés en erreurs (ce qui lève une exception).

Conceptually, the warnings filter maintains an ordered list of filter specifications; any specific warning is matched against each filter specification in the list in turn until a match is found; the match determines the disposition of the match. Each entry is a tuple of the form (action, message, category, module, lineno), where:

  • action est l’une des chaînes de caractères suivantes :

    Valeur

    Action

    "error"

    transforme les avertissements correspondants en exceptions

    "ignore"

    ignore les avertissements correspondants

    "always"

    affiche toujours les avertissements correspondants

    "default"

    print the first occurrence of matching warnings for each location where the warning is issued

    "module"

    print the first occurrence of matching warnings for each module where the warning is issued

    "once"

    n’affiche que la première occurrence des avertissements correspondants, quel que soit l’endroit où ils se trouvent

  • message est une chaîne de caractères contenant une expression régulière avec laquelle le début du message d’avertissement doit correspondre. L’expression est compilée pour être toujours insensible à la casse.

  • category est une classe (une sous-classe de Warning) dont la catégorie d’avertissement doit être une sous-classe afin de correspondre.

  • module est une chaîne de caractères contenant une expression régulière avec laquelle le nom du module doit correspondre. L’expression est compilée pour être sensible à la casse.

  • lineno est le numéro de ligne d’où l’avertissement doit provenir, ou 0 pour correspondre à tous les numéros de ligne.

Puisque que la classe Warning hérite de la classe Exception, pour transformer un avertissement en erreur, il suffit de lever category(message).

The warnings filter is initialized by -W options passed to the Python interpreter command line. The interpreter saves the arguments for all -W options without interpretation in sys.warnoptions; the warnings module parses these when it is first imported (invalid options are ignored, after printing a message to sys.stderr).

29.5.2.1. Default Warning Filters

By default, Python installs several warning filters, which can be overridden by the command-line options passed to -W and calls to filterwarnings().

Modifié dans la version 3.2: DeprecationWarning est maintenant ignoré par défaut en plus de PendingDeprecationWarning.

29.5.3. Suppression temporaire des avertissements

If you are using code that you know will raise a warning, such as a deprecated function, but do not want to see the warning, then it is possible to suppress the warning using the catch_warnings context manager:

import warnings

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

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

Dans le gestionnaire de contexte, tous les avertissements sont simplement ignorés. Ceci vous permet d’utiliser du code déclaré obsolète sans voir l’avertissement tout en ne supprimant pas l’avertissement pour un autre code qui pourrait ne pas être conscient de son utilisation de code déprécié. Remarque : ceci ne peut être garanti que dans une application utilisant un seul fil d’exécution. Si deux ou plusieurs threads utilisent le gestionnaire de contexte catch_warnings en même temps, le comportement est indéfini.

29.5.4. Tester les avertissements

Pour tester les avertissements générés par le code, utilisez le gestionnaire de contexte catch_warnings. Avec lui, vous pouvez temporairement modifier le filtre d’avertissements pour faciliter votre test. Par exemple, procédez comme suit pour capturer tous les avertissements levés à vérifier :

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)

Vous pouvez aussi faire en sorte que tous les avertissements soient des exceptions en utilisant error au lieu de always. Il faut savoir que si un avertissement a déjà été émis à cause d’une règle once ou default, quel que soit le filtre activé, l’avertissement ne sera pas revu à moins que le registre des avertissements lié à l’avertissement ait été vidé.

A sa sortie, le gestionnaire de contexte restaure le filtre des avertissements dans l’état où il était au démarrage du contexte. Cela empêche les tests de changer le filtre d’avertissements de manière inattendue entre les tests et d’aboutir à des résultats de test indéterminés. La fonction showwarning() du module est également restaurée à sa valeur originale. Remarque : ceci ne peut être garanti que dans une application mono-threadées. Si deux ou plusieurs fils d’exécution utilisent le gestionnaire de contexte catch_warnings en même temps, le comportement est indéfini.

Lorsque vous testez plusieurs opérations qui provoquent le même type d’avertissement, il est important de les tester d’une manière qui confirme que chaque opération provoque un nouvel avertissement (par exemple, définissez les avertissements comme exceptions et vérifiez que les opérations provoquent des exceptions, vérifiez que la longueur de la liste des avertissements continue à augmenter après chaque opération, ou bien supprimez les entrées précédentes de la liste des avertissements avant chaque nouvelle opération).

29.5.5. Updating Code For New Versions of Python

Warnings that are only of interest to the developer are ignored by default. As such you should make sure to test your code with typically ignored warnings made visible. You can do this from the command-line by passing -Wd to the interpreter (this is shorthand for -W default). This enables default handling for all warnings, including those that are ignored by default. To change what action is taken for encountered warnings you simply change what argument is passed to -W, e.g. -W error. See the -W flag for more details on what is possible.

To programmatically do the same as -Wd, use:

warnings.simplefilter('default')

Make sure to execute this code as soon as possible. This prevents the registering of what warnings have been raised from unexpectedly influencing how future warnings are treated.

Having certain warnings ignored by default is done to prevent a user from seeing warnings that are only of interest to the developer. As you do not necessarily have control over what interpreter a user uses to run their code, it is possible that a new version of Python will be released between your release cycles. The new interpreter release could trigger new warnings in your code that were not there in an older interpreter, e.g. DeprecationWarning for a module that you are using. While you as a developer want to be notified that your code is using a deprecated module, to a user this information is essentially noise and provides no benefit to them.

The unittest module has been also updated to use the 'default' filter while running tests.

29.5.6. Fonctions disponibles

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

Émet, ignore, ou transforme en exception un avertissement. L’argument category, s’il est donné, doit être une classe de catégorie d’avertissement (voir ci-dessus) ; et vaut par défaut UserWarning. Aussi message peut être une instance de Warning', auquel cas *category* sera ignoré et ``message.__class__` sera utilisé. Dans ce cas, le texte du message sera str(message). Cette fonction lève une exception si cet avertissement particulier émis est transformé en erreur par le filtre des avertissements, voir ci-dessus. L’argument stacklevel peut être utilisé par les fonctions wrapper écrites en Python, comme ceci :

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

Fait en sorte que l’avertissement se réfère à l’appelant de deprecation() plutôt qu’à la source de deprecation() elle-même (puisque celle-ci irait à l’encontre du but du message d’avertissement).

source, s’il est fourni, est l’objet détruit qui a émis un ResourceWarning.

Modifié dans la version 3.6: Ajout du paramètre source.

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

Il s’agit d’une interface de bas niveau pour la fonctionnalité de warn(), en passant explicitement le message, la catégorie, le nom de fichier et le numéro de ligne, et éventuellement le nom du module et le registre (qui devrait être le dictionnaire __warningregistry__ du module). Le nom de module par défaut est le nom de fichier sans .py ; si aucun registre n’est passé, l’avertissement n’est jamais supprimé. message doit être une chaîne de caractères et category une sous-classe de Warning ou message peut être une instance de Warning, auquel cas category sera ignoré.

module_globals, s’il est fourni, doit être l’espace de nommage global utilisé par le code pour lequel l’avertissement est émis. (Cet argument est utilisé pour afficher les sources des modules trouvés dans les fichiers zip ou d’autres sources d’importation hors du système de fichiers).

source, s’il est fourni, est l’objet détruit qui a émis un ResourceWarning.

Modifié dans la version 3.6: Ajout du paramètre source.

warnings.showwarning(message, category, filename, lineno, file=None, line=None)

Écrit un avertissement dans un fichier. L’implémentation par défaut appelle format warning(message, category, filename, lineno, line)``et écrit la chaîne résultante dans *file*, qui par défaut est ``sys.stderr. Vous pouvez remplacer cette fonction par n’importe quel appelable en l’affectant à warnings.showwarning. line est une ligne de code source à inclure dans le message d’avertissement ; si line n’est pas fourni, show warning() essaiera de lire la ligne spécifiée par filename et lineno.

warnings.formatwarning(message, category, filename, lineno, line=None)

Formate un avertissement de la manière standard. Ceci renvoie une chaîne pouvant contenir des retours à la ligne se termine par un retour à la ligne. line est une ligne de code source à inclure dans le message d’avertissement ; si line n’est pas fourni, formatwarning() essaiera de lire la ligne spécifiée par filename et lineno.

warnings.filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False)

Insère une entrée dans la liste de warning filter specifications. L’entrée est insérée à l’avant par défaut ; si append est vrai, elle est insérée à la fin. Il vérifie le type des arguments, compile les expressions régulières message et module, et les insère sous forme de tuple dans la liste des filtres d’avertissements. Les entrées plus proches du début de la liste ont priorité sur les entrées plus loin dans la liste. Les arguments omis ont par défaut une valeur qui correspond à tout.

warnings.simplefilter(action, category=Warning, lineno=0, append=False)

Insère une entrée simple dans la liste de spécifications du filtre d’avertissements. La signification des paramètres de fonction est la même que pour filterwarnings(), mais les expressions régulières ne sont pas nécessaires car le filtre inséré correspond toujours à n’importe quel message dans n’importe quel module tant que la catégorie et le numéro de ligne correspondent.

warnings.resetwarnings()

Réinitialise le filtre des avertissements. Ceci supprime l’effet de tous les appels précédents à filterwarnings(), y compris celui de l’option -W des options de ligne de commande et des appels à simplefilter().

29.5.7. Gestionnaires de contexte disponibles

class warnings.catch_warnings(*, record=False, module=None)

Un gestionnaire de contexte qui copie et, à la sortie, restaure le filtre des avertissements et la fonction showwarning(). Si l’argument record est False (par défaut), le gestionnaire de contexte retourne None en entrant. Si record est True, une liste est renvoyée qui est progressivement remplie d’objets comme vus par une fonction custom showwarning' (qui supprime également la sortie vers ``sys.stdout`()). Chaque objet de la liste a des attributs avec les mêmes noms que les arguments de showwarning().

L’argument module prend un module qui sera utilisé à la place du module renvoyé lors de l’importation warnings dont le filtre sera protégé. Cet argument existe principalement pour tester le module warnings lui-même.

Note

Le gestionnaire catch_warnings fonctionne en remplaçant puis en restaurant plus tard la fonction showwarning() du module et la liste interne des spécifications du filtre. Cela signifie que le gestionnaire de contexte modifie l’état global et n’est donc pas prévisible avec plusieurs fils d’exécution.