This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Documentation for constructing abstract base classes is misleading
Type: Stage: patch review
Components: Documentation Versions: Python 3.11
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Yoshanuikabundi, docs@python, gvanrossum, rhettinger
Priority: normal Keywords: patch

Created on 2022-02-21 08:25 by Yoshanuikabundi, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 31463 open Yoshanuikabundi, 2022-02-21 09:15
Messages (5)
msg413639 - (view) Author: Josh A. Mitchell (Yoshanuikabundi) * Date: 2022-02-21 08:25
The docs for the abc[0] module states "With this class, an abstract base class can be created by simply deriving from ABC", and then gives an example of a class with no contents. This is not sufficient to construct an ABC; an ABC in Python additionally requires at least one abstract method. This can be demonstrated by executing the example code and instantiating it (ABCs cannot be instantiated) or calling the inspect.isabstract() function on it (returns False). The requirement is also (cryptically) explicated in the Implementation paragraph of the "The abc Module: an ABC Support Framework" section of PEP 3119[1]. This requirement of implementing an abstract method is not mentioned in the docs for the abc module or in the module's docstrings. An ABC with no abstract methods is sometimes used to mark a parent class that is not intended to be instantiated on its own, so this limitation of the Python implementation should be documented.


msg413682 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2022-02-21 21:37
To me, this looks like a way too extensive edit jsut to emphasize a corner case that rarely arises in practice.   It bends over backwards to force an awkward definition regarding what an ABC really is.

A more minimal edit is to just note that inspect.isabstract() returns true if a class inherits from ABC and has at least one remaining abstractmethod.  

That tells the truth without having to redefine an ABC.  And it matches the spirit of the ABC mechanism.  At no point does ABCMeta ever require that any class in the chain must have ever defined an abstractmethod.  Instead, its only rule is that if there is least one remaining abstractmethod, it will refuse to instantiate.  Roughly:

  if any(getattr(meth, '__isabstractmethod__', False) for meth in meths):
     raise TypeError("Can't instantiate")

Note, any() defaults to False if there are no inputs and that the actual C code works the same way.  Even if a class never defines any abstractmethods, this test still occurs.  For an empty ABC, it just happens to always succeed in instantiating because there is no work left to be done.

Worldviews aside, I don't think it helpful to users to everywhere rewrite what it means to be an ABC just to make it match the output of inspect.isabstract() which is just short for inspect.has_abstract_methods_remaining().

Guido, any thoughts?
msg413683 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2022-02-21 21:47
An analogy may help.  Release managers must check the list of release blockers and stop if the list is non-empty.  If no release blockers were ever filed, the release blockers list is empty, but it still exists and its definition hasn't changed.

The test is_blocked(blockers) tells us whether the list is non-empty.  It doesn't redefine what it means to be a blockers list.
msg413686 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2022-02-21 23:35
FWIW, I’m only -0 on this.   It is also perfectly reasonable to say that a class is abstract if and only if there is at least one remaining abstract method.  After 15 years though, I’m inclined to say that the status quo wins.
msg414208 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2022-02-28 16:58
Raymond, I agree that this is going too far. I believe the OP has taken the position that "abstract" has only one meaning and it is defined by inspect.isabstract(). I disagree with this.

An ABC is an ABC is an ABC, and it provides certain functionality through the ABCMeta metaclass: (1) forbid instantiation when at least one @abstractmethod-decorated method exist that isn't overridden, and (2) virtual subclasses.

Calling out that a class with metaclass=ABCMeta is only abstract when it has at least one @abstractmethod left, over and over, is not helpful.
Date User Action Args
2022-04-11 14:59:56adminsetgithub: 90970
2022-02-28 16:58:45gvanrossumsetmessages: + msg414208
2022-02-21 23:35:53rhettingersetmessages: + msg413686
2022-02-21 22:01:40AlexWaygoodsettitle: Documentation for constructin abstract base classes is misleading -> Documentation for constructing abstract base classes is misleading
2022-02-21 21:47:14rhettingersetmessages: + msg413683
2022-02-21 21:37:43rhettingersetnosy: + rhettinger, gvanrossum
messages: + msg413682
2022-02-21 09:15:43Yoshanuikabundisetkeywords: + patch
stage: patch review
pull_requests: + pull_request29592
2022-02-21 08:25:45Yoshanuikabundicreate