From 7c61e57f99757fe9268f418c240a50dbc8df4459 Mon Sep 17 00:00:00 2001 From: WYSIATI Date: Wed, 1 Apr 2026 21:44:06 +0800 Subject: [PATCH] gh-146642: Clarify -W regex requires at least two characters The documentation for the -W option's message and module fields states that a value starting and ending with a forward slash is treated as a regular expression. However, the implementation requires the value to be at least two characters long (so a bare "/" is treated as a literal string, not a regex). Update the docs in both cmdline.rst and warnings.rst to mention this requirement. --- Doc/library/warnings.rst | 12 ++++++------ Doc/using/cmdline.rst | 13 +++++++------ 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index b25384dbfce54b..2ab988fdfb1ced 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -159,9 +159,9 @@ the disposition of the match. Each entry is a tuple of the form (*action*, * *message* is a string containing a regular expression that the start of the warning message must match, case-insensitively. In :option:`-W` and - :envvar:`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 + :envvar:`PYTHONWARNINGS`, if *message* is at least two characters long and + 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*. @@ -170,9 +170,9 @@ the disposition of the match. Each entry is a tuple of the form (*action*, * *module* is a string containing a regular expression that the start of the fully qualified module name must match, case-sensitively. In :option:`-W` and - :envvar:`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 + :envvar:`PYTHONWARNINGS`, if *module* is at least two characters long and + 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*. diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 73cd8d31d0b20d..54b1355e90f421 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -481,8 +481,9 @@ Miscellaneous options The *message* field must match the start of the warning message; this match is case-insensitive. - If it starts and ends with a forward slash (``/``), it specifies - a regular expression, otherwise it specifies a literal string. + If it is at least two characters long and starts and ends with a forward + slash (``/``), it specifies a regular expression, otherwise it specifies a + literal string. The *category* field matches the warning category (ex: ``DeprecationWarning``). This must be a class name; the match test @@ -491,10 +492,10 @@ Miscellaneous options The *module* field matches the (fully qualified) module name; this match is case-sensitive. - If it starts and ends with a forward slash (``/``), it specifies - a regular expression that the start of the fully qualified module name - must match, otherwise it specifies a literal string that the fully - qualified module name must be equal to. + If it is at least two characters long and starts and ends with a forward + slash (``/``), it specifies a regular expression that the start of the fully + qualified module name must match, otherwise it specifies a literal string + that the fully qualified module name must be equal to. The *lineno* field matches the line number, where zero matches all line numbers and is thus equivalent to an omitted line number.