Skip to content

Commit 7c61e57

Browse files
committed
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.
1 parent 9e5b838 commit 7c61e57

File tree

2 files changed

+13
-12
lines changed

2 files changed

+13
-12
lines changed

Doc/library/warnings.rst

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -159,9 +159,9 @@ the disposition of the match. Each entry is a tuple of the form (*action*,
159159

160160
* *message* is a string containing a regular expression that the start of
161161
the warning message must match, case-insensitively. In :option:`-W` and
162-
:envvar:`PYTHONWARNINGS`, if *message* starts and ends with a forward slash
163-
(``/``), it specifies a regular expression as above;
164-
otherwise it is a literal string that the start of the
162+
:envvar:`PYTHONWARNINGS`, if *message* is at least two characters long and
163+
starts and ends with a forward slash (``/``), it specifies a regular
164+
expression as above; otherwise it is a literal string that the start of the
165165
warning message must match (case-insensitively), ignoring any whitespace at
166166
the start or end of *message*.
167167

@@ -170,9 +170,9 @@ the disposition of the match. Each entry is a tuple of the form (*action*,
170170

171171
* *module* is a string containing a regular expression that the start of the
172172
fully qualified module name must match, case-sensitively. In :option:`-W` and
173-
:envvar:`PYTHONWARNINGS`, if *module* starts and ends with a forward slash
174-
(``/``), it specifies a regular expression as above;
175-
otherwise it is a literal string that the
173+
:envvar:`PYTHONWARNINGS`, if *module* is at least two characters long and
174+
starts and ends with a forward slash (``/``), it specifies a regular
175+
expression as above; otherwise it is a literal string that the
176176
fully qualified module name must be equal to (case-sensitively), ignoring any
177177
whitespace at the start or end of *module*.
178178

Doc/using/cmdline.rst

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -481,8 +481,9 @@ Miscellaneous options
481481

482482
The *message* field must match the start of the warning message;
483483
this match is case-insensitive.
484-
If it starts and ends with a forward slash (``/``), it specifies
485-
a regular expression, otherwise it specifies a literal string.
484+
If it is at least two characters long and starts and ends with a forward
485+
slash (``/``), it specifies a regular expression, otherwise it specifies a
486+
literal string.
486487

487488
The *category* field matches the warning category
488489
(ex: ``DeprecationWarning``). This must be a class name; the match test
@@ -491,10 +492,10 @@ Miscellaneous options
491492

492493
The *module* field matches the (fully qualified) module name; this match is
493494
case-sensitive.
494-
If it starts and ends with a forward slash (``/``), it specifies
495-
a regular expression that the start of the fully qualified module name
496-
must match, otherwise it specifies a literal string that the fully
497-
qualified module name must be equal to.
495+
If it is at least two characters long and starts and ends with a forward
496+
slash (``/``), it specifies a regular expression that the start of the fully
497+
qualified module name must match, otherwise it specifies a literal string
498+
that the fully qualified module name must be equal to.
498499

499500
The *lineno* field matches the line number, where zero matches all line
500501
numbers and is thus equivalent to an omitted line number.

0 commit comments

Comments
 (0)