Wrong NotImplementedError documentation regarding abstract base classes

Documentation

Python Versions

Python 3.10 / 3.11 / 3.12 / 3.13 / 3.14 / 3.15 / 3.16 beta

Description

The current documentation for NotImplementedError on docs.python.org contains a conceptual and technical contradiction regarding its use in abstract class methods.

Current cpython Documentation

From /Doc/builtins/exceptions.rst:

"In user-defined base classes, abstract methods should raise this exception when they require derived classes to override the method, or while the class is being developed to indicate that the real implementation still needs to be added."

The Problem

This documentation text advises developers to raise `NotImplementedError inside abstract class methods.,This is incorrect, as the Python interpreter will never execute the exception-raising code.

Basic Example (Schematic Code)

class Base(metaclass=ABCMeta):
    @abstractmethod
    def meow(self):
        raise NotImplementedError("I am not able to meow right now, this will change in version 0.3")

The Python Interpreter will never output the "I am not able to ..." message which the following code will prove.

PoC Code 1

from abc import ABCMeta, abstractmethod

class Base(metaclass=ABCMeta):
    @abstractmethod
    def meow(self):
        raise NotImplementedError("Must override") # This code is unreachable

i = Base()
i.meow()

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

PoC Code 2 (Multi-Inheritance)

from abc import ABCMeta, abstractmethod

class Base(metaclass=ABCMeta):
    @abstractmethod
    def meow(self):
        raise NotImplementedError("Must override") # This code is unreachable

class Tiger(Base):
    def other(self):
        print('other')

i = Tiger()
i.meow()

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.

Correct Context

The Python interpreter behaves 100% correctly. The error lies solely within the Python documentation, which incorrectly recommends the pattern of raising NotImplementedError inside abstract methods.

Raising NotImplementedError only makes sense in non-abstract class-methods

Real-World Impact (Pylint)

The current Python documentation text has a cascading effect on the Python ecosystem. Most notably, Pylint relies heavily on this exact wording for its code checks. Because the documentation explicitly commands that abstract methods should raise this exception, Pylint's abstract method checking has been incorrectly implemented.

Proposed Changes

Suggested Replacement Text:

"In user-defined base classes, any non-abstract method should raise this exception when derived classes are required to override the method, indicating that the real implementation still needs to be added."

References

https://www.der-it-pruefer.de/programming/Python-Abstract-ClassMethods (contains proof of concept code)
Should we remove abstract-method? pylint-dev/pylint#10054 (comment) (current Pylint discussion)

Linked PRs

gh-158911 Docs: Correct and clarify NotImplementedError usage guidelines #158912

I don't think this is a correct change nor a valid issue: #158912 (review)

I don't think this is a correct change nor a valid issue: #158912 (review)

I do not agree, the examples from you and Copilot are wrong!

The definition of an abstract method:

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.

An abstract method has no code body and therefore a super() call from the overriding method breaks the basic rules.

This rule doesn't hold in Python necessarily. ABCs add overhead at the cost of safety but if you want to define an abstract method in Python, and semantically speaking, you just need to raise NotImplementedError. That's the only role of that exception. Once you use ABCs, the contract is a bit different and people either use "..." or "pass" statements, which btw makes the implementation contain something (there is an implicit return None)).

But the docs for the exception itself are correct.

This rule doesn't hold in Python necessarily. ABCs add overhead at the cost of safety but if you want to define an abstract method in Python, and semantically speaking, you just need to raise NotImplementedError. That's the only role of that exception. Once you use ABCs, the contract is a bit different and people either use "..." or "pass" statements, which btw makes the implementation contain something (there is an implicit return None)).

But the docs for the exception itself are correct.

No, the documentation for the NotImplementedError exception is incorrect. An abstract class-method must always be declared using @abstractmethod (abc module); otherwise, it is not an abstract class-method.

This exception is derived from RuntimeError. In user defined base classes, abstract methods should raise this exception when they require derived classes to override the method, or while the class is being developed to indicate that the real implementation still needs to be added.

Please, recheck what exactly an abstract class or method is in C++, Java, or similar languages, given your background in them.

Furthermore, it is false that raising a NotImplementedError inside a method body magically makes it abstract. The concept of abstractness exists precisely to guarantee that if you have multiple child classes, the abstract method must be implemented in all of them.

And as a side note: the Python interpreter and the abc module implementation behave 100% correctly according to these abstractness rules; only the documentation states exactly the opposite.

Please, recheck what exactly an abstract class or method is in C++, Java, or similar languages, given your background in them.

Those languages have different semantics.

An abstract class-method must always be declared using @abstractmethod (abc module); otherwise, it is not an abstract class-method

ABCs are only for duck typing but semantics can be decided by developers. Having ABCs is a non-trivial overhead. Raising NotImplementedError is a way to declare the intent of an abstract method (in the Python sense) without having to enforce it (that is, without forbidding instantiation). It's not making it abstract at runtime. It's making it abstract semantically. Then users can know that it was meant to be abstract if they hit an issue at runtime. Python doesn't have the same way of contracts as other languages and we apply the consenting adults principle here.

The #100400 issue should be used instead of this one and the tone of the conversation is not civil enough. Should you continue being aggressive, we will restrict your access to our repositories.

I will also no longer interact with you because it doesn't seem you want to hear my arguments.

Navigation Menu

Repository navigation

Wrong NotImplementedError documentation regarding abstract base classes #158911

Documentation

Python Versions

Description

Current cpython Documentation

The Problem

Basic Example (Schematic Code)

PoC Code 1

PoC Code 2 (Multi-Inheritance)

Correct Context

Real-World Impact (Pylint)

Proposed Changes

References

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Wrong NotImplementedError documentation regarding abstract base classes #158911

Description

Documentation

Python Versions

Description

Current cpython Documentation

The Problem

Basic Example (Schematic Code)

PoC Code 1

PoC Code 2 (Multi-Inheritance)

Correct Context

Real-World Impact (Pylint)

Proposed Changes

References

Linked PRs

Activity

picnixz commented on Oct 6, 2026

clauspruefer commented on Oct 7, 2026

picnixz commented on Oct 7, 2026

clauspruefer commented on Oct 7, 2026

picnixz commented on Oct 7, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions