Skip to content

gh-161005: simplify subtype notation in numbers.rst - #161006

Merged
nedbat merged 7 commits into
python:mainfrom
saioffl:docs/remove-subtype-notation
Oct 31, 2026
Merged

gh-161005: simplify subtype notation in numbers.rst#161006
nedbat merged 7 commits into
python:mainfrom
saioffl:docs/remove-subtype-notation

Conversation

@saioffl

@saioffl saioffl commented Oct 31, 2026 •
edited by bedevere-app Bot
Loading

Copy link
Copy Markdown
Contributor

This PR addresses #161005.

  • Replaces the unfamiliar <: subtype notation with clearer prose.
  • Preserves the original meaning of the arithmetic operations documentation.

@bedevere-app bedevere-app Bot added awaiting review docs Documentation in the Doc dir skip news labels Oct 31, 2026
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Oct 31, 2026
@saioffl saioffl changed the title Docs: simplify subtype notation in numbers.rst Docs: simplify subtype notation in numbers.rst (GH-161005) Oct 31, 2026
@bedevere-app bedevere-app Bot mentioned this pull request Oct 31, 2026
Closed
@saioffl

saioffl commented Oct 31, 2026

Copy link
Copy Markdown
Contributor Author

Hey, I've replaced the unfamiliar <: subtype notation with clearer prose while preserving the original type relationships and technical meaning. Hope that helps..

@read-the-docs-community

read-the-docs-community Bot commented Oct 31, 2026 •
edited
Loading

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35547775 | 📁 Comparing 9a1da23 against main (1259f16)

  🔍 Preview build  

3 files changed
± library/numbers.html
± library/urllib.error.html
± whatsnew/changelog.html

algmyr
algmyr reviewed Oct 31, 2026
View reviewed changes
Comment thread Doc/library/numbers.rst Outdated
of :class:`Complex` (``a : A <: Complex``), and ``b : B <:
Complex``. I'll consider ``a + b``:
of :class:`Complex`, and ``b`` will be an instance of ``B``,
which is also a subtype of :class:`Complex`. I'll consider ``a + b``:

@algmyr algmyr Oct 31, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Maybe something like this would flow nicely?

Let ``a`` be an instance of ``A`` and ``b`` be an instance of ``B``,
where both ``A`` and ``B`` are subtypes of :class:`Complex`.

@nedbat nedbat Oct 31, 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.

"Let" sounds very mathy (which I guess this section kind of is, but I'd go with:

In this description, a is an instance of A and b is an instance of B, where A and B are both subtypes of Complex.

@picnixz picnixz Oct 31, 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.

Yes, "let" is too heavy even for this description. I would like to remove the personal form of "I" in this document as well since we're anyway editing this part of the docs.

@nedbat nedbat Oct 31, 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.

Good point.

@saioffl saioffl Oct 31, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Thanks for the feedback. I've updated the wording to avoid the mathematical-sounding "Let" and replaced the first-person phrasing in this section, and while preserving the original technical meaning and subtype relationships..

@picnixz picnixz changed the title Docs: simplify subtype notation in numbers.rst (GH-161005) gh-161005: simplify subtype notation in numbers.rst Oct 31, 2026
@hugovk hugovk added needs backport to 3.14 bugs and security fixes needs backport to 3.15 bugs and security fixes labels Oct 31, 2026
@hugovk

hugovk commented Oct 31, 2026

Copy link
Copy Markdown
Member

As we're editing this file, let's also change the "Adding More Numeric ABCs" header to "Adding more numeric ABCs": https://devguide.python.org/documentation/style-guide/#capitalization.

@saioffl

saioffl commented Oct 31, 2026

Copy link
Copy Markdown
Contributor Author

As we're editing this file, let's also change the "Adding More Numeric ABCs" header to "Adding more numeric ABCs": https://devguide.python.org/documentation/style-guide/#capitalization.

Sure, I'll update that heading to match the documentation style guide as well.

@nedbat
nedbat merged commit 683fca8 into python:main Oct 31, 2026
34 checks passed
@miss-islington-app

miss-islington-app Bot commented Oct 31, 2026

Copy link
Copy Markdown

Thanks @saioffl for the PR, and @nedbat for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14, 3.15.
🐍🍒⛏🤖

@github-project-automation github-project-automation Bot moved this from Todo to Done in Docs PRs Oct 31, 2026
@bedevere-app

bedevere-app Bot commented Oct 31, 2026

Copy link
Copy Markdown

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

@bedevere-app bedevere-app Bot removed the needs backport to 3.15 bugs and security fixes label Oct 31, 2026
@bedevere-app

bedevere-app Bot commented Oct 31, 2026

Copy link
Copy Markdown

GH-161024 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 Oct 31, 2026
hugovk pushed a commit that referenced this pull request Oct 31, 2026
@miss-islington @saioffl @nedbat
[3.15] Docs: gh-161005: simplify subtype notation in numbers.rst (G…
f254c47 
…H-161006) (#161023)

Co-authored-by: sai <[email protected]>
Co-authored-by: Ned Batchelder <[email protected]>
hugovk pushed a commit that referenced this pull request Oct 31, 2026
@miss-islington @saioffl @nedbat
[3.14] Docs: gh-161005: simplify subtype notation in numbers.rst (G…
9cd3c61 
…H-161006) (#161024)

Co-authored-by: sai <[email protected]>
Co-authored-by: Ned Batchelder <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@picnixz picnixz picnixz left review comments
@nedbat nedbat nedbat approved these changes
+1 more reviewer
@algmyr algmyr algmyr left review comments
Reviewers whose approvals may not affect merge requirements

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.

5 participants

@saioffl @hugovk @nedbat @picnixz @algmyr