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

Bắt đầu với tài liệu về abc.ABCMeta.subclasshook được liên kết trong issue và xem lại cuộc thảo luận được tham chiếu về issubclass. So sánh ví dụ hiện có với hành vi được nêu của True, False và NotImplemented, sau đó cập nhật phần giải thích và thêm hoặc sửa đổi các ví dụ để làm rõ sự khác biệt. Kiểm tra các PR được liên kết gh-100453 và gh-100503 trước khi bắt đầu.