Skip to content

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

Merged
encukou merged 23 commits into
python:mainfrom
encukou:expressions-subscription
Feb 4, 2026
Merged

gh-141984: Reword and reorganize Subscription (and Slicing) docs#141985
encukou merged 23 commits into
python:mainfrom
encukou:expressions-subscription

Conversation

@encukou

@encukouencukou commented Nov 26, 2025•
edited
Loading

Copy link
Copy Markdown
Member

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/

encukouand 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-appbedevere-appBot added docs Documentation in the Doc dir skip news labels Nov 26, 2025
@bedevere-appbedevere-appBot mentioned this pull request Nov 26, 2025
Open
StanFromIreland
StanFromIreland reviewed Nov 26, 2025
View reviewed changes
Comment threadDoc/reference/expressions.rst Outdated
Comment threadDoc/reference/expressions.rst Outdated
Comment threadDoc/reference/expressions.rst Outdated
Comment threadDoc/reference/expressions.rst Outdated
Comment threadDoc/reference/expressions.rst Outdated
Comment threadDoc/reference/expressions.rst Outdated
Comment threadDoc/reference/datamodel.rst Outdated
Comment threadDoc/reference/expressions.rst
Comment threadDoc/reference/expressions.rst Outdated
Comment threadDoc/reference/expressions.rst Outdated
@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

@encukouencukou left a comment

Copy link
Copy Markdown
MemberAuthor

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!

Comment threadDoc/reference/expressions.rst Outdated
Comment threadDoc/reference/expressions.rst
Comment threadDoc/reference/expressions.rst Outdated
Comment threadDoc/reference/expressions.rst Outdated
@encukou
encukou marked this pull request as ready for review January 7, 2026 15:19
StanFromIreland
StanFromIreland reviewed Jan 23, 2026
View reviewed changes

@StanFromIrelandStanFromIreland left a comment

Copy link
Copy Markdown
Member

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!

Comment threadDoc/glossary.rst Outdated
Comment threadDoc/reference/expressions.rst Outdated
subscription: `primary` '[' `subscript` ']'
subscript: `slice` | `tuple_slices`
tuple_slices: ','.(`slice` | `starred_expression`)+ [',']
slice: `proper_slice` | `assignment_expression`

@StanFromIrelandStanFromIrelandJan 23, 2026

Copy link
Copy Markdown
Member

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"?

@encukouencukouFeb 4, 2026

Copy link
Copy Markdown
MemberAuthor

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.

Comment threadDoc/reference/datamodel.rst Outdated
StanFromIreland
StanFromIreland reviewed Feb 4, 2026
View reviewed changes
Comment threadDoc/reference/expressions.rst Outdated
StanFromIreland
StanFromIreland reviewed Feb 4, 2026
View reviewed changes
Comment threadDoc/reference/expressions.rst Outdated
StanFromIreland
StanFromIreland reviewed Feb 4, 2026
View reviewed changes

@StanFromIrelandStanFromIreland left a comment

Copy link
Copy Markdown
Member

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.

Comment threadDoc/reference/expressions.rst Outdated
Comment threadDoc/reference/simple_stmts.rst Outdated
@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

@StanFromIrelandStanFromIreland left a comment

Copy link
Copy Markdown
Member

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
@encukouencukou added the needs backport to 3.14 bugs and security fixes label Feb 4, 2026
@encukou
encukou merged commit e423e0c into python:mainFeb 4, 2026
31 checks passed
@github-project-automationgithub-project-automationBot moved this from Todo to Done in Docs PRsFeb 4, 2026
@miss-islington-app

miss-islington-appBot commented Feb 4, 2026

Copy link
Copy Markdown

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

bedevere-appBot commented Feb 4, 2026

Copy link
Copy Markdown

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

@bedevere-appbedevere-appBot 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>
thunder-coding pushed a commit to thunder-coding/cpython that referenced this pull request Feb 15, 2026
@encukou@blaisep
@StanFromIreland@thunder-coding
pythongh-141984: Reword and reorganize Subscription (and Slicing) docs (
24d100e
pythonGH-141985)
Co-authored-by: Blaise Pabon <blaise@gmail.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
ljfp pushed a commit to ljfp/cpython that referenced this pull request Apr 25, 2026
@encukou@blaisep
@StanFromIreland@ljfp
pythongh-141984: Reword and reorganize Subscription (and Slicing) docs (
449ece2
pythonGH-141985)
Co-authored-by: Blaise Pabon <blaise@gmail.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@StanFromIrelandStanFromIrelandStanFromIreland approved these changes
@willingcwillingcAwaiting requested review from willingcwillingc is a code owner
@AA-TurnerAA-TurnerAwaiting requested review from AA-TurnerAA-Turner is a code owner

Assignees

No one assigned

Labels

docsDocumentation in the Doc dirskip news

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@encukou@blaisep@StanFromIreland@nazeerali4325-commits