Subtle pattern in the __subclasshook__ docs isn't explained

Documentation

The docs for subclasshook[0] contains the following example:

from abc import ABC

class MyIterable(ABC):
    ...
    @classmethod
    def __subclasshook__(cls, C):
        if cls is MyIterable:
            if any("__iter__" in B.__dict__ for B in C.__mro__):
                return True
        return NotImplemented

The docs state that "This method should return True, False or NotImplemented" but the example given only returns True | NotImplemented. This makes it hard for the user to understand how to use the method themselves.

In particular it's not clear to the reader:

1. Why they may want to return NotImplemented instead of False (this is a common pattern used in stdlib ABCs).
2. That returning False in __subclasshook__ will override the registration of a class due to the issubclass algorithm. [1][2]

[0] https://docs.python.org/3.12/library/abc.html#abc.ABCMeta.__subclasshook__
[1] Demonstration of this:

from abc import ABC

class Iterable(ABC):
    
    @classmethod
    def __subclasshook__(cls, subclass):
        return hasattr(subclass, "__iter__")

class NotIterable:
    """Does not define __iter__."""


Iterable.register(NotIterable)
assert issubclass(NotIterable, Iterable)
# 'AssertionErrror'

[2] My understanding of the issubclass algorithm is described in this comment: https://github.com/python/cpython/issues/61035#issuecomment-1361180346

Linked PRs

• gh-100453
• gh-100503

Comece pela documentação de abc.ABCMeta.subclasshook vinculada no issue e revise a discussão referenciada sobre issubclass. Compare o exemplo existente com o comportamento indicado de True, False e NotImplemented; em seguida, atualize a explicação e adicione ou revise exemplos para que a distinção fique clara. Verifique os PRs vinculados gh-100453 e gh-100503 antes de começar.