bpo-39868: Add the documentation for Assignment Expressions (PEP 572). #18851

shankarj67 · 2020-03-08T13:28:28Z

https://bugs.python.org/issue39868

https://bugs.python.org/issue39702

brandtbucher · 2020-03-08T17:41:09Z

Thanks for your time @shankarj67, and welcome to CPython! 😎

I'll review this in a bit. Adding "skip news" since the one for #18793 is fine here as well.

Also, can you change the PR title to reference "bpo-39868" instead of "bpo-39702"?

brandtbucher

This is good, thanks!

It's a bit longer than I think it needs to be, though (see similar sections, which are quite brief and have no subheadings). I also don't think we need examples of code without assignment expressions, since we're not trying to sell the syntax (like the PEP), just explaining it!

Before we get to grammar, etc., I've identified three chunks that can probably be removed, for the reasons above.

brandtbucher · 2020-03-08T17:46:09Z

Doc/reference/expressions.rst

+
+**Examples**
+
+*The following examples demonstrate the use case of an assignment expressions.*
+


Suggested change

**Examples**

*The following examples demonstrate the use case of an assignment expressions.*

brandtbucher · 2020-03-08T17:46:43Z

Doc/reference/expressions.rst

+
+**Current scenario**
+
+.. code-block:: python
+
+   matching = patern.search(data)
+   if matching:
+       do_something(matching)
+
+Notice that a matching variable is being called two times in the code
+that may be replaced using assignment expression in one line.
+
+**Using assignment expression**


Suggested change

**Current scenario**

.. code-block:: python

matching = patern.search(data)

if matching:

do_something(matching)

Notice that a matching variable is being called two times in the code

that may be replaced using assignment expression in one line.

**Using assignment expression**

brandtbucher · 2020-03-08T17:47:07Z

Doc/reference/expressions.rst

+
+**Current scenario**
+
+.. code-block:: python
+
+   chunk = file.read(9000)
+   while chunk:
+       process(chunk)
+       chunk = file.read(9000)
+
+**Using assignment expression**


Suggested change

**Current scenario**

.. code-block:: python

chunk = file.read(9000)

while chunk:

process(chunk)

chunk = file.read(9000)

**Using assignment expression**

I have added the commit.

brandtbucher

I've added some suggestions (mostly grammar and style):

brandtbucher · 2020-03-08T22:23:31Z

Doc/reference/expressions.rst

+
+   while chunk := file.read(9000):
+       process(chunk)
+

 See :pep:`572` for more details about assignment expressions.



We typically add versionadded directives for new features:

Suggested change

.. versionadded:: 3.8

brandtbucher · 2020-03-08T22:24:16Z

Doc/reference/expressions.rst

+Another popular use case is when processing the streams in a
+chunk from the file.


I was a bit confused by the original wording... something like this is clearer to me:

Suggested change

Another popular use case is when processing the streams in a

chunk from the file.

Or, when processing a file stream in chunks:

brandtbucher · 2020-03-08T22:24:31Z

Doc/reference/expressions.rst

+
+.. code-block:: python
+
+   if (matching := pattern.search(data)):


No need for parentheses here:

Suggested change

if (matching := pattern.search(data)):

if matching := pattern.search(data):

brandtbucher · 2020-03-08T22:25:13Z

Doc/reference/expressions.rst

+Here the variable **name** holds the assigned value of a given **expression**.
+
+
+One common use case is when handling the matched data in regular expression


Grammar:

Suggested change

One common use case is when handling the matched data in regular expression

One common use case is when handling matched regular expressions:

brandtbucher · 2020-03-10T15:45:47Z

Doc/reference/expressions.rst

+Assignment expression is the new expression introduced in the Python3.8
+or later (sometimes also called as "named expression" or "walrus operator"),
+which aims to reduce the number of lines of code by allowing the
+assignment and return of value in the same expression. This makes codebase
+more readable and maintainable.
+
+The expression ``name := expr`` where **expr** is any valid Python expression
+other than an unparenthesize tuple and the **name** is an identifier.
+Here the variable **name** holds the assigned value of a given **expression**.
+


