Crossreferences to standard library in mypy docs, part 7

docs/source/protocols.rst

@@ -10,7 +10,7 @@ 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 ``isinstance()`` check works -- based on class
+how the native :py:func:`isinstance <isinstance>` check works -- based on class
 hierarchy. *Structural* subtyping can also be useful. Class ``D`` is
 a structural subtype of class ``C`` if the former has all attributes
 and methods of the latter, and with compatible types.
@@ -26,10 +26,10 @@ and structural subtyping in Python.
 Predefined protocols
 ********************
 
-The ``typing`` module defines various protocol classes that correspond
-to common Python protocols, such as ``Iterable[T]``.  If a class
-defines a suitable ``__iter__`` method, mypy understands that it
-implements the iterable protocol and is compatible with ``Iterable[T]``.
+The :py:mod:`typing` module defines various protocol classes that correspond
+to common Python protocols, such as :py:class:`Iterable[T] <typing.Iterable>`. If a class
+defines a suitable :py:meth:`__iter__ <object.__iter__>` method, mypy understands that it
+implements the iterable protocol and is compatible with :py:class:`Iterable[T] <typing.Iterable>`.
 For example, ``IntList`` below is iterable, over ``int`` values:
 
 .. code-block:: python
@@ -56,7 +56,7 @@ For example, ``IntList`` below is iterable, over ``int`` values:
    print_numbered([4, 5])  # Also OK
 
 The subsections below introduce all built-in protocols defined in
-``typing`` and the signatures of the corresponding methods you need to define
+: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).
 
@@ -66,170 +66,200 @@ Iteration protocols
 The iteration protocols are useful in many contexts. For example, they allow
 iteration of objects in for loops.
 
-``Iterable[T]``
----------------
+Iterable[T]
+-----------
 
 The :ref:`example above <predefined_protocols>` has a simple implementation of an
-``__iter__`` method.
+:py:meth:`__iter__ <object.__iter__>` method.
 
 .. code-block:: python
 
    def __iter__(self) -> Iterator[T]
 
-``Iterator[T]``
----------------
+See also :py:class:`~typing.Iterable`.
+
+Iterator[T]
+-----------
 
 .. code-block:: python
 
    def __next__(self) -> T
    def __iter__(self) -> Iterator[T]
 
+See also :py:class:`~typing.Iterator`.
+
 Collection protocols
 ....................
 
 Many of these are implemented by built-in container types such as
-``list`` and ``dict``, and these are also useful for user-defined
+:py:class:`list` and :py:class:`dict`, and these are also useful for user-defined
 collection objects.
 
-``Sized``
----------
+Sized
+-----
 
-This is a type for objects that support ``len(x)``.
+This is a type for objects that support :py:func:`len(x) <len>`.
 
 .. code-block:: python
 
    def __len__(self) -> int
 
-``Container[T]``
-----------------
+See also :py:class:`~typing.Sized`.
+
+Container[T]
+------------
 
 This is a type for objects that support the ``in`` operator.
 
 .. code-block:: python
 
    def __contains__(self, x: object) -> bool
 
-``Collection[T]``
------------------
+See also :py:class:`~typing.Container`.
+
+Collection[T]
+-------------
 
 .. code-block:: python
 
    def __len__(self) -> int
    def __iter__(self) -> Iterator[T]
    def __contains__(self, x: object) -> bool
 
+See also :py:class:`~typing.Collection`.
+
 One-off protocols
 .................
 
 These protocols are typically only useful with a single standard
 library function or class.
 
-``Reversible[T]``
------------------
+Reversible[T]
+-------------
 
-This is a type for objects that support ``reversed(x)``.
+This is a type for objects that support :py:func:`reversed(x) <reversed>`.
 
 .. code-block:: python
 
    def __reversed__(self) -> Iterator[T]
 
-``SupportsAbs[T]``
-------------------
+See also :py:class:`~typing.Reversible`.
 
-This is a type for objects that support ``abs(x)``. ``T`` is the type of
-value returned by ``abs(x)``.
+SupportsAbs[T]
+--------------
+
+This is a type for objects that support :py:func:`abs(x) <abs>`. ``T`` is the type of
+value returned by :py:func:`abs(x) <abs>`.
 
 .. code-block:: python
 
    def __abs__(self) -> T
 
-``SupportsBytes``
------------------
+See also :py:class:`~typing.SupportsAbs`.
 
-This is a type for objects that support ``bytes(x)``.
+SupportsBytes
+-------------
+
+This is a type for objects that support :py:class:`bytes(x) <bytes>`.
 
 .. code-block:: python
 
    def __bytes__(self) -> bytes
 
+See also :py:class:`~typing.SupportsBytes`.
+
 .. _supports-int-etc:
 
-``SupportsComplex``
--------------------
+SupportsComplex
+---------------
 
-This is a type for objects that support ``complex(x)``. Note that no arithmetic operations
+This is a type for objects that support :py:class:`complex(x) <complex>`. Note that no arithmetic operations
 are supported.
 
 .. code-block:: python
 
    def __complex__(self) -> complex
 
-``SupportsFloat``
------------------
+See also :py:class:`~typing.SupportsComplex`.
 
-This is a type for objects that support ``float(x)``. Note that no arithmetic operations
+SupportsFloat
+-------------
+
+This is a type for objects that support :py:class:`float(x) <float>`. Note that no arithmetic operations
 are supported.
 
 .. code-block:: python
 
    def __float__(self) -> float
 
-``SupportsInt``
----------------
+See also :py:class:`~typing.SupportsFloat`.
 
-This is a type for objects that support ``int(x)``.  Note that no arithmetic operations
+SupportsInt
+-----------
+
+This is a type for objects that support :py:class:`int(x) <int>`. Note that no arithmetic operations
 are supported.
 
 .. code-block:: python
 
    def __int__(self) -> int
 
-``SupportsRound[T]``
---------------------
+See also :py:class:`~typing.SupportsInt`.
+
+SupportsRound[T]
+----------------
 
-This is a type for objects that support ``round(x)``.
+This is a type for objects that support :py:func:`round(x) <round>`.
 
 .. code-block:: python
 
    def __round__(self) -> T
 
+See also :py:class:`~typing.SupportsRound`.
+
 Async protocols
 ...............
 
 These protocols can be useful in async code. See :ref:`async-and-await`
 for more information.
 
-``Awaitable[T]``
-----------------
+Awaitable[T]
+------------
 
 .. code-block:: python
 
    def __await__(self) -> Generator[Any, None, T]
 
-``AsyncIterable[T]``
---------------------
+See also :py:class:`~typing.Awaitable`.
+
+AsyncIterable[T]
+----------------
 
 .. code-block:: python
 
    def __aiter__(self) -> AsyncIterator[T]
 
-``AsyncIterator[T]``
---------------------
+See also :py:class:`~typing.AsyncIterable`.
+
+AsyncIterator[T]
+----------------
 
 .. code-block:: python
 
    def __anext__(self) -> Awaitable[T]
    def __aiter__(self) -> AsyncIterator[T]
 
+See also :py:class:`~typing.AsyncIterator`.
+
 Context manager protocols
 .........................
 
 There are two protocols for context managers -- one for regular context
 managers and one for async ones. These allow defining objects that can
 be used in ``with`` and ``async with`` statements.
 
-``ContextManager[T]``
----------------------
+ContextManager[T]
+-----------------
 
 .. code-block:: python
 
@@ -239,8 +269,10 @@ be used in ``with`` and ``async with`` statements.
                 exc_value: Optional[BaseException],
                 traceback: Optional[TracebackType]) -> Optional[bool]
 
-``AsyncContextManager[T]``
---------------------------
+See also :py:class:`~typing.ContextManager`.
+
+AsyncContextManager[T]
+----------------------
 
 .. code-block:: python
 
@@ -250,6 +282,8 @@ be used in ``with`` and ``async with`` statements.
                  exc_value: Optional[BaseException],
                  traceback: Optional[TracebackType]) -> Awaitable[Optional[bool]]
 
+See also :py:class:`~typing.AsyncContextManager`.
+
 Simple user-defined protocols
 *****************************
 
@@ -278,7 +312,7 @@ class:
    close_all([Resource(), open('some/file')])  # Okay!
 
 ``Resource`` is a subtype of the ``SupportsClose`` protocol since it defines
-a compatible ``close`` method. Regular file objects returned by ``open()`` are
+a compatible ``close`` method. Regular file objects returned by :py:func:`open` are
 similarly compatible with the protocol, as they support ``close()``.
 
 .. note::
@@ -379,7 +413,7 @@ such as trees and linked lists:
 Using isinstance() with protocols
 *********************************
 
-You can use a protocol class with ``isinstance()`` if you decorate it
+You can use a protocol class with :py:func:`isinstance` if you decorate it
 with the ``@runtime_checkable`` class decorator. The decorator adds
 support for basic runtime structural checks:
 
@@ -399,11 +433,11 @@ support for basic runtime structural checks:
    if isinstance(mug, Portable):
       use(mug.handles)  # Works statically and at runtime
 
-``isinstance()`` also works with the :ref:`predefined protocols <predefined_protocols>`
-in ``typing`` such as ``Iterable``.
+:py:func:`isinstance` also works with the :ref:`predefined protocols <predefined_protocols>`
+in :py:mod:`typing` such as :py:class:`~typing.Iterable`.
 
 .. note::
-   ``isinstance()`` with protocols is not completely safe at runtime.
+   :py:func:`isinstance` with protocols is not completely safe at runtime.
    For example, signatures of methods are not checked. The runtime
    implementation only checks that all protocol members are defined.
 
@@ -413,8 +447,8 @@ Callback protocols
 ******************
 
 Protocols can be used to define flexible callback types that are hard
-(or even impossible) to express using the ``Callable[...]`` syntax, such as variadic,
-overloaded, and complex generic callbacks. They are defined with a special ``__call__``
+(or even impossible) to express using the :py:data:`Callable[...] <typing.Callable>` syntax, such as variadic,
+overloaded, and complex generic callbacks. They are defined with a special :py:meth:`__call__ <object.__call__>`
 member:
 
 .. code-block:: python
@@ -438,8 +472,8 @@ member:
    batch_proc([], bad_cb)   # Error! Argument 2 has incompatible type because of
                             # different name and kind in the callback
 
-Callback protocols and ``Callable[...]`` types can be used interchangeably.
-Keyword argument names in ``__call__`` methods must be identical, unless
+Callback protocols and :py:data:`~typing.Callable` types can be used interchangeably.
+Keyword argument names in :py:meth:`__call__ <object.__call__>` methods must be identical, unless
 a double underscore prefix is used. For example:
 
 .. code-block:: python