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

(cherry picked from commit f117cef25b5ffc4db9fbe373ddb65e14f59f0397)

Co-authored-by: Shankar Jha <shankarj67@gmail.com>

diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 8036a491c29ab11266f3cf0cf0ab121b96fc0216..18abce3c510bdb84a4c83383fa1da5e6722f74d4 100644 (file)
--- 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: