typing docs: Clarify Protocol / runtime_checkable docs (#132606)

- Explicitly say that isinstance/issubclass do not work on non-runtime checkable
  protocols.
- Move the sentence "This raises TypeError when applied to a non-protocol class". It
  took me quite some time to decide what "this" was here: it refers to applying the
  decorator, not to an isinstance() call.

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
This commit is contained in:
Jelle Zijlstra 2025-04-16 10:44:17 -07:00 committed by GitHub
parent 2925462411
commit 14efcadfd4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -2455,7 +2455,8 @@ types.
See :pep:`544` for more details. Protocol classes decorated with
:func:`runtime_checkable` (described later) act as simple-minded runtime
protocols that check only the presence of given attributes, ignoring their
type signatures.
type signatures. Protocol classes without this decorator cannot be used
as the second argument to :func:`isinstance` or :func:`issubclass`.
Protocol classes can be generic, for example::
@ -2479,8 +2480,7 @@ types.
Mark a protocol class as a runtime protocol.
Such a protocol can be used with :func:`isinstance` and :func:`issubclass`.
This raises :exc:`TypeError` when applied to a non-protocol class. This
allows a simple-minded structural check, very similar to "one trick ponies"
This allows a simple-minded structural check, very similar to "one trick ponies"
in :mod:`collections.abc` such as :class:`~collections.abc.Iterable`. For example::
@runtime_checkable
@ -2496,6 +2496,8 @@ types.
import threading
assert isinstance(threading.Thread(name='Bob'), Named)
This decorator raises :exc:`TypeError` when applied to a non-protocol class.
.. note::
:func:`!runtime_checkable` will check only the presence of the required