Skip to content

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

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

Closed
clauspruefer wants to merge 1 commit into from
Closed

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
18 changes: 14 additions & 4 deletions Doc/builtins/exceptions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -338,17 +338,27 @@ The following exceptions are the exceptions that are usually raised.

.. exception:: NotImplementedError

This exception is derived from :exc:`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.
This exception is derived from :exc:`RuntimeError`. In user-defined base
classes, any **non**-abstract method should raise this exception when derived

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

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.

@clauspruefer clauspruefer Oct 7, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

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.

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

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.

@clauspruefer clauspruefer Oct 7, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

A pass statement does not count as code.

@clauspruefer clauspruefer Oct 7, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

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

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

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).

classes are required to override the method, indicating that the real
implementation still needs to be added.

.. note::

It should not be used to indicate that an operator or method is not
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::

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

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


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.
Comment on lines +354 to +360

@clauspruefer clauspruefer Oct 7, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

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.


.. caution::

:exc:`!NotImplementedError` and :data:`!NotImplemented` are not
Expand Down
Loading