warnings --- Warning control — Dokumentasi Python 3.15.2
Navigasi index modul | berikut | sebelum | Python » 3.15.2 documentation » The Python standard library » Layanan Runtime Python » warnings --- Warning control | Tema | warnings --- Warning control ¶ Source code: Lib/warnings.py 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 warn() function defined in this module. (C programmers use PyErr_WarnEx() ; see Penanganan Pengecualian for details). Warning messages are normally written to 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 , 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 filterwarnings() and reset to its default state by calling resetwarnings() . The printing of warning messages is done by calling showwarning() , which may be overridden; the default implementation of this function formats the message by calling formatwarning() , which is also available for use by custom implementations. Lihat juga logging.captureWarnings() allows you to handle all warnings with the standard logging infrastructure.
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. 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 Warning class.
The following warnings category classes are currently defined: Class Deskripsi Warning Base class for warning categories. It is a subclass of Exception . UserWarning Base class for warnings generated by user code. The default category for warn() . DeprecationWarning Base class for warnings about deprecated features when those warnings are intended for other Python developers (ignored by default, unless triggered by code in __main__ ).
PendingDeprecationWarning Base class for warnings about features that will be deprecated in the future (ignored by default). SyntaxWarning Base class for warnings about dubious syntax (typically emitted when compiling Python source code, and hence may not be suppressed by runtime filters). RuntimeWarning Base class for warnings about dubious runtime behavior. FutureWarning Base class for warnings about deprecated features when those warnings are intended for end users of applications that are written in Python.
ImportWarning Base class for warnings triggered during the process of importing a module (ignored by default). UnicodeWarning Base class for warnings related to Unicode. EncodingWarning Base class for warnings related to encodings. See Opt-in EncodingWarning for details. BytesWarning Base class for warnings related to bytes and bytearray . ResourceWarning Base class for warnings related to resource usage (ignored by default).
Berubah pada versi 3.7: Previously DeprecationWarning and FutureWarning were distinguished based on whether a feature was being removed entirely or changing its behaviour. They are now distinguished based on their intended audience and the way they're handled by the default warnings filters. The Warnings 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 filter determines the disposition of the match. Each entry is a tuple of the form ( action , message , category , module , lineno ), where: action is one of the following strings: Nilai Disposition "default" print the first occurrence of matching warnings for each location (module + line number) where the warning is issued "error" turn matching warnings into exceptions "ignore" never print matching warnings "always" always print matching warnings "all" alias to "always" "module" print the first occurrence of matching warnings for each module where the warning is issued (regardless of line number) "once" print only the first occurrence of matching warnings, regardless of location message is a string containing a regular expression that the start of the warning message must match, case-insensitively.
In -W and PYTHONWARNINGS , if message starts and ends with a forward slash ( / ), it specifies a regular expression as above; otherwise it is a literal string that the start of the warning message must match (case-insensitively), ignoring any whitespace at the start or end of message . category is a class (a subclass of Warning ) of which the warning category must be a subclass in order to match. 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 , if module starts and ends with a forward slash ( / ), it specifies a regular expression as above; otherwise it 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 is an integer that the line number where the warning occurred must match, or 0 to match all line numbers. Since the Warning class is derived from the built-in Exception class, to turn a warning into an error we simply raise category(message) .
If a warning is reported and doesn't match any registered filter then the "default" action is applied (hence its name). 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. Describing Warning Filters ¶ 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 ).
Individual warnings filters are specified as a sequence of fields separated by colons: action : message : category : module : line The meaning of each of these fields is as described in The Warnings Filter . When listing multiple filters on a single line (as for PYTHONWARNINGS ), the individual filters are separated by commas and the filters listed later take precedence over those listed before them (as they're applied left-to-right, and the most recently applied filters take precedence over earlier ones).
Commonly used warning filters apply to either all warnings, warnings in a particular categor
The rest of this page is on the live site.