[Python-checkins] bpo-39868: Add documentation for Assignment Expressions (walrus, PEP 572) (#18851)

[Shankar Jha]

https://github.com/python/cpython/commit/f117cef25b5ffc4db9fbe373ddb65e14f59f0397
commit: f117cef25b5ffc4db9fbe373ddb65e14f59f0397
branch: master
author: Shankar Jha <shankarj67 at gmail.com>
committer: GitHub <noreply at github.com>
date: 2020-07-25T16:33:48-07:00
summary:

bpo-39868: Add documentation for Assignment Expressions (walrus, PEP 572) (#18851)

files:
M Doc/reference/expressions.rst

diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 8036a491c29ab..18abce3c510bd 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -1650,9 +1650,26 @@ Assignment expressions
 .. productionlist::
    assignment_expression: [`identifier` ":="] `expression`
 
-.. TODO: BPO-39868
+An assignment expression (sometimes also called a "named expression" or
+"walrus") assigns an :token:`expression` to an :token:`identifier`, while also
+returning the value of the :token:`expression`.
 
-See :pep:`572` for more details about assignment expressions.
+One common use case is when handling matched regular expressions:
+
+.. code-block:: python
+
+   if matching := pattern.search(data):
+       do_something(matching)
+
+Or, when processing a file stream in chunks:
+
+.. code-block:: python
+
+   while chunk := file.read(9000):
+       process(chunk)
+
+.. versionadded:: 3.8
+   See :pep:`572` for more details about assignment expressions.
 
 
 .. _if_expr: