Skip to content

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

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

Merged
nedbat merged 7 commits into from
Oct 31, 2026
+11 −9
Merged

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

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
d9bb67b
Docs: simplify subtype notation in numbers.rst
saioffl Oct 31, 2026
a8fb47d
Docs: preserve operand subtype relationship
saioffl Oct 31, 2026
efb0ca2
Merge branch 'main' into docs/remove-subtype-notation
nedbat Oct 31, 2026
f20281b
Docs: improve subtype explanation in numbers.rst
saioffl Oct 31, 2026
446ab07
Docs: address review feedback
saioffl Oct 31, 2026
cc02c00
Docs: address review feedback
saioffl Oct 31, 2026
9a1da23
Fix numeric ABCs heading capitalization
saioffl Oct 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions Doc/library/numbers.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ them to the same values. This may be subtle if there are two different
extensions of the real numbers. See also :ref:`numeric-hash`.


Adding More Numeric ABCs
Adding more numeric ABCs
~~~~~~~~~~~~~~~~~~~~~~~~

There are, of course, more possible ABCs for numbers, and this would
Expand Down Expand Up @@ -143,11 +143,12 @@ defined as::


There are 5 different cases for a mixed-type operation on subclasses
of :class:`Complex`. I'll refer to all of the above code that doesn't
refer to ``MyIntegral`` and ``OtherTypeIKnowAbout`` as
"boilerplate". ``a`` will be an instance of ``A``, which is a subtype
of :class:`Complex` (``a : A <: Complex``), and ``b : B <:
Complex``. I'll consider ``a + b``:
of :class:`Complex`. All of the above code that doesn't refer to
``MyIntegral`` and ``OtherTypeIKnowAbout`` is referred to as "boilerplate".

In this description, ``a`` is an instance of ``A`` and ``b`` is an
instance of ``B``, where ``A`` and ``B`` are both subtypes of :class:`Complex`.
Consider ``a + b``:

1. If ``A`` defines an :meth:`~object.__add__` which accepts ``b``, all is
well.
Expand All @@ -162,13 +163,14 @@ Complex``. I'll consider ``a + b``:
4. If it falls back to the boilerplate, there are no more possible
methods to try, so this is where the default implementation
should live.
5. If ``B <: A``, Python tries ``B.__radd__`` before
5. If ``B`` is a subtype of ``A``, Python tries ``B.__radd__`` before
``A.__add__``. This is ok, because it was implemented with
knowledge of ``A``, so it can handle those instances before
delegating to :class:`Complex`.

If ``A <: Complex`` and ``B <: Real`` without sharing any other knowledge,
then the appropriate shared operation is the one involving the built
If ``A`` is a subtype of :class:`Complex` and ``B`` is a subtype of
:class:`Real` without sharing any other knowledge, then the appropriate
shared operation is the one involving the built
in :class:`complex`, and both :meth:`~object.__radd__` s land there, so ``a+b
== b+a``.

Expand Down
Loading