diff options
Diffstat (limited to 'Doc/lib/libwarnings.tex')
| -rw-r--r-- | Doc/lib/libwarnings.tex | 253 |
1 files changed, 0 insertions, 253 deletions
diff --git a/Doc/lib/libwarnings.tex b/Doc/lib/libwarnings.tex deleted file mode 100644 index a37a9f5..0000000 --- a/Doc/lib/libwarnings.tex +++ /dev/null @@ -1,253 +0,0 @@ -\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 overridden; 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.} - -\lineii{PendingDeprecationWarning}{Base category for warnings about -features that will be deprecated in the future (ignored by default).} - -\lineii{ImportWarning}{Base category for warnings triggered during the -process of importing a module (ignored by default).} - -\lineii{UnicodeWarning}{Base category for warnings related to Unicode.} - -\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}). - -The warnings that are ignored by default may be enabled by passing - \programopt{-Wd} to the interpreter. This enables default handling -for all warnings, including those that are normally ignored by -default. This is particular useful for enabling ImportWarning when -debugging problems importing a developed package. ImportWarning can -also be enabled explicitly in Python code using: - -\begin{verbatim} - warnings.simplefilter('default', ImportWarning) -\end{verbatim} - - -\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\optional{, - module_globals}}}} -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. - -\var{module_globals}, if supplied, should be the global namespace in use -by the code for which the warning is issued. (This argument is used to -support displaying source for modules found in zipfiles or other -non-filesystem import sources, and was added in Python 2.5.) -\end{funcdesc} - -\begin{funcdesc}{showwarning}{message, category, filename, - lineno\optional{, file}} -Write a warning to a file. The default implementation calls -\code{formatwarning(\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 the -list of warnings filters. Entries closer to the front of the list -override entries later in the list, if both match a particular -warning. Omitted arguments default to a value that matches -everything. -\end{funcdesc} - -\begin{funcdesc}{simplefilter}{action\optional{, - category\optional{, - lineno\optional{, append}}}} -Insert a simple entry into the list of warnings filters. The meaning -of the function parameters is as for \function{filterwarnings()}, but -regular expressions are not needed as the filter inserted always -matches any message in any module as long as the category and line -number match. -\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 and calls to -\function{simplefilter()}. -\end{funcdesc} |