bpo-43862: Enhance -W cmdline option documentation (GH-25439)
The -W format is "action:message:category:module:lineno".
Update also the Python manual page.
diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
index 5e9296a..325e607 100644
--- a/Doc/c-api/init_config.rst
+++ b/Doc/c-api/init_config.rst
@@ -1135,6 +1135,13 @@
item of :data:`warnings.filters` which is checked first (highest
priority).
+ The :option:`-W` command line options adds its value to
+ :c:member:`~PyConfig.warnoptions`, it can be used multiple times.
+
+ The :envvar:`PYTHONWARNINGS` environment variable can also be used to add
+ warning options. Multiple options can be specified, separated by commas
+ (``,``).
+
Default: empty list.
.. c:member:: int write_bytecode
diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv
index a3ee332..b9e1067 100644
--- a/Doc/tools/susp-ignored.csv
+++ b/Doc/tools/susp-ignored.csv
@@ -279,7 +279,11 @@
tutorial/stdlib2,,:start,filename = data[start:start+filenamesize]
tutorial/stdlib2,,:Warning,WARNING:root:Warning:config file server.conf not found
using/cmdline,,:errorhandler,:errorhandler
-using/cmdline,,:line,file:line: category: message
+using/cmdline,,:message,action:message:category:module:lineno
+using/cmdline,,:category,action:message:category:module:lineno
+using/cmdline,,:module,action:message:category:module:lineno
+using/cmdline,,:lineno,action:message:category:module:lineno
+using/cmdline,,::,-W ignore::DeprecationWarning
using/unix,,:Packaging,https://en.opensuse.org/Portal:Packaging
whatsnew/2.0,,:len,
whatsnew/2.3,,::,
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index a39cfd6..09d8fa9 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -380,25 +380,8 @@
.. _using-on-warnings:
.. cmdoption:: -W arg
- Warning control. Python's warning machinery by default prints warning
- messages to :data:`sys.stderr`. A typical warning message has the following
- form:
-
- .. code-block:: none
-
- file:line: category: message
-
- By default, each warning is printed once for each source line where it
- occurs. This option controls how often warnings are printed.
-
- Multiple :option:`-W` options may be given; when a warning matches more than
- one option, the action for the last matching option is performed. Invalid
- :option:`-W` options are ignored (though, a warning message is printed about
- invalid options when the first warning is issued).
-
- Warnings can also be controlled using the :envvar:`PYTHONWARNINGS`
- environment variable and from within a Python program using the
- :mod:`warnings` module.
+ Warning control. Python's warning machinery by default prints warning
+ messages to :data:`sys.stderr`.
The simplest settings apply a particular action unconditionally to all
warnings emitted by a process (even those that are otherwise ignored by
@@ -411,14 +394,48 @@
-Wonce # Warn once per Python process
-Wignore # Never warn
- The action names can be abbreviated as desired (e.g. ``-Wi``, ``-Wd``,
- ``-Wa``, ``-We``) and the interpreter will resolve them to the appropriate
- action name.
+ The action names can be abbreviated as desired and the interpreter will
+ resolve them to the appropriate action name. For example, ``-Wi`` is the
+ same as ``-Wignore``.
+
+ The full form of argument is::
+
+ action:message:category:module:lineno
+
+ Empty fields match all values; trailing empty fields may be omitted. For
+ example ``-W ignore::DeprecationWarning`` ignores all DeprecationWarning
+ warnings.
+
+ The *action* field is as explained above but only applies to warnings that
+ match the remaining fields.
+
+ The *message* field must match the whole warning message; this match is
+ case-insensitive.
+
+ The *category* field matches the warning category
+ (ex: ``DeprecationWarning``). This must be a class name; the match test
+ whether the actual warning category of the message is a subclass of the
+ specified warning category.
+
+ The *module* field matches the (fully-qualified) module name; this match is
+ case-sensitive.
+
+ The *lineno* field matches the line number, where zero matches all line
+ numbers and is thus equivalent to an omitted line number.
+
+ Multiple :option:`-W` options can be given; when a warning matches more than
+ one option, the action for the last matching option is performed. Invalid
+ :option:`-W` options are ignored (though, a warning message is printed about
+ invalid options when the first warning is issued).
+
+ Warnings can also be controlled using the :envvar:`PYTHONWARNINGS`
+ environment variable and from within a Python program using the
+ :mod:`warnings` module. For example, the :func:`warnings.filterwarnings`
+ function can be used to use a regular expression on the warning message.
See :ref:`warning-filter` and :ref:`describing-warning-filters` for more
details.
-
.. cmdoption:: -x
Skip the first line of the source, allowing use of non-Unix forms of
diff --git a/Misc/python.man b/Misc/python.man
index 3ea1801..10cb807 100644
--- a/Misc/python.man
+++ b/Misc/python.man
@@ -207,71 +207,76 @@
.B \-V ", " \-\-version
Prints the Python version number of the executable and exits. When given
twice, print more information about the build.
+
.TP
.BI "\-W " argument
-Warning control. Python sometimes prints warning message to
+Warning control. Python's warning machinery by default prints warning messages
+to
.IR sys.stderr .
-A typical warning message has the following form:
-.IB file ":" line ": " category ": " message.
-By default, each warning is printed once for each source line where it
-occurs. This option controls how often warnings are printed.
-Multiple
-.B \-W
-options may be given; when a warning matches more than one
-option, the action for the last matching option is performed.
-Invalid
-.B \-W
-options are ignored (a warning message is printed about invalid
-options when the first warning is issued). Warnings can also be
-controlled from within a Python program using the
-.I warnings
-module.
-The simplest form of
-.I argument
-is one of the following
-.I action
-strings (or a unique abbreviation):
-.B ignore
-to ignore all warnings;
-.B default
-to explicitly request the default behavior (printing each warning once
-per source line);
-.B all
-to print a warning each time it occurs (this may generate many
-messages if a warning is triggered repeatedly for the same source
-line, such as inside a loop);
-.B module
-to print each warning only the first time it occurs in each
-module;
-.B once
-to print each warning only the first time it occurs in the program; or
-.B error
-to raise an exception instead of printing a warning message.
+The simplest settings apply a particular action unconditionally to all warnings
+emitted by a process (even those that are otherwise ignored by default):
-The full form of
-.I argument
-is
-.IB action : message : category : module : line.
-Here,
+ -Wdefault # Warn once per call location
+ -Werror # Convert to exceptions
+ -Walways # Warn every time
+ -Wmodule # Warn once per calling module
+ -Wonce # Warn once per Python process
+ -Wignore # Never warn
+
+The action names can be abbreviated as desired and the interpreter will resolve
+them to the appropriate action name. For example,
+.B -Wi
+is the same as
+.B -Wignore .
+
+The full form of argument is:
+.IB action:message:category:module:lineno
+
+Empty fields match all values; trailing empty fields may be omitted. For
+example
+.B -W ignore::DeprecationWarning
+ignores all DeprecationWarning warnings.
+
+The
.I action
-is as explained above but only applies to messages that match the
-remaining fields. Empty fields match all values; trailing empty
-fields may be omitted. The
+field is as explained above but only applies to warnings that match
+the remaining fields.
+
+The
.I message
-field matches the start of the warning message printed; this match is
-case-insensitive. The
+field must match the whole printed warning message; this match is
+case-insensitive.
+
+The
.I category
-field matches the warning category. This must be a class name; the
-match test whether the actual warning category of the message is a
-subclass of the specified warning category. The full class name must
-be given. The
+field matches the warning category (ex: "DeprecationWarning"). This must be a
+class name; the match test whether the actual warning category of the message
+is a subclass of the specified warning category.
+
+The
.I module
-field matches the (fully-qualified) module name; this match is
-case-sensitive. The
-.I line
-field matches the line number, where zero matches all line numbers and
-is thus equivalent to an omitted line number.
+field matches the (fully-qualified) module name; this match is case-sensitive.
+
+The
+.I lineno
+field matches the line number, where zero matches all line numbers and is thus
+equivalent to an omitted line number.
+
+Multiple
+.B -W
+options can be given; when a warning matches more than one option, the action
+for the last matching option is performed. Invalid
+.B -W
+options are ignored (though, a warning message is printed about invalid options
+when the first warning is issued).
+
+Warnings can also be controlled using the
+.B PYTHONWARNINGS
+environment variable and from within a Python program using the warnings
+module. For example, the warnings.filterwarnings() function can be used to use
+a regular expression on the warning message.
+
.TP
.BI "\-X " option
Set implementation specific option. The following options are available:
