From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sat, 25 Jul 2020 23:41:20 +0000 (-0700)
Subject: bpo-39868: Add documentation for Assignment Expressions (walrus, PEP 572) (GH-18851)
X-Git-Tag: v3.8.6rc1~71
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=755cb49429581679fc7b12905cb3d3ecf439032c;p=thirdparty%2FPython%2Fcpython.git

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 8036a491c29a..18abce3c510b 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: