From 7c61e57f99757fe9268f418c240a50dbc8df4459 Mon Sep 17 00:00:00 2001 From: WYSIATI Date: Wed, 1 Apr 2026 21:44:06 +0800 Subject: [PATCH 1/2] 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. From d69bf9b60df65361a0e48dc40e82a9e79b804a1b Mon Sep 17 00:00:00 2001 From: Chester Li Date: Fri, 3 Apr 2026 11:57:40 +0800 Subject: [PATCH 2/2] Clarify single / edge case instead of length requirement Replace "at least two characters long" with a parenthetical note that a single / on its own is treated as a literal string. --- Doc/library/warnings.rst | 14 ++++++++------ Doc/using/cmdline.rst | 15 ++++++++------- 2 files changed, 16 insertions(+), 13 deletions(-) diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index 2ab988fdfb1ced..6ad3166ee18f2c 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -159,9 +159,10 @@ 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* 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 + :envvar:`PYTHONWARNINGS`, if *message* starts and ends with a forward + slash (``/``), it specifies a regular expression as above (a single ``/`` + on its own is treated as a literal string); 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 +171,10 @@ 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* 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 + :envvar:`PYTHONWARNINGS`, if *module* starts and ends with a forward + slash (``/``), it specifies a regular expression as above (a single ``/`` + on its own is treated as a literal string); 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 54b1355e90f421..6e571eff2098c7 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -481,9 +481,9 @@ Miscellaneous options The *message* field must match the start of the warning message; this match is case-insensitive. - 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. + If it starts and ends with a forward slash (``/``), it specifies a regular + expression (a single ``/`` on its own is treated as a literal string), + otherwise it specifies a literal string. The *category* field matches the warning category (ex: ``DeprecationWarning``). This must be a class name; the match test @@ -492,10 +492,11 @@ Miscellaneous options The *module* field matches the (fully qualified) module name; this match is case-sensitive. - 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. + If it starts and ends with a forward slash (``/``), it specifies a regular + expression (a single ``/`` on its own is treated as a literal string) 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.