[Python-checkins] gh-86482: Document assignment expression need for ()s (#23291)

[JelleZijlstra]

https://github.com/python/cpython/commit/2b5f1360ead9aa72ae00de59edfd6c229d13933f
commit: 2b5f1360ead9aa72ae00de59edfd6c229d13933f
branch: main
author: Terry Jan Reedy <tjreedy at udel.edu>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2022-10-06T12:24:17-07:00
summary:

gh-86482: Document assignment expression need for ()s (#23291)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra at gmail.com>

files:
A Misc/NEWS.d/next/Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst
M Doc/reference/expressions.rst

diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index a6ca55dafe53..a661e03b1734 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -1766,6 +1766,13 @@ Or, when processing a file stream in chunks:
    while chunk := file.read(9000):
        process(chunk)
 
+Assignment expressions must be surrounded by parentheses when used
+as sub-expressions in slicing, conditional, lambda,
+keyword-argument, and comprehension-if expressions
+and in ``assert`` and ``with`` statements.
+In all other places where they can be used, parentheses are not required,
+including in ``if`` and ``while`` statements.
+
 .. versionadded:: 3.8
    See :pep:`572` for more details about assignment expressions.
 
diff --git a/Misc/NEWS.d/next/Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst b/Misc/NEWS.d/next/Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst
new file mode 100644
index 000000000000..ea997800bf07
--- /dev/null
+++ b/Misc/NEWS.d/next/Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst	
@@ -0,0 +1 @@
+Document some places where an assignment expression needs parentheses.