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

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

Update also the Python manual page.

1 files changed, 61 insertions, 56 deletions

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: