gh-102936: typing: document performance pitfalls of protocols decorated with `@runtime_checkable` (GH-102937)
(cherry picked from commit 58d2b30c012c3a9fe5ab747ae47c96af09e0fd15)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 8db9a3f..df6ddb6 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -1582,16 +1582,32 @@
assert isinstance(open('/some/file'), Closable)
+ @runtime_checkable
+ class Named(Protocol):
+ name: str
+
+ import threading
+ assert isinstance(threading.Thread(name='Bob'), Named)
+
.. note::
- :func:`runtime_checkable` will check only the presence of the required
- methods, not their type signatures. For example, :class:`ssl.SSLObject`
+ :func:`!runtime_checkable` will check only the presence of the required
+ methods or attributes, not their type signatures or types.
+ For example, :class:`ssl.SSLObject`
is a class, therefore it passes an :func:`issubclass`
check against :data:`Callable`. However, the
``ssl.SSLObject.__init__`` method exists only to raise a
:exc:`TypeError` with a more informative message, therefore making
it impossible to call (instantiate) :class:`ssl.SSLObject`.
+ .. note::
+
+ An :func:`isinstance` check against a runtime-checkable protocol can be
+ surprisingly slow compared to an ``isinstance()`` check against
+ a non-protocol class. Consider using alternative idioms such as
+ :func:`hasattr` calls for structural checks in performance-sensitive
+ code.
+
.. versionadded:: 3.8
Other special directives
