From 18e523fa4a75ef438b19dd96165c0add57444dc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Claus=20Pr=C3=BCfer?= Date: Tue, 6 Oct 2026 14:47:58 +0200 Subject: [PATCH] Docs: Correct and clarify NotImplementedError usage guidelines 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. --- Doc/builtins/exceptions.rst | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/Doc/builtins/exceptions.rst b/Doc/builtins/exceptions.rst index ecf62fb6391b1b..cc173fbc692ae3 100644 --- a/Doc/builtins/exceptions.rst +++ b/Doc/builtins/exceptions.rst @@ -338,10 +338,10 @@ 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 + classes are required to override the method, indicating that the real + implementation still needs to be added. .. note:: @@ -349,6 +349,16 @@ The following exceptions are the exceptions that are usually raised. 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:: + + 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. + .. caution:: :exc:`!NotImplementedError` and :data:`!NotImplemented` are not