bpo-39868: Add documentation for Assignment Expressions (walrus, PEP 572) (#18851)
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 8036a49..18abce3 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -1650,9 +1650,26 @@
.. 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: