[Python-checkins] bpo-44025: Clarify when '_' is a keyword. (GH-25873)

[miss-islington]

https://github.com/python/cpython/commit/ae4f8574993c85f9dc6fe60e6a25d65f688705e6
commit: ae4f8574993c85f9dc6fe60e6a25d65f688705e6
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2021-05-04T04:36:50-07:00
summary:

bpo-44025: Clarify when '_' is a keyword. (GH-25873)


In match statements, in case patterns and nowhere else.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra at gmail.com>
(cherry picked from commit 3b200b2aa648fcc8a2673871807c1463afe00195)

Co-authored-by: Terry Jan Reedy <tjreedy at udel.edu>

files:
A Misc/NEWS.d/next/Documentation/2021-05-03-22-08-08.bpo-44025.gcB7iP.rst
M Doc/reference/compound_stmts.rst

diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index 96bd9b028d5044..77400a8d8504f3 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -797,7 +797,7 @@ Syntax:
    capture_pattern: !'_' NAME
 
 A single underscore ``_`` is not a capture pattern (this is what ``!'_'``
-expresses). And is instead treated as a :token:`wildcard_pattern`.
+expresses). It is instead treated as a :token:`wildcard_pattern`.
 
 In a given pattern, a given name can only be bound once.  E.g.
 ``case x, x: ...`` is invalid while ``case [x] | x: ...`` is allowed.
@@ -820,7 +820,9 @@ and binds no name.  Syntax:
 .. productionlist:: python-grammar
    wildcard_pattern: '_'
 
-``_`` is a :ref:`soft keyword <soft-keywords>`.
+``_`` is a :ref:`soft keyword <soft-keywords>` within any pattern,
+but only within patterns.  It is an identifier, as usual, even within
+``match`` headers, ``guards``, and ``case`` blocks.
 
 In simple terms, ``_`` will always succeed.
 
diff --git a/Misc/NEWS.d/next/Documentation/2021-05-03-22-08-08.bpo-44025.gcB7iP.rst b/Misc/NEWS.d/next/Documentation/2021-05-03-22-08-08.bpo-44025.gcB7iP.rst
new file mode 100644
index 00000000000000..1432236a32f63f
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2021-05-03-22-08-08.bpo-44025.gcB7iP.rst
@@ -0,0 +1 @@
+Clarify when '_' in match statements is a keyword, and when not.