gh-102936: typing: document performance pitfalls of protocols decorated with @runtime_checkable (GH-102937)

miss-islington · AlexWaygood · web-flow · commit 6c667d025a1b · 2023-03-23T11:28:11.000-07:00
(cherry picked from commit 58d2b30) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
@@ -1350,16 +1350,32 @@ These are not used in annotations. They are building blocks for creating generic
 
       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
