gh-158911 Docs: Correct and clarify NotImplementedError usage guidelines by clauspruefer · Pull Request #158912 · python/cpython

clauspruefer · 2026-10-06T13:54:01Z

Reference (Details)

Implementation

Update the /Doc/builtins/exceptions.rst documentation for NotImplementedError to specify that it should be raised in non-abstract methods of user-defined base classes rather than abstract ones.

Additionally, add a caution note explaining that adding NotImplementedError inside methods decorated with abc.abstractmethod is redundant, as the ABC metaclass enforcement prevents instantiation without concrete child implementations, rendering the base method body uncalled.

Issue: Wrong NotImplementedError documentation regarding abstract base classes #158911

Update the documentation for `NotImplementedError` to specify that it should be raised in non-abstract methods of user-defined base classes rather than abstract ones. Additionally, add a caution note explaining that adding `NotImplementedError` inside methods decorated with `abc.abstractmethod` is redundant, as the ABC metaclass enforcement prevents instantiation without concrete child implementations, rendering the base method body uncalled.

python-cla-bot · 2026-10-06T13:54:43Z

All commit authors signed the Contributor License Agreement.

Copilot

Copilot review overview

🟡 Changes recommended

The caution incorrectly claims abstract method bodies cannot be called through overriding methods.

Review effort: Balanced
Findings: 1

Open (1)

Abstract method bodies can be called via super() · New

What changed in this PR

Clarifies guidance for using NotImplementedError in base classes.

Changes:

Recommends use in non-abstract methods requiring overrides.
Adds cautionary guidance about abc.abstractmethod.

File	Description
`Doc/builtins/exceptions.rst`	Updates `NotImplementedError` usage documentation.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

clauspruefer · 2026-10-07T07:44:33Z

+      Methods decorated with :func:`abc.abstractmethod` designate a member function
+      as abstract, which prompts the ABC metaclass enforcement mechanism to verify
+      that a concrete implementation resides within the instantiated subclass.
+      Consequently, the Python interpreter invokes the overridden child class implementation
+      directly; the original base class method body remains uncalled during regular
+      polymorphic execution, rendering the inclusion of a :exc:`NotImplementedError`
+      entirely superfluous and redundant.


An abstract method is a method that is declared without an implementation (it has no code body). It defines a method's signature—> such as its name, parameters, and return type—but leaves the actual logic to be defined by its subclasses.

Calling a base class method via super() from within its overridden implementation is controversial when discussing what constitutes a strictly 'abstract' method.

read-the-docs-community · 2026-10-06T13:59:46Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #34970158 | 📁 Comparing 18e523f against main (82c62ab)

🔍 Preview build

1 file changed

± builtins/exceptions.html

picnixz

I don't think it's wrong though. A class can be considered abstract either from a semantical PoV or from a runtime PoV (inheriting abc.ABC). In the former case, raising NotImplementedError is relevant. The PoCs in the issues are also inaccurate:

Calling i.meow() raises: TypeError: Can't instantiate abstract class Tiger without an implementation for abstract method 'meow', the NotImplementedError exception code never will be executed.

That's not true. It's the instantiation of i that already raises the exception, not calling the method.

FTR, I fail to see the relation with class methods. And I don't think the docs are semantically wrong.

picnixz · 2026-10-06T17:19:29Z

      meant to be supported at all -- in that case either leave the operator /
      method undefined or, if a subclass, set it to :data:`None`.

+   .. caution::


We don't want this paragraph. This leaks implementation details and relates to a concept that is not about exceptions specifically.

picnixz · 2026-10-06T17:19:46Z

-   derived classes to override the method, or while the class is being
-   developed to indicate that the real implementation still needs to be added.
+   This exception is derived from :exc:`RuntimeError`. In user-defined base
+   classes, any **non**-abstract method should raise this exception when derived


That's not necessarily true, see

cpython/Lib/_collections_abc.py

Lines 450 to 452 in fb313a3

@abstractmethod

def __buffer__(self, flags: int, /) -> memoryview:

raise NotImplementedError

for instance.

This makes the intent clearer instead of having a pass statement or a ... statement and allows one to remove the decorator if necessary.

That's not necessarily true, see

cpython/Lib/_collections_abc.py

Lines 450 to 452 in fb313a3

@abstractmethod

def __buffer__(self, flags: int, /) -> memoryview:

raise NotImplementedError

for instance.

This makes the intent clearer instead of having a pass statement or a ... statement and allows one to remove the decorator if necessary.

No, this is wrong. An abstract method never should contain code.

In Python you must have one code. A pass statement remains something. So sorry but I'm not accepting this change. Clarity is better than purity in the language and NotImplementedError predates ABCs. ABCs also add overhead at runtime while raising NotImplementedError directly (without any abc.abstractmethod decorator) is the only way to convene the intent of an abstract method.

The page about exceptions is not about ABC only. It's for anyone wanting to define an abstract method.

A pass statement does not count as code.

Please review this correctly, your arguments are not logically, who pays you?

A pass statement does not count as code.

It does, from an interpreter PoV:

$ python3 -m dis def foo(): pass 0 RESUME 0 1 LOAD_CONST 0 (<code object foo at 0x10a05c730, file "<stdin>", line 1>) MAKE_FUNCTION STORE_NAME 0 (foo) LOAD_CONST 1 (None) RETURN_VALUE Disassembly of <code object foo at 0x10a05c730, file "<stdin>", line 1>: 1 RESUME 0 2 LOAD_CONST 0 (None) RETURN_VALUE

Please review this correctly, your arguments are not logically, who pays you?

Please keep it civil. This would count as a breach of CoC. And I already explained the rationale on the issue and here: ABCs should not be considered by NotImplementedError. They are an alternative where you are allowed to write regular code as well (in case you want to move OUT of ABCs in the future).

bedevere-app · 2026-10-06T17:20:42Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

StanFromIreland · 2026-10-06T18:30:30Z

Marking as draft till CLA is signed.

picnixz · 2026-10-07T09:23:36Z

Closing because the docs for the exception specifically are correct. If you use ABCs, that's different.

Copilot AI balanced review requested due to automatic review settings October 6, 2026 13:54

Copilot started reviewing on behalf of clauspruefer October 6, 2026 13:54 View session

bedevere-app Bot mentioned this pull request Oct 6, 2026

Wrong NotImplementedError documentation regarding abstract base classes #158911

Closed

bedevere-app Bot added awaiting review docs Documentation in the Doc dir skip news labels Oct 6, 2026

github-project-automation Bot added this to Docs PRs Oct 6, 2026

Copilot AI reviewed Oct 6, 2026

View reviewed changes

Pierre-Sassoulas mentioned this pull request Oct 6, 2026

abstract-method: decide which subclasses of an abstract class must override its abstract methods pylint-dev/pylint#11585

Open

picnixz requested changes Oct 6, 2026

View reviewed changes

bedevere-app Bot added awaiting changes and removed awaiting review labels Oct 6, 2026

StanFromIreland marked this pull request as draft October 6, 2026 18:30

bedevere-app Bot removed the awaiting changes label Oct 6, 2026

picnixz added the DO-NOT-MERGE label Oct 7, 2026

picnixz closed this Oct 7, 2026

	@abstractmethod
	def __buffer__(self, flags: int, /) -> memoryview:
	raise NotImplementedError

Conversation

clauspruefer commented Oct 6, 2026 • edited by bedevere-app Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reference (Details)

Implementation

Uh oh!

python-cla-bot Bot commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Choose a reason for hiding this comment

Uh oh!

read-the-docs-community Bot commented Oct 6, 2026

Documentation build overview

Uh oh!

picnixz left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-app Bot commented Oct 6, 2026

Uh oh!

StanFromIreland commented Oct 6, 2026

Uh oh!

picnixz commented Oct 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

clauspruefer commented Oct 6, 2026 •

edited by bedevere-app Bot

Loading

python-cla-bot Bot commented Oct 6, 2026 •

edited

Loading