gh-141984: Reword the Generator expressions section by encukou · Pull Request #150518 · python/cpython

encukou · 2026-05-27T15:47:03Z

Continuing after #148622, this rewords the Generator Expressions with increasingly complex examples, ending with the formal grammar (which is trivial in this case).

Issue: Reword the Expressions chapter of the docs #141984

Co-authored-by: Blaise Pabon <blaise@gmail.com>

read-the-docs-community · 2026-05-27T16:05:32Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #32974179 | 📁 Comparing d8bf895 against main (d8ff4f8)

🔍 Preview build

88 files changed · + 1 added · ± 87 modified

+Added

howto/abi3t-migration.html

±Modified

StanFromIreland · 2026-05-31T10:28:46Z

+The enclosing parentheses can be omitted in calls with only one
+positional argument.


Suggested change
The enclosing parentheses can be omitted in calls with only one
positional argument.
The enclosing parentheses can be omitted in calls when it is
the only argument.
Proof by counterexample: sum(x ** 2 for x in range(10), start=3) has only one pos-arg.

The single argument must be positional. For example, sum(iterable=x ** 2 for x in range(10)) is invalid syntax.
Would this work?
Suggested change
The enclosing parentheses can be omitted in calls with only one
positional argument.
The enclosing parentheses can be omitted in calls when the generator
expression is the only positional argument and there are no keyword
arguments.

That's fine.

StanFromIreland · 2026-05-31T10:35:52Z

+ >>> list(iterator)
+ [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
+
+Thus, the example above is roughly equivalent to defining and calling


To make it less rough, we could pass an iterator?

I'm not sure what you mean; where should we pass it?

I meant something like:
defmake_generator_of_squares(iterator): forxiniterator: yieldx**2make_generator_of_squares(iter(range(10)))
That way, it's also evaluated immediately like in generator expressions.

StanFromIreland · 2026-05-31T10:36:59Z

-:meth:`~generator.__next__` method is called for the generator object (in the same
-fashion as normal generators). However, the iterable expression in the
-leftmost :keyword:`!for` clause is immediately evaluated, and the
-:term:`iterator` is immediately created for that iterable, so that an error


I think we should keep this.

It's moved around and reworded, see "The iterable expression in the leftmost :keyword:!for clause is evaluated immediately" in the new text.
For "Subsequent for clauses" the new wording is "All other expressions" -- it's for, if but also the "result" expression.

Sorry for my unclear comment, I was referring specifically to keeping the sentence on L972: "iterator is immediately created for that iterable"
(Which in turn made me think of the comment above :-)

Co-authored-by: Stan Ulbrych <stan@python.org>

StanFromIreland

"".join((c for c in ['L', 'G', 'T', 'M']))

miss-islington-app · 2026-06-10T14:45:48Z

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

miss-islington-app · 2026-06-10T14:45:51Z

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

miss-islington-app · 2026-06-10T14:45:52Z

Sorry, @encukou, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 7bbb9607a2e7d1f8a7de11ce02f0a2402d6e7262 3.14

bedevere-app · 2026-06-10T14:46:13Z

GH-151261 is a backport of this pull request to the 3.15 branch.

GH-151261) (cherry picked from commit 7bbb960) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: Stan Ulbrych <stan@python.org>

encukou · 2026-06-10T16:05:59Z

Like with the earlier PR, I'll concentrate on the next section rather than backport to 3.14.

bedevere-app · 2026-06-10T16:23:27Z

GH-151267 is a backport of this pull request to the 3.14 branch.

StanFromIreland · 2026-06-10T16:25:23Z

Like with the earlier PR, I'll concentrate on the next section rather than backport to 3.14.

Took less than a minute so I took care of it for 'ya.

GH-151267) (cherry picked from commit 7bbb960) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: Stan Ulbrych <stan@python.org>

…50518) Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: Stan Ulbrych <stan@python.org>

pythongh-141984: Reword the Generator expressions section
0655b63
Co-authored-by: Blaise Pabon <blaise@gmail.com>

encukou requested review from AA-Turner and willingc as code owners May 27, 2026 15:47

bedevere-appBot added docs Documentation in the Doc dir skip news labels May 27, 2026

github-project-automationBot added this to Docs PRs May 27, 2026

github-project-automationBot moved this to Todo in Docs PRs May 27, 2026

bedevere-appBot mentioned this pull request May 27, 2026
Reword the Expressions chapter of the docs #141984
Open

bedevere-appBot added the awaiting core review label May 27, 2026

StanFromIreland reviewed May 31, 2026
View reviewed changes

encukouand others added 4 commits June 3, 2026 16:15

Apply suggestions from code review
d8bf895
Co-authored-by: Stan Ulbrych <stan@python.org>

Merge in the main branch
1ecb685

More precise wording for only one positional argument
e475a42

Address review
33bb301

StanFromIreland approved these changes Jun 10, 2026
View reviewed changes

bedevere-appBot added awaiting merge and removed awaiting core review labels Jun 10, 2026

encukou merged commit 7bbb960 into python:mainJun 10, 2026
34 checks passed

encukou deleted the expressions-genexp-sq branch June 10, 2026 14:45

github-project-automationBot moved this from Todo to Done in Docs PRs Jun 10, 2026

bedevere-appBot removed the awaiting merge label Jun 10, 2026

encukou added needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Jun 10, 2026

miss-islington-appBot assigned encukou Jun 10, 2026

bedevere-appBot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jun 10, 2026

encukou removed the needs backport to 3.14 bugs and security fixes label Jun 10, 2026

philthompson10 pushed a commit to philthompson10/cpython that referenced this pull request Jun 17, 2026
pythongh-141984: Reword the Generator expressions section (pythonGH-1…
1a373fa
…50518) Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: Stan Ulbrych <stan@python.org>

		The enclosing parentheses can be omitted in calls with only one
		positional argument.

-The enclosing parentheses can be omitted in calls with only one
-positional argument.
+The enclosing parentheses can be omitted in calls when the generator
+expression is the only positional argument and there are no keyword
+arguments.

Uh oh!

Uh oh!

Conversation

encukou commented May 27, 2026• edited by bedevere-app BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-communityBot commented May 27, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-appBot commented Jun 10, 2026

Uh oh!

miss-islington-appBot commented Jun 10, 2026

Uh oh!

miss-islington-appBot commented Jun 10, 2026

Uh oh!

bedevere-appBot commented Jun 10, 2026

Uh oh!

encukou commented Jun 10, 2026

Uh oh!

bedevere-appBot commented Jun 10, 2026

Uh oh!

StanFromIreland commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

encukou commented May 27, 2026•
edited by bedevere-app Bot
Loading

read-the-docs-communityBot commented May 27, 2026•
edited
Loading