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>

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 84f77e8f2064384a04b416296346947f23fb3684..a0beed4a8c77fb7b57245921d3b0fca32991b76d 100644 (file)
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -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