I personally don't think this needs to include the history or motivation... just the behavior. We can reuse the above grammar for the explanation, too!

Suggested change

Assignment expression is the new expression introduced in the Python3.8

or later (sometimes also called as "named expression" or "walrus operator"),

which aims to reduce the number of lines of code by allowing the

assignment and return of value in the same expression. This makes codebase

more readable and maintainable.

The expression ``name := expr`` where **expr** is any valid Python expression

other than an unparenthesize tuple and the **name** is an identifier.

Here the variable **name** holds the assigned value of a given **expression**.

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`.

shankarj67 · 2020-03-10T17:05:03Z

Thank you for the suggestion. I have added the new commit.

brandtbucher · 2020-03-10T17:31:57Z

Doc/reference/expressions.rst


-See :pep:`572` for more details about assignment expressions.
+One common use case is when handling matched regular expression:


Thanks! One more tiny fix:

Suggested change

One common use case is when handling matched regular expression:

One common use case is when handling matched regular expressions:

brandtbucher · 2020-07-17T17:00:29Z

Closing and reopening to trigger CI.

gvanrossum

This looks fine to me. Is it waiting for anything?

brandtbucher · 2020-07-25T23:15:13Z

Just a merge! ;)

miss-islington · 2020-07-25T23:33:51Z

Thanks @shankarj67 for the PR, and @gvanrossum for merging it 🌮🎉.. I'm working now to backport this PR to: 3.8, 3.9.
🐍🍒⛏🤖

…572) (pythonGH-18851) (cherry picked from commit f117cef) Co-authored-by: Shankar Jha <[email protected]>

bedevere-bot · 2020-07-25T23:34:13Z

GH-21622 is a backport of this pull request to the 3.9 branch.

bedevere-bot · 2020-07-25T23:34:21Z

GH-21623 is a backport of this pull request to the 3.8 branch.

…572) (pythonGH-18851) (cherry picked from commit f117cef) Co-authored-by: Shankar Jha <[email protected]>

…572) (GH-18851) (cherry picked from commit f117cef) Co-authored-by: Shankar Jha <[email protected]>

…572) (python#18851)

bpo-39702: Add the documentation for Assignment Expressions (PEP 572).

57d7454

the-knights-who-say-ni added the CLA signed label Mar 8, 2020

bedevere-bot added docs Documentation in the Doc dir awaiting review labels Mar 8, 2020

brandtbucher added the skip news label Mar 8, 2020

shankarj67 changed the title ~~bpo-39702: Add the documentation for Assignment Expressions (PEP 572).~~ bpo-39868: Add the documentation for Assignment Expressions (PEP 572). Mar 8, 2020

brandtbucher requested changes Mar 8, 2020

View reviewed changes

bedevere-bot added awaiting core review and removed awaiting review labels Mar 8, 2020

bpo-39868: Update the content.

987acca

brandtbucher requested changes Mar 10, 2020

View reviewed changes

bpo-39868: Update the style and grammar.

80e3f7d

brandtbucher reviewed Mar 10, 2020

View reviewed changes

brandtbucher added the needs backport to 3.8 label Mar 10, 2020

bpo-39868: Update the spelling.

ada2b88

brandtbucher approved these changes Mar 10, 2020

View reviewed changes

brandtbucher closed this Jul 17, 2020

brandtbucher reopened this Jul 17, 2020

gvanrossum approved these changes Jul 25, 2020

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting core review labels Jul 25, 2020

gvanrossum added the needs backport to 3.9 only security fixes label Jul 25, 2020

gvanrossum merged commit f117cef into python:master Jul 25, 2020

This comment has been minimized.

Sign in to view

bedevere-bot removed the awaiting merge label Jul 25, 2020

bedevere-bot removed the needs backport to 3.9 only security fixes label Jul 25, 2020

bedevere-bot removed the needs backport to 3.8 label Jul 25, 2020

miss-islington added a commit that referenced this pull request Jul 25, 2020

bpo-39868: Add documentation for Assignment Expressions (walrus, PEP …

616734b

…572) (GH-18851) (cherry picked from commit f117cef) Co-authored-by: Shankar Jha <[email protected]>

miss-islington added a commit that referenced this pull request Jul 25, 2020

bpo-39868: Add documentation for Assignment Expressions (walrus, PEP …

755cb49

…572) (GH-18851) (cherry picked from commit f117cef) Co-authored-by: Shankar Jha <[email protected]>

shihai1991 pushed a commit to shihai1991/cpython that referenced this pull request Aug 4, 2020

bpo-39868: Add documentation for Assignment Expressions (walrus, PEP …

004e82b

…572) (python#18851)

shihai1991 pushed a commit to shihai1991/cpython that referenced this pull request Aug 20, 2020

bpo-39868: Add documentation for Assignment Expressions (walrus, PEP …

2161d14

…572) (python#18851)

xzy3 pushed a commit to xzy3/cpython that referenced this pull request Oct 18, 2020

bpo-39868: Add documentation for Assignment Expressions (walrus, PEP …

5ec34f6

…572) (python#18851)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

bpo-39868: Add the documentation for Assignment Expressions (PEP 572). #18851

bpo-39868: Add the documentation for Assignment Expressions (PEP 572). #18851

shankarj67 commented Mar 8, 2020 •

edited by bedevere-bot

Loading

brandtbucher commented Mar 8, 2020 •

edited by bedevere-bot

Loading

brandtbucher left a comment •

edited

Loading

brandtbucher Mar 8, 2020

brandtbucher Mar 8, 2020

brandtbucher Mar 8, 2020

shankarj67 Mar 8, 2020

brandtbucher left a comment

brandtbucher Mar 8, 2020

brandtbucher Mar 8, 2020

brandtbucher Mar 8, 2020

brandtbucher Mar 8, 2020

brandtbucher Mar 10, 2020

shankarj67 commented Mar 10, 2020

brandtbucher Mar 10, 2020

shankarj67 Mar 10, 2020

brandtbucher commented Jul 17, 2020

gvanrossum left a comment

brandtbucher commented Jul 25, 2020

This comment has been minimized.

miss-islington commented Jul 25, 2020

bedevere-bot commented Jul 25, 2020

bedevere-bot commented Jul 25, 2020


		Examples

		The following examples demonstrate the use case of an assignment expressions.

		Another popular use case is when processing the streams in a
		chunk from the file.

	Another popular use case is when processing the streams in a
	chunk from the file.
	Or, when processing a file stream in chunks:


		.. code-block:: python

		if (matching := pattern.search(data)):

	if (matching := pattern.search(data)):
	if matching := pattern.search(data):

		Here the variable name holds the assigned value of a given expression.


		One common use case is when handling the matched data in regular expression

	One common use case is when handling the matched data in regular expression
	One common use case is when handling matched regular expressions:


		See :pep:`572` for more details about assignment expressions.
		One common use case is when handling matched regular expression:

bpo-39868: Add the documentation for Assignment Expressions (PEP 572). #18851

bpo-39868: Add the documentation for Assignment Expressions (PEP 572). #18851

Conversation

shankarj67 commented Mar 8, 2020 • edited by bedevere-bot Loading

brandtbucher commented Mar 8, 2020 • edited by bedevere-bot Loading

brandtbucher left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brandtbucher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shankarj67 commented Mar 10, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brandtbucher commented Jul 17, 2020

gvanrossum left a comment

Choose a reason for hiding this comment

brandtbucher commented Jul 25, 2020

This comment has been minimized.

miss-islington commented Jul 25, 2020

bedevere-bot commented Jul 25, 2020

bedevere-bot commented Jul 25, 2020

shankarj67 commented Mar 8, 2020 •

edited by bedevere-bot

Loading

brandtbucher commented Mar 8, 2020 •

edited by bedevere-bot

Loading

brandtbucher left a comment •

edited

Loading