"warnings" --- Warning control
******************************

**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 selon la  catégorie
d'avertissement, de son texte et d'où il est émis. Les répétitions du
même avertissement depuis une même source sont généralement ignorées.

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.


Catégories d'avertissement
==========================

Il existe un certain nombre d'exceptions natives qui représentent des
catégories d'avertissement. Cette catégorisation est utile pour
filtrer les groupes d'avertissements.

Bien qu'il s'agisse techniquement d'exceptions, les exceptions natives
sont documentées ici, parce qu'elles appartiennent conceptuellement au
mécanisme des avertissements.

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".

Les classes de catégories d'avertissement suivantes sont actuellement
définies :

+------------------------------------+-------------------------------------------------+
| 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"               | Catégorie de base pour les avertissements sur   |
|                                    | les fonctionnalités obsolètes lorsque ces       |
|                                    | avertissements sont destinés à d'autres         |
|                                    | développeurs Python (ignorées par défaut, sauf  |
|                                    | si elles proviennent de "__main__").            |
+------------------------------------+-------------------------------------------------+
| "SyntaxWarning"                    | Base category for warnings about dubious        |
|                                    | syntactic features (typically emitted when      |
|                                    | compiling Python source code, and hence may not |
|                                    | be suppressed by runtime filters)               |
+------------------------------------+-------------------------------------------------+
| "RuntimeWarning"                   | Catégorie de base pour les avertissements       |
|                                    | concernant les fonctionnalités douteuses à      |
|                                    | l'exécution.                                    |
+------------------------------------+-------------------------------------------------+
| "FutureWarning"                    | Catégorie de base pour les avertissements       |
|                                    | concernant les fonctionnalités obsolètes        |
|                                    | lorsque ces avertissements sont destinés aux    |
|                                    | utilisateurs finaux des programmes écrits en    |
|                                    | Python.                                         |
+------------------------------------+-------------------------------------------------+
| "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         |
|                                    | (ignorés par défaut).                           |
+------------------------------------+-------------------------------------------------+

Modifié dans la version 3.7: Avant, la différence entre
"DeprecationWarning" et "FutureWarning" était que l'un était dédié aux
fonctionnalités retirées, et l'autre aux fonctionnalités modifiées. La
différence aujourd'hui est plutôt leur audience et la façon dont ils
sont traités par les filtres d'avertissement par défaut.


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).

Conceptuellement, le filtre d'avertissements maintient une liste
ordonnée d'entrées ; chaque avertissement est comparé à chaque entrée
de la liste jusqu'à ce qu'une correspondance soit trouvée ; l'entrée
détermine l'action à effectuer.  Chaque entrée est un quintuplet de la
forme (*action*, *message*, *catégorie*, *module*, *lineno*), où :

* *action* est l'une des chaînes de caractères suivantes :

  +-----------------+------------------------------------------------+
  | Valeur          | Action                                         |
  |=================|================================================|
  | ""default""     | affiche la première occurrence des             |
  |                 | avertissements correspondants pour chaque      |
  |                 | emplacement (module + numéro de ligne) où      |
  |                 | l'avertissement est émis                       |
  +-----------------+------------------------------------------------+
  | ""error""       | transforme les avertissements correspondants   |
  |                 | en exceptions                                  |
  +-----------------+------------------------------------------------+
  | ""ignore""      | ignore les avertissements correspondants       |
  +-----------------+------------------------------------------------+
  | ""always""      | affiche toujours les avertissements            |
  |                 | correspondants                                 |
  +-----------------+------------------------------------------------+
  | ""all""         | alias to "always"                              |
  +-----------------+------------------------------------------------+
  | ""module""      | affiche la première occurrence des             |
  |                 | avertissements correspondants pour chaque      |
  |                 | module où l'avertissement est émis (quel que   |
  |                 | soit le numéro de ligne)                       |
  +-----------------+------------------------------------------------+
  | ""once""        | n'affiche que la première occurrence des       |
  |                 | avertissements correspondants, quel que soit   |
  |                 | l'endroit où ils se trouvent                   |
  +-----------------+------------------------------------------------+

* *message* is a string containing a regular expression that the start
  of the warning message must match, case-insensitively.  In "-W" and
  "PYTHONWARNINGS", *message* is a literal string that the start of
  the warning message must contain (case-insensitively), ignoring any
  whitespace at the start or end of *message*.

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

* *module* is a string containing a regular expression that the start
  of the fully qualified module name must match, case-sensitively.  In
  "-W" and "PYTHONWARNINGS", *module* is a literal string that the
  fully qualified module name must be equal to (case-sensitively),
  ignoring any whitespace at the start or end of *module*.

* *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)".

Si un avertissement est signalé et ne correspond à aucun filtre
enregistré, l'action "default" est appliquée (d'où son nom).


Repeated Warning Suppression Criteria
-------------------------------------

The filters that suppress repeated warnings apply the following
criteria to determine if a warning is considered a repeat:

* ""default"": A warning is considered a repeat only if the
  (*message*, *category*, *module*, *lineno*) are all the same.

* ""module"": A warning is considered a repeat if the (*message*,
  *category*, *module*) are the same, ignoring the line number.

* ""once"": A warning is considered a repeat if the (*message*,
  *category*) are the same, ignoring the module and line number.


Rédaction de filtres d'avertissement
------------------------------------

The warnings filter is initialized by "-W" options passed to the
Python interpreter command line and the "PYTHONWARNINGS" environment
variable. The interpreter saves the arguments for all supplied entries
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").

Les filtres d'avertissement individuels sont décrits sous la forme
d'une séquence de champs séparés par des deux-points :

   action:message:category:module:line

La signification de chacun de ces champs est décrite dans Le filtre
des avertissements. Plusieurs filtres peuvent être écrits en une seule
ligne (comme pour "PYTHONWARNINGS"), ils sont dans ce cas séparés par
des virgules, et les filtres listés plus en dernier ont priorité sur
ceux qui les précèdent (car ils sont appliqués de gauche à droite, et
les filtres les plus récemment appliqués ont priorité sur les
précédents).

Les filtres d'avertissement couramment utilisés s'appliquent à tous
les avertissements, aux avertissements d'une catégorie particulière ou
aux avertissements émis par certains modules ou paquets. Quelques
exemples :

   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"


Filtre d'avertissement par défaut
---------------------------------

Par défaut, Python installe plusieurs filtres d'avertissement, qui
peuvent être outrepassés par l'option "-W" en ligne de commande, la
variable d'environnement "PYTHONWARNINGS" et les appels à
"filterwarnings()".

Dans les versions standard publiées de Python, le filtre
d'avertissement par défaut a les entrées suivantes (par ordre de
priorité) :

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

Dans les versions de débogage, la liste des filtres d'avertissement
par défaut est vide.

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

Modifié dans la version 3.7: "DeprecationWarning" est à nouveau
affiché par défaut lorsqu'il provient directement de "__main__".

Modifié dans la version 3.7: "BytesWarning" n'apparaît plus dans la
liste de filtres par défaut et est configuré via "sys.warnoptions"
lorsque l'option "-b" est donnée deux fois.


Outrepasser le filtre par défaut
--------------------------------

Les développeurs d'applications écrites en Python peuvent souhaiter
cacher *tous* les avertissements Python à leurs utilisateurs, et ne
les afficher que lorsqu'ils exécutent des tests ou travaillent sur
l'application. L'attribut "sys.warnoptions" utilisé pour passer les
configurations de filtre à l'interpréteur peut être utilisé comme
marqueur pour indiquer si les avertissements doivent être ou non
désactivés :

   import sys

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

Les développeurs d'exécuteurs de test pour le code Python sont invités
à s'assurer que *tous* les avertissements sont affichés par défaut
pour le code en cours de test, en utilisant par exemple :

   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

Enfin, les développeurs d'interpréteurs de commandes interactifs qui
exécutent du code utilisateur dans un espace de nommage autre que
"__main__" sont invités à s'assurer que les messages
"DeprecationWarning" sont rendus visibles par défaut, en utilisant le
code suivant (où "user_ns" est le module utilisé pour exécuter le code
entré interactivement) :

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


Suppression temporaire des avertissements
=========================================

