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/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