Wrong NotImplementedError documentation regarding abstract base classes

[clauspruefer]

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

1. https://www.der-it-pruefer.de/programming/Python-Abstract-ClassMethods (contains proof of concept code)
2. 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

[picnixz]

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

[clauspruefer]

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.