Si vous utilisez un code dont vous savez qu'il va déclencher un
avertissement, comme une fonction obsolète, mais que vous ne voulez
pas voir l'avertissement (même si les avertissements ont été
explicitement configurés via la ligne de commande), alors il est
possible de supprimer l'avertissement en utilisant le gestionnaire de
contexte "catch_warnings" :

   import warnings

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

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

While within the context manager all warnings will simply be ignored.
This allows you to use known-deprecated code without having to see the
warning while not suppressing the warning for other code that might
not be aware of its use of deprecated code.

   Note:

     See Concurrent safety of Context Managers for details on the
     concurrency-safety of the "catch_warnings" context manager when
     used in programs using multiple threads or async functions.


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é.

Once the context manager exits, the warnings filter is restored to its
state when the context was entered. This prevents tests from changing
the warnings filter in unexpected ways between tests and leading to
indeterminate test results.

   Note:

     See Concurrent safety of Context Managers for details on the
     concurrency-safety of the "catch_warnings" context manager when
     used in programs using multiple threads or async functions.

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).


Mise à jour du code pour les nouvelles versions des dépendances
===============================================================

Les catégories d'avertissement qui intéressent principalement les
développeurs Python (plutôt que les utilisateurs finaux d'applications
écrites en Python) sont ignorées par défaut.

Notamment, cette liste "ignorés par défaut" inclut
"DeprecationWarning" (pour chaque module sauf "__main__"), ce qui
signifie que les développeurs doivent s'assurer de tester leur code
avec des avertissements généralement ignorés rendus visibles afin de
recevoir des notifications rapides des changements d'API (que ce soit
dans la bibliothèque standard ou les paquets tiers).

Dans le cas idéal, le code dispose d'une suite de tests appropriée, et
le testeur se charge d'activer implicitement tous les avertissements
lors de l'exécution des tests (le testeur fourni par le module
"unittest" le fait).

Dans des cas moins idéaux, l'utilisation de d'interfaces obsolète peut
être testé en passant "-Wd" à l'interpréteur Python (c'est une
abréviation pour "-W default") ou en définissant
"PYTHONWARNINGS=default" dans l'environnement. Ceci permet la gestion
par défaut de tous les avertissements, y compris ceux qui sont ignorés
par défaut. Pour changer l'action prise pour les avertissements
rencontrés, vous pouvez changer quel argument est passé à "-W" (par
exemple "-W error"). Voir l'option "-W" pour plus de détails sur ce
qui est possible.


Fonctions disponibles
=====================

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

   Émet, ignore, ou transforme en exception un avertissement.
   L'argument *category*, s'il est donné, doit être une classe de
   warning category class ; 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.  L'argument
   *stacklevel* peut être utilisé par les fonctions *wrapper* écrites
   en Python, comme ceci :

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

   This makes the warning refer to "deprecated_api"'s caller, rather
   than to the source of "deprecated_api" itself (since the latter
   would defeat the purpose of the warning message).

   The *skip_file_prefixes* keyword argument can be used to indicate
   which stack frames are ignored when counting stack levels. This can
   be useful when you want the warning to always appear at call sites
   outside of a package when a constant *stacklevel* does not fit all
   call paths or is otherwise challenging to maintain. If supplied, it
   must be a tuple of strings. When prefixes are supplied, stacklevel
   is implicitly overridden to be "max(2, stacklevel)". To cause a
   warning to be attributed to the caller from outside of the current
   package you might write:

      # 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)

   This makes the warning refer to both the "example.lower.one_way()"
   and "example.higher.another_way()" call sites only from calling
   code living outside of "example" package.

   *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*.

   Modifié dans la version 3.12: Added *skip_file_prefixes*.

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

   This is a low-level interface to the functionality of "warn()",
   passing in explicitly the message, category, filename and line
   number, and optionally other arguments. *message* must be a string
   and *category* a subclass of "Warning" or *message* may be a
   "Warning" instance, in which case *category* will be ignored.

   *module*, if supplied, should be the module name. If no module is
   passed, the filename with ".py" stripped is used.

   *registry*, if supplied, should be the "__warningregistry__"
   dictionary of the module. If no registry is passed, each warning is
   treated as the first occurrence, that is, filter actions
   ""default"", ""module"" and ""once"" are handled as ""always"".

   *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 "formatwarning(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, "showwarning()"
   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 *n*-uplet 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()".

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

   Decorator to indicate that a class, function or overload is
   deprecated.

   When this decorator is applied to an object, deprecation warnings
   may be emitted at runtime when the object is used. *static type
   checkers* will also generate a diagnostic on usage of the
   deprecated object.

   Utilisation :

      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: ...

   The warning specified by *category* will be emitted at runtime on
   use of deprecated objects. For functions, that happens on calls;
   for classes, on instantiation and on creation of subclasses. If the
   *category* is "None", no warning is emitted at runtime. The
   *stacklevel* determines where the warning is emitted. If it is "1"
   (the default), the warning is emitted at the direct caller of the
   deprecated object; if it is higher, it is emitted further up the
   stack. Static type checker behavior is not affected by the
   *category* and *stacklevel* arguments.

   The deprecation message passed to the decorator is saved in the
   "__deprecated__" attribute on the decorated object. If applied to
   an overload, the decorator must be after the "@~typing.overload"
   decorator for the attribute to exist on the overload as returned by
   "typing.get_overloads()".

   Ajouté dans la version 3.13: See **PEP 702**.


Gestionnaires de contexte disponibles
=====================================

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

   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()".

   The *module* argument takes a module that will be used instead of
   the module returned when you import "warnings" whose filter will be
   protected. This argument exists primarily for testing the
   "warnings" module itself.

   If the *action* argument is not "None", the remaining arguments are
   passed to "simplefilter()" as if it were called immediately on
   entering the context.

   See Le filtre des avertissements for the meaning of the *category*
   and *lineno* parameters.

   Note:

     See Concurrent safety of Context Managers for details on the
     concurrency-safety of the "catch_warnings" context manager when
     used in programs using multiple threads or async functions.

   Modifié dans la version 3.11: Added the *action*, *category*,
   *lineno*, and *append* parameters.


Concurrent safety of Context Managers
=====================================

The behavior of "catch_warnings" context manager depends on the
"sys.flags.context_aware_warnings" flag.  If the flag is true, the
context manager behaves in a concurrent-safe fashion and otherwise
not. Concurrent-safe means that it is both thread-safe and safe to use
within asyncio coroutines and tasks.  Being thread-safe means that
behavior is predictable in a multi-threaded program.  The flag
defaults to true for free-threaded builds and false otherwise.

If the "context_aware_warnings" flag is false, then "catch_warnings"
will modify the global attributes of the "warnings" module.  This is
not safe if used within a concurrent program (using multiple threads
or using asyncio coroutines).  For example, if two or more threads use
the "catch_warnings" class at the same time, the behavior is
undefined.

If the flag is true, "catch_warnings" will not modify global
attributes and will instead use a "ContextVar" to store the newly
established warning filtering state.  A context variable provides
thread-local storage and it makes the use of "catch_warnings" thread-
safe.

The *record* parameter of the context handler also behaves differently
depending on the value of the flag.  When *record* is true and the
flag is false, the context manager works by replacing and then later
restoring the module's "showwarning()" function.  That is not
concurrent-safe.

When *record* is true and the flag is true, the "showwarning()"
function is not replaced.  Instead, the recording status is indicated
by an internal property in the context variable.  In this case, the
"showwarning()" function will not be restored when exiting the context
handler.

The "context_aware_warnings" flag can be set the "-X
context_aware_warnings" command-line option or by the
"PYTHON_CONTEXT_AWARE_WARNINGS" environment variable.

   Note:

     It is likely that most programs that desire thread-safe behaviour
     of the warnings module will also want to set the
     "thread_inherit_context" flag to true.  That flag causes threads
     created by "threading.Thread" to start with a copy of the context
     variables from the thread starting it.  When true, the context
     established by "catch_warnings" in one thread will also apply to
     new threads started by it.  If false, new threads will start with
     an empty warnings context variable, meaning that any filtering
     that was established by a "catch_warnings" context manager will
     no longer be active.

Modifié dans la version 3.14: Added the
"sys.flags.context_aware_warnings" flag and the use of a context
variable for "catch_warnings" if the flag is true.  Previous versions
of Python acted as if the flag was always set to false.
