Hi there,

In ``Doc/faq/design.rst`` there is an explanation of why Python does not have assignment in expressions. This is dated since PEP 572 / Python 3.8.

Online version: https://docs.python.org/3/faq/design.html#why-can-t-i-use-an-assignment-in-an-expression

I suggest updating it to the attached file. `git diff`:

```
diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst
index e2d63a0323..e61284611d 100644
--- a/Doc/faq/design.rst
+++ b/Doc/faq/design.rst
@@ -149,7 +149,15 @@ to tell Python which namespace to use.
 Why can't I use an assignment in an expression?
 -----------------------------------------------
 
-Many people used to C or Perl complain that they want to use this C idiom:
+In Python 3.8 and newer, you can use assignment in an expression with the
+``:=`` operator (as described in :pep:`572`)::
+
+    while line := f.readline():
+        ...  # do something with line
+
+For more than 25 years it was not possible to do assignments in expressions in
+Python. Naturally, many people used to C or Perl would complain that they want
+to use this C idiom:
 
 .. code-block:: c
 
@@ -157,7 +165,7 @@ Many people used to C or Perl complain that they want to use this C idiom:
        // do something with line
    }
 
-where in Python you're forced to write this::
+where in Python you would be forced to write this::
 
    while True:
        line = f.readline()
@@ -165,8 +173,10 @@ where in Python you're forced to write this::
            break
        ...  # do something with line
 
-The reason for not allowing assignment in Python expressions is a common,
-hard-to-find bug in those other languages, caused by this construct:
+The reason different operators are used for assignment and assignment in
+expressions (``=`` and ``:=``, respectively), and why Python didn't allow
+assignment in expressions for a long time is a common, hard-to-find bug in
+those other languages, caused by this construct:
 
 .. code-block:: c
 
@@ -180,11 +190,6 @@ hard-to-find bug in those other languages, caused by this construct:
 The error is a simple typo: ``x = 0``, which assigns 0 to the variable ``x``,
 was written while the comparison ``x == 0`` is certainly what was intended.
 
-Many alternatives have been proposed.  Most are hacks that save some typing but
-use arbitrary or cryptic syntax or keywords, and fail the simple criterion for
-language change proposals: it should intuitively suggest the proper meaning to a
-human reader who has not yet been introduced to the construct.
-
 An interesting phenomenon is that most experienced Python programmers recognize
 the ``while True`` idiom and don't seem to be missing the assignment in
 expression construct much; it's only newcomers who express a strong desire to

```

This can be changed only after implementing PEP 572.

> I believe a spot where assignment expressions are explicitly mentioned as not being included in the language, which is no longer the case

Emily, I guess you were referring to this issue in https://bugs.python.org/issue35224#msg334331 . Now that PEP 572 implementation is merged this can be updated.

Thanks

Ah sorry I think this could be a duplicate of issue34237 where you have added an update.

This is updated with 6357c95716d89ac1f80587fbc4133df8d2e8396c . Closing this as fixed. Feel free to reopen if needed. Thanks.

stage: resolved