| \section{\module{warnings} --- |
| Warning control} |
| |
| \declaremodule{standard}{warnings} |
| \modulesynopsis{Issue warning messages and control their disposition.} |
| \index{warnings} |
| |
| \versionadded{2.1} |
| |
| Warning messages are typically issued in situations where it is useful |
| to alert the user of some condition in a program, where that condition |
| (normally) doesn't warrant raising an exception and terminating the |
| program. For example, one might want to issue a warning when a |
| program uses an obsolete module. |
| |
| Python programmers issue warnings by calling the \function{warn()} |
| function defined in this module. (C programmers use |
| \cfunction{PyErr_Warn()}; see the |
| \citetitle[../api/exceptionHandling.html]{Python/C API Reference |
| Manual} for details). |
| |
| Warning messages are normally written to \code{sys.stderr}, but their |
| disposition can be changed flexibly, from ignoring all warnings to |
| turning them into exceptions. The disposition of warnings can vary |
| based on the warning category (see below), the text of the warning |
| message, and the source location where it is issued. Repetitions of a |
| particular warning for the same source location are typically |
| suppressed. |
| |
| There are two stages in warning control: first, each time a warning is |
| issued, a determination is made whether a message should be issued or |
| not; next, if a message is to be issued, it is formatted and printed |
| using a user-settable hook. |
| |
| The determination whether to issue a warning message is controlled by |
| the warning filter, which is a sequence of matching rules and actions. |
| Rules can be added to the filter by calling |
| \function{filterwarnings()} and reset to its default state by calling |
| \function{resetwarnings()}. |
| |
| The printing of warning messages is done by calling |
| \function{showwarning()}, which may be overidden; the default |
| implementation of this function formats the message by calling |
| \function{formatwarning()}, which is also available for use by custom |
| implementations. |
| |
| |
| \subsection{Warning Categories \label{warning-categories}} |
| |
| 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: |
| |
| \begin{tableii}{l|l}{exception}{Class}{Description} |
| |
| \lineii{Warning}{This is the base class of all warning category |
| classes. It is a subclass of \exception{Exception}.} |
| |
| \lineii{UserWarning}{The default category for \function{warn()}.} |
| |
| \lineii{DeprecationWarning}{Base category for warnings about |
| deprecated features.} |
| |
| \lineii{SyntaxWarning}{Base category for warnings about dubious |
| syntactic features.} |
| |
| \lineii{RuntimeWarning}{Base category for warnings about dubious |
| runtime features.} |
| |
| \lineii{FutureWarning}{Base category for warnings about constructs |
| that will change semantically in the future.} |
| |
| \end{tableii} |
| |
| While these are technically built-in exceptions, they are documented |
| here, because conceptually they belong to the warnings mechanism. |
| |
| User code can define additional warning categories by subclassing one |
| of the standard warning categories. A warning category must always be |
| a subclass of the \exception{Warning} class. |
| |
| |
| \subsection{The Warnings Filter \label{warning-filter}} |
| |
| The warnings filter controls whether warnings are ignored, displayed, |
| or turned into errors (raising an 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 (\var{action}, \var{message}, \var{category}, \var{module}, |
| \var{lineno}), where: |
| |
| \begin{itemize} |
| |
| \item \var{action} is one of the following strings: |
| |
| \begin{tableii}{l|l}{code}{Value}{Disposition} |
| |
| \lineii{"error"}{turn matching warnings into exceptions} |
| |
| \lineii{"ignore"}{never print matching warnings} |
| |
| \lineii{"always"}{always print matching warnings} |
| |
| \lineii{"default"}{print the first occurrence of matching |
| warnings for each location where the warning is issued} |
| |
| \lineii{"module"}{print the first occurrence of matching |
| warnings for each module where the warning is issued} |
| |
| \lineii{"once"}{print only the first occurrence of matching |
| warnings, regardless of location} |
| |
| \end{tableii} |
| |
| \item \var{message} is a string containing a regular expression that |
| the warning message must match (the match is compiled to always be |
| case-insensitive) |
| |
| \item \var{category} is a class (a subclass of \exception{Warning}) of |
| which the warning category must be a subclass in order to match |
| |
| \item \var{module} is a string containing a regular expression that the module |
| name must match (the match is compiled to be case-sensitive) |
| |
| \item \var{lineno} is an integer that the line number where the |
| warning occurred must match, or \code{0} to match all line |
| numbers |
| |
| \end{itemize} |
| |
| Since the \exception{Warning} class is derived from the built-in |
| \exception{Exception} class, to turn a warning into an error we simply |
| raise \code{category(message)}. |
| |
| The warnings filter is initialized by \programopt{-W} options passed |
| to the Python interpreter command line. The interpreter saves the |
| arguments for all \programopt{-W} options without interpretation in |
| \code{sys.warnoptions}; the \module{warnings} module parses these when |
| it is first imported (invalid options are ignored, after printing a |
| message to \code{sys.stderr}). |
| |
| |
| \subsection{Available Functions \label{warning-functions}} |
| |
| \begin{funcdesc}{warn}{message\optional{, category\optional{, stacklevel}}} |
| Issue a warning, or maybe ignore it or raise an exception. The |
| \var{category} argument, if given, must be a warning category class |
| (see above); it defaults to \exception{UserWarning}. Alternatively |
| \var{message} can be a \exception{Warning} instance, in which case |
| \var{category} will be ignored and \code{message.__class__} will be used. |
| In this case the message text will be \code{str(message)}. This function |
| raises an exception if the particular warning issued is changed |
| into an error by the warnings filter see above. The \var{stacklevel} |
| argument can be used by wrapper functions written in Python, like |
| this: |
| |
| \begin{verbatim} |
| def deprecation(message): |
| warnings.warn(message, DeprecationWarning, stacklevel=2) |
| \end{verbatim} |
| |
| This makes the warning refer to \function{deprecation()}'s caller, |
| rather than to the source of \function{deprecation()} itself (since |
| the latter would defeat the purpose of the warning message). |
| \end{funcdesc} |
| |
| \begin{funcdesc}{warn_explicit}{message, category, filename, |
| lineno\optional{, module\optional{, registry}}} |
| This is a low-level interface to the functionality of |
| \function{warn()}, passing in explicitly the message, category, |
| filename and line number, and optionally the module name and the |
| registry (which should be the \code{__warningregistry__} dictionary of |
| the module). The module name defaults to the filename with \code{.py} |
| stripped; if no registry is passed, the warning is never suppressed. |
| \var{message} must be a string and \var{category} a subclass of |
| \exception{Warning} or \var{message} may be a \exception{Warning} instance, |
| in which case \var{category} will be ignored. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{showwarning}{message, category, filename, |
| lineno\optional{, file}} |
| Write a warning to a file. The default implementation calls |
| \code{showwarning(\var{message}, \var{category}, \var{filename}, |
| \var{lineno})} and writes the resulting string to \var{file}, which |
| defaults to \code{sys.stderr}. You may replace this function with an |
| alternative implementation by assigning to |
| \code{warnings.showwarning}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{formatwarning}{message, category, filename, lineno} |
| Format a warning the standard way. This returns a string which may |
| contain embedded newlines and ends in a newline. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{filterwarnings}{action\optional{, |
| message\optional{, category\optional{, |
| module\optional{, lineno\optional{, append}}}}}} |
| Insert an entry into the list of warnings filters. The entry is |
| inserted at the front by default; if \var{append} is true, it is |
| inserted at the end. |
| This checks the types of the arguments, compiles the message and |
| module regular expressions, and inserts them as a tuple in front |
| of the warnings filter. Entries inserted later override entries |
| inserted earlier, if both match a particular warning. Omitted |
| arguments default to a value that matches everything. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{resetwarnings}{} |
| Reset the warnings filter. This discards the effect of all previous |
| calls to \function{filterwarnings()}, including that of the |
| \programopt{-W} command line options. |
| \end{funcdesc} |