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

從 issue 中連結的 abc.ABCMeta.subclasshook 文件開始，並查看所參照的 issubclass 討論。將現有範例與 True、False 和 NotImplemented 的所述行為進行比較，然後更新說明並新增或修改範例，以清楚呈現其中的區別。開始之前檢查連結的 PR gh-100453 和 gh-100503。