[issue46814] Documentation for constructin abstract base classes is misleading

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46814] Documentation for constructin abstract base classes is misleading

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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")
  instantiate(cls)

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?

--
nosy: +gvanrossum, rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46814] Documentation for constructin abstract base classes is misleading

[Josh A. Mitchell]

Change by Josh A. Mitchell :


--
keywords: +patch
pull_requests: +29592
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/31463

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46814] Documentation for constructin abstract base classes is misleading

[Josh A. Mitchell]

New submission from Josh A. Mitchell :

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.

[0] https://docs.python.org/3.11/library/abc.html

[1] 
https://www.python.org/dev/peps/pep-3119/#the-abc-module-an-abc-support-framework

--
assignee: docs@python
components: Documentation
messages: 413639
nosy: Yoshanuikabundi, docs@python
priority: normal
severity: normal
status: open
title: Documentation for constructin abstract base classes is misleading
versions: Python 3.11

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com