[Python-checkins] (no subject)

[Stéphane Wirtel]

To: python-checkins at python.org
Subject: bpo-35224: Additional documentation for Assignment Expressions
 (GH-15935) (GH-15967)
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0

https://github.com/python/cpython/commit/be2aa58fdc29cf13aabff6d6712e7853e94e=
88f8
commit: be2aa58fdc29cf13aabff6d6712e7853e94e88f8
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.co=
m>
committer: St=C3=A9phane Wirtel <stephane at wirtel.be>
date: 2019-09-11T17:12:09+02:00
summary:

bpo-35224: Additional documentation for Assignment Expressions (GH-15935) (GH=
-15967)

Add or update assignment expression documentation for:
- FAQ - Design
- Reference - Expressions
- Reference - Lexical Analysis

https://bugs.python.org/issue35224

Automerge-Triggered-By: @matrixise
(cherry picked from commit 6357c95716d89ac1f80587fbc4133df8d2e8396c)

Co-authored-by: Emily Morehouse <emily at cuttlesoft.com>

files:
M Doc/faq/design.rst
M Doc/reference/expressions.rst
M Doc/reference/lexical_analysis.rst
M Doc/whatsnew/3.8.rst

diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst
index e2d63a0323da..81c0f474ac16 100644
--- a/Doc/faq/design.rst
+++ b/Doc/faq/design.rst
@@ -149,66 +149,15 @@ to tell Python which namespace to use.
 Why can't I use an assignment in an expression?
 -----------------------------------------------
=20
-Many people used to C or Perl complain that they want to use this C idiom:
+Starting in Python 3.8, you can!
=20
-.. code-block:: c
+Assignment expressions using the walrus operator `:=3D` assign a variable in=
 an
+expression::
=20
-   while (line =3D readline(f)) {
-       // do something with line
-   }
-
-where in Python you're forced to write this::
-
-   while True:
-       line =3D f.readline()
-       if not line:
-           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:
-
-.. code-block:: c
-
-    if (x =3D 0) {
-        // error handling
-    }
-    else {
-        // code that only works for nonzero x
-    }
-
-The error is a simple typo: ``x =3D 0``, which assigns 0 to the variable ``x=
``,
-was written while the comparison ``x =3D=3D 0`` is certainly what was intend=
ed.
-
-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 f=
or
-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 recogn=
ize
-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
-add this to the language.
-
-There's an alternative way of spelling this that seems attractive but is
-generally less robust than the "while True" solution::
-
-   line =3D f.readline()
-   while line:
-       ...  # do something with line...
-       line =3D f.readline()
-
-The problem with this is that if you change your mind about exactly how you =
get
-the next line (e.g. you want to change it into ``sys.stdin.readline()``) you
-have to remember to change two places in your program -- the second occurren=
ce
-is hidden at the bottom of the loop.
-
-The best approach is to use iterators, making it possible to loop through
-objects using the ``for`` statement.  For example, :term:`file objects
-<file object>` support the iterator protocol, so you can write simply::
+   while chunk :=3D fp.read(200):
+      print(chunk)
=20
-   for line in f:
-       ...  # do something with line...
+See :pep:`572` for more information.
=20
=20
=20
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 73a2f271ca54..d9db33a78568 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -1784,6 +1784,8 @@ precedence and have a left-to-right chaining feature as=
 described in the
 +-----------------------------------------------+---------------------------=
----------+
 | Operator                                      | Description               =
          |
 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D+
+| ``:=3D``                                        | Assignment expression   =
            |
++-----------------------------------------------+---------------------------=
----------+
 | :keyword:`lambda`                             | Lambda expression         =
          |
 +-----------------------------------------------+---------------------------=
----------+
 | :keyword:`if <if_expr>` -- :keyword:`!else`   | Conditional expression    =
          |
diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analy=
sis.rst
index 7e1e17edb2d8..c0e13b53698e 100644
--- a/Doc/reference/lexical_analysis.rst
+++ b/Doc/reference/lexical_analysis.rst
@@ -887,7 +887,7 @@ The following tokens are operators:
=20
=20
    +       -       *       **      /       //      %      @
-   <<      >>      &       |       ^       ~
+   <<      >>      &       |       ^       ~       :=3D
    <       >       <=3D      >=3D      =3D=3D      !=3D
=20
=20
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index aefe9b53746f..c2455f487b14 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -122,8 +122,6 @@ See :pep:`572` for a full description.
=20
 (Contributed by Emily Morehouse in :issue:`35224`.)
=20
-.. TODO: Emily will sprint on docs at PyCon US 2019.
-
=20
 Positional-only parameters
 --------------------------