From 91b67405a7cd9da551411ccb4e28493647208c11 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 18 Jun 2023 14:12:50 -0700
Subject: [PATCH] Small improvements to protocol documentation (#15460)

---
 docs/source/protocols.rst | 50 +++++++++++++++++++--------------------
 1 file changed, 24 insertions(+), 26 deletions(-)

diff --git a/docs/source/protocols.rst b/docs/source/protocols.rst
index 95b870265f73..3336d77cb397 100644
--- a/docs/source/protocols.rst
+++ b/docs/source/protocols.rst
@@ -3,26 +3,24 @@
 Protocols and structural subtyping
 ==================================
 
-Mypy supports two ways of deciding whether two classes are compatible
-as types: nominal subtyping and structural subtyping.
-
-*Nominal* subtyping is strictly based on the class hierarchy. If class ``D``
-inherits class ``C``, it's also a subtype of ``C``, and instances of
-``D`` can be used when ``C`` instances are expected. This form of
-subtyping is used by default in mypy, since it's easy to understand
-and produces clear and concise error messages, and since it matches
-how the native :py:func:`isinstance <isinstance>` check works -- based on class
+The Python type system supports two ways of deciding whether two objects are
+compatible as types: nominal subtyping and structural subtyping.
+
+*Nominal* subtyping is strictly based on the class hierarchy. If class ``Dog``
+inherits class ``Animal``, it's a subtype of ``Animal``. Instances of ``Dog``
+can be used when ``Animal`` instances are expected. This form of subtyping
+subtyping is what Python's type system predominantly uses: it's easy to
+understand and produces clear and concise error messages, and matches how the
+native :py:func:`isinstance <isinstance>` check works -- based on class
 hierarchy.
 
-*Structural* subtyping is based on the operations that can be performed with an object. Class ``D`` is
-a structural subtype of class ``C`` if the former has all attributes
-and methods of the latter, and with compatible types.
+*Structural* subtyping is based on the operations that can be performed with an
+object. Class ``Dog`` is a structural subtype of class ``Animal`` if the former
+has all attributes and methods of the latter, and with compatible types.
 
-Structural subtyping can be seen as a static equivalent of duck
-typing, which is well known to Python programmers. Mypy provides
-support for structural subtyping via protocol classes described
-below.  See :pep:`544` for the detailed specification of protocols
-and structural subtyping in Python.
+Structural subtyping can be seen as a static equivalent of duck typing, which is
+well known to Python programmers. See :pep:`544` for the detailed specification
+of protocols and structural subtyping in Python.
 
 .. _predefined_protocols:
 
@@ -60,8 +58,7 @@ For example, ``IntList`` below is iterable, over ``int`` values:
 
 :ref:`predefined_protocols_reference` lists all protocols defined in
 :py:mod:`typing` and the signatures of the corresponding methods you need to define
-to implement each protocol (the signatures can be left out, as always, but mypy
-won't type check unannotated methods).
+to implement each protocol.
 
 Simple user-defined protocols
 *****************************
@@ -89,18 +86,12 @@ class:
        for item in items:
            item.close()
 
-   close_all([Resource(), open('some/file')])  # Okay!
+   close_all([Resource(), open('some/file')])  # OK
 
 ``Resource`` is a subtype of the ``SupportsClose`` protocol since it defines
 a compatible ``close`` method. Regular file objects returned by :py:func:`open` are
 similarly compatible with the protocol, as they support ``close()``.
 
-.. note::
-
-   The ``Protocol`` base class is provided in the ``typing_extensions``
-   package for Python 3.4-3.7. Starting with Python 3.8, ``Protocol``
-   is included in the ``typing`` module.
-
 Defining subprotocols and subclassing protocols
 ***********************************************
 
@@ -171,6 +162,13 @@ abstract:
    ExplicitSubclass()  # error: Cannot instantiate abstract class 'ExplicitSubclass'
                        # with abstract attributes 'attr' and 'method'
 
+Similarly, explicitly assigning to a protocol instance can be a way to ask the
+type checker to verify that your class implements a protocol:
+
+.. code-block:: python
+
+   _proto: SomeProto = cast(ExplicitSubclass, None)
+
 Invariance of protocol attributes
 *********************************