bpo-43862: Enhance -W cmdline option documentation (GH-25439)

The -W format is "action:message:category:module:lineno".

Update also the Python manual page.

4 files changed, 113 insertions, 80 deletions

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 @@ PyConfig
       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,"fields = struct.unpack('<IIIHH', data[start:start+16])
 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 @@ Miscellaneous options
 .. _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 @@ Miscellaneous options
        -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 @@ at exit.
 .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: