Skip to content

gh-141984: Reword and reorganize Subscription (and Slicing) docs #141985

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
encukou merged 23 commits into from
Feb 4, 2026
Merged

gh-141984: Reword and reorganize Subscription (and Slicing) docs #141985

encukou merged 23 commits into from
Feb 4, 2026
+283 −156

Conversation

@encukou
Copy link
Member

@encukou encukou commented Nov 26, 2025 •
edited
Loading

This merges the Subscriptions and Slicings sections in the language reference. From the parser's point of view, slicing is a special case of subscription, and it makes sense to document it that way too.

The PR also touches Data model documentation: I've tried to move details of the runtime behaviour there, and to de-duplicate (and cross-link) as needed.
Similar for the slice attribute docs.

Todo:

  • Add a glossary entry for subscript -- the term this uses consistently for the key/index/whatever in the square brackets.

📚 Documentation preview 📚: https://cpython-previews--141985.org.readthedocs.build/

encukou and others added 7 commits September 10, 2025 17:59
@encukou @blaisep
Start on Subscriptions and slicing
7d892d3 
Co-authored-by: Blaise Pabon <blaise@gmail.com>
@encukou @blaisep
Continue Subscriptions and slicing
bb70707 
Co-authored-by: Blaise Pabon <blaise@gmail.com>
@encukou @StanFromIreland
Reorganize, add sections
0cd76e6 
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
@encukou
Continue rewording
c8d0f9e
@encukou
Merge in the main branch
d3e1c13
@encukou @blaisep
More work here
e755b5d 
Co-authored-by: Blaise Pabon <blaise@gmail.com>
@encukou
A correction and a simplification
0aa0256
@bedevere-app bedevere-app bot added docs Documentation in the Doc dir skip news labels Nov 26, 2025
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Nov 26, 2025
@bedevere-app bedevere-app bot mentioned this pull request Nov 26, 2025
Open
StanFromIreland
StanFromIreland reviewed Nov 26, 2025
View reviewed changes
@encukou @StanFromIreland
Apply suggestions from code review
ec68594 
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
encukou
encukou commented Dec 3, 2025
View reviewed changes
Copy link
Member Author

@encukou encukou left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for going through this!

@encukou encukou marked this pull request as ready for review January 7, 2026 15:19
StanFromIreland
StanFromIreland reviewed Jan 23, 2026
View reviewed changes
Copy link
Member

@StanFromIreland StanFromIreland left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a few little things, overall looks very good!

Doc/reference/expressions.rst Outdated
subscription: `primary` '[' `subscript` ']'
subscript: `slice` | `tuple_slices`
tuple_slices: ','.(`slice` | `starred_expression`)+ [',']
slice: `proper_slice` | `assignment_expression`
Copy link
Member

@StanFromIreland StanFromIreland Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By this grammar, if one does something[0], 0 is an int and is a slice, but that contradicts with your glossary entry, that states it must be a "an object of type slice"?

Copy link
Member Author

@encukou encukou Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good point. I've considered the terms and the rules separate namespaces, but i agree it can be confusing.

StanFromIreland
StanFromIreland reviewed Feb 4, 2026
View reviewed changes
StanFromIreland
StanFromIreland reviewed Feb 4, 2026
View reviewed changes
StanFromIreland
StanFromIreland reviewed Feb 4, 2026
View reviewed changes
Copy link
Member

@StanFromIreland StanFromIreland left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I read through most during your unicode shenanigans ;-), a few small things but otherwise LGTM.

@encukou @StanFromIreland
Apply suggestions from code review
bbac1fc 
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
StanFromIreland
StanFromIreland approved these changes Feb 4, 2026
View reviewed changes
Copy link
Member

@StanFromIreland StanFromIreland left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With that, LGMT

@encukou encukou enabled auto-merge (squash) February 4, 2026 16:02
@encukou encukou added the needs backport to 3.14 bugs and security fixes label Feb 4, 2026
@encukou encukou merged commit e423e0c into python:main Feb 4, 2026
31 checks passed
@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs Feb 4, 2026
@miss-islington-app
Copy link

miss-islington-app bot commented Feb 4, 2026

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Feb 4, 2026
@encukou @blaisep
@StanFromIreland @miss-islington
pythongh-141984: Reword and reorganize Subscription (and Slicing) docs (
0089958 
pythonGH-141985)

(cherry picked from commit e423e0c)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Blaise Pabon <blaise@gmail.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
@bedevere-app
Copy link

bedevere-app bot commented Feb 4, 2026

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

@bedevere-app bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Feb 4, 2026
encukou added a commit that referenced this pull request Feb 5, 2026
@miss-islington @encukou
@blaisep @StanFromIreland
[3.14] gh-141984: Reword and reorganize Subscription (and Slicing) do…
f27896c 
…cs (GH-141985) (GH-144476)

(cherry picked from commit e423e0c)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Blaise Pabon <blaise@gmail.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
encukou added a commit to encukou/cpython that referenced this pull request Feb 5, 2026
@encukou @blaisep @StanFromIreland
pythongh-141984: Reword and reorganize Subscription (and Slicing) docs (
0b91f57 
pythonGH-141985)

Co-authored-by: Blaise Pabon <blaise@gmail.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@StanFromIreland StanFromIreland StanFromIreland approved these changes

@willingc willingc Awaiting requested review from willingc willingc is a code owner

@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip news

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@encukou @blaisep @StanFromIreland