Crossreferences to standard library in mypy docs, part 5 (#7689)

Signed-off-by: Oleg Höfling <[email protected]>

Author: hoefling

docs/source/kinds_of_types.rst

@@ -10,7 +10,7 @@ Class types
 
 Every class is also a valid type. Any instance of a subclass is also
 compatible with all superclasses -- it follows that every value is compatible
-with the ``object`` type (and incidentally also the ``Any`` type, discussed
+with the :py:class:`object` type (and incidentally also the ``Any`` type, discussed
 below). Mypy analyzes the bodies of classes to determine which methods and
 attributes are available in instances. This example uses subclassing:
 
@@ -135,7 +135,7 @@ purpose. Example:
 .. note::
 
    Usually it's a better idea to use ``Sequence[T]`` instead of ``Tuple[T, ...]``, as
-   ``Sequence`` is also compatible with lists and other non-tuple sequences.
+   :py:class:`~typing.Sequence` is also compatible with lists and other non-tuple sequences.
 
 .. note::
 
@@ -212,7 +212,7 @@ Use the ``Union[T1, ..., Tn]`` type constructor to construct a union
 type. For example, if an argument has type ``Union[int, str]``, both
 integers and strings are valid argument values.
 
-You can use an ``isinstance()`` check to narrow down a union type to a
+You can use an :py:func:`isinstance` check to narrow down a union type to a
 more specific type:
 
 .. code-block:: python
@@ -235,18 +235,18 @@ more specific type:
 .. note::
 
     Operations are valid for union types only if they are valid for *every*
-    union item. This is why it's often necessary to use an ``isinstance()``
+    union item. This is why it's often necessary to use an :py:func:`isinstance`
     check to first narrow down a union type to a non-union type. This also
     means that it's recommended to avoid union types as function return types,
-    since the caller may have to use ``isinstance()`` before doing anything
+    since the caller may have to use :py:func:`isinstance` before doing anything
     interesting with the value.
 
 .. _strict_optional:
 
 Optional types and the None type
 ********************************
 
-You can use the ``Optional`` type modifier to define a type variant
+You can use the :py:data:`~typing.Optional` type modifier to define a type variant
 that allows ``None``, such as ``Optional[int]`` (``Optional[X]`` is
 the preferred shorthand for ``Union[X, None]``):
 
@@ -264,7 +264,7 @@ the preferred shorthand for ``Union[X, None]``):
            return None  # Error: None not compatible with int
        return len(s)
 
-Most operations will not be allowed on unguarded ``None`` or ``Optional``
+Most operations will not be allowed on unguarded ``None`` or :py:data:`~typing.Optional`
 values:
 
 .. code-block:: python
@@ -415,7 +415,7 @@ Disabling strict optional checking
 Mypy also has an option to treat ``None`` as a valid value for every
 type (in case you know Java, it's useful to think of it as similar to
 the Java ``null``). In this mode ``None`` is also valid for primitive
-types such as ``int`` and ``float``, and ``Optional[...]`` types are
+types such as ``int`` and ``float``, and :py:data:`~typing.Optional` types are
 not required.
 
 The mode is enabled through the ``--no-strict-optional`` command-line
@@ -455,7 +455,7 @@ but it's not obvious from its signature:
     print(greeting('Python'))  # Okay!
     print(greeting(None))      # Also okay!
 
-You can still use ``Optional[t]`` to document that ``None`` is a
+You can still use :py:data:`Optional[t] <typing.Optional>` to document that ``None`` is a
 valid argument type, even if strict ``None`` checking is not
 enabled:
 
@@ -566,9 +566,9 @@ missing attribute:
     p = Point(x=1, y=2)
     print(p.z)  # Error: Point has no attribute 'z'
 
-If you use ``namedtuple`` to define your named tuple, all the items
+If you use :py:func:`namedtuple <collections.namedtuple>` to define your named tuple, all the items
 are assumed to have ``Any`` types. That is, mypy doesn't know anything
-about item types. You can use ``typing.NamedTuple`` to also define
+about item types. You can use :py:class:`~typing.NamedTuple` to also define
 item types:
 
 .. code-block:: python
@@ -600,10 +600,10 @@ The type of class objects
 <484#the-type-of-class-objects>`.)
 
 Sometimes you want to talk about class objects that inherit from a
-given class.  This can be spelled as ``Type[C]`` where ``C`` is a
+given class.  This can be spelled as :py:class:`Type[C] <typing.Type>` where ``C`` is a
 class.  In other words, when ``C`` is the name of a class, using ``C``
 to annotate an argument declares that the argument is an instance of
-``C`` (or of a subclass of ``C``), but using ``Type[C]`` as an
+``C`` (or of a subclass of ``C``), but using :py:class:`Type[C] <typing.Type>` as an
 argument annotation declares that the argument is a class object
 deriving from ``C`` (or ``C`` itself).
 
@@ -634,7 +634,7 @@ you pass it the right class object:
        # (Here we could write the user object to a database)
        return user
 
-How would we annotate this function?  Without ``Type[]`` the best we
+How would we annotate this function?  Without :py:class:`~typing.Type` the best we
 could do would be:
 
 .. code-block:: python
@@ -650,7 +650,7 @@ doesn't see that the ``buyer`` variable has type ``ProUser``:
    buyer = new_user(ProUser)
    buyer.pay()  # Rejected, not a method on User
 
-However, using ``Type[]`` and a type variable with an upper bound (see
+However, using :py:class:`~typing.Type` and a type variable with an upper bound (see
 :ref:`type-variable-upper-bound`) we can do better:
 
 .. code-block:: python
@@ -670,7 +670,7 @@ Now mypy will infer the correct type of the result when we call
 
 .. note::
 
-   The value corresponding to ``Type[C]`` must be an actual class
+   The value corresponding to :py:class:`Type[C] <typing.Type>` must be an actual class
    object that's a subtype of ``C``.  Its constructor must be
    compatible with the constructor of ``C``.  If ``C`` is a type
    variable, its upper bound must be a class object.
@@ -688,7 +688,7 @@ strings. This can be challenging to do in a codebase intended to run in
 both Python 2 and Python 3 since ``str`` means something different in both
 versions and ``unicode`` is not a keyword in Python 3.
 
-To help solve this issue, use ``typing.Text`` which is aliased to
+To help solve this issue, use :py:class:`~typing.Text` which is aliased to
 ``unicode`` in Python 2 and to ``str`` in Python 3. This allows you to
 indicate that a function should accept only unicode strings in a
 cross-compatible way:
@@ -702,7 +702,7 @@ cross-compatible way:
 
 In other cases, you may want to write a function that will work with any
 kind of string but will not let you mix two different string types. To do
-so use ``typing.AnyStr``:
+so use :py:data:`~typing.AnyStr`:
 
 .. code-block:: python
 
@@ -728,17 +728,17 @@ Generators
 **********
 
 A basic generator that only yields values can be annotated as having a return
-type of either ``Iterator[YieldType]`` or ``Iterable[YieldType]``. For example:
+type of either :py:class:`Iterator[YieldType] <typing.Iterator>` or :py:class:`Iterable[YieldType] <typing.Iterable>`. For example:
 
 .. code-block:: python
 
    def squares(n: int) -> Iterator[int]:
        for i in range(n):
            yield i * i
 
-If you want your generator to accept values via the ``send`` method or return
+If you want your generator to accept values via the :py:meth:`~generator.send` method or return
 a value, you should use the
-``Generator[YieldType, SendType, ReturnType]`` generic type instead. For example:
+:py:class:`Generator[YieldType, SendType, ReturnType] <typing.Generator>` generic type instead. For example:
 
 .. code-block:: python
 
@@ -749,7 +749,7 @@ a value, you should use the
        return 'Done'
 
 Note that unlike many other generics in the typing module, the ``SendType`` of
-``Generator`` behaves contravariantly, not covariantly or invariantly.
+:py:class:`~typing.Generator` behaves contravariantly, not covariantly or invariantly.
 
 If you do not plan on receiving or returning values, then set the ``SendType``
 or ``ReturnType`` to ``None``, as appropriate. For example, we could have
@@ -762,6 +762,6 @@ annotated the first example as the following:
            yield i * i
 
 This is slightly different from using ``Iterable[int]`` or ``Iterator[int]``,
-since generators have ``close()``, ``send()``, and ``throw()`` methods that
+since generators have :py:meth:`~generator.close`, :py:meth:`~generator.send`, and :py:meth:`~generator.throw` methods that
 generic iterables don't. If you will call these methods on the returned
-generator, use the ``Generator`` type instead of ``Iterable`` or ``Iterator``.
+generator, use the :py:class:`~typing.Generator` type instead of :py:class:`~typing.Iterable` or :py:class:`~typing.Iterator`.

docs/source/metaclasses.rst

@@ -6,11 +6,11 @@ Metaclasses
 A :ref:`metaclass <python:metaclasses>` is a class that describes
 the construction and behavior of other classes, similarly to how classes
 describe the construction and behavior of objects.
-The default metaclass is ``type``, but it's possible to use other metaclasses.
-Metaclasses allows one to create "a different kind of class", such as Enums,
-NamedTuples and singletons.
+The default metaclass is :py:class:`type`, but it's possible to use other metaclasses.
+Metaclasses allows one to create "a different kind of class", such as
+:py:class:`~enum.Enum`\s, :py:class:`~typing.NamedTuple`\s and singletons.
 
-Mypy has some special understanding of ``ABCMeta`` and ``EnumMeta``.
+Mypy has some special understanding of :py:class:`~abc.ABCMeta` and ``EnumMeta``.
 
 .. _defining:
 
@@ -32,7 +32,7 @@ In Python 2, the syntax for defining a metaclass is different:
     class A(object):
         __metaclass__ = M
 
-Mypy also supports using :py:func:`six.with_metaclass`
+Mypy also supports using :py:func:`six.with_metaclass` and :py:func:`@six.add_metaclass <six.add_metaclass>`
 to define metaclass in a portable way:
 
 .. code-block:: python
@@ -103,4 +103,4 @@ so it's better not to combine metaclasses and class hierarchies:
 * Mypy does not understand dynamically-computed metaclasses,
   such as ``class A(metaclass=f()): ...``
 * Mypy does not and cannot understand arbitrary metaclass code.
-* Mypy only recognizes subclasses of ``type`` as potential metaclasses.
+* Mypy only recognizes subclasses of :py:class:`type` as potential metaclasses.

docs/source/python2.rst

@@ -15,7 +15,7 @@ Run mypy in Python 2 mode by using the ``--py2`` option::
 To run your program, you must have the ``typing`` module in your
 Python 2 module search path. Use ``pip install typing`` to install the
 module. This also works for Python 3 versions prior to 3.5 that don't
-include ``typing`` in the standard library.
+include :py:mod:`typing` in the standard library.
 
 The example below illustrates the Python 2 function type annotation
 syntax. This syntax is also valid in Python 3 mode:

docs/source/python36.rst

@@ -8,7 +8,7 @@ Mypy has supported all language features new in Python 3.6 starting with mypy
 type checking.
 
 Syntax for variable annotations (:pep:`526`)
----------------------------------------------------------------------------------------
+--------------------------------------------
 
 Python 3.6 introduced a new syntax for variable annotations (in
 global, class and local scopes).  There are two variants of the
@@ -23,7 +23,7 @@ syntax, with or without an initializer expression:
 .. _class-var:
 
 You can also mark names intended to be used as class variables with
-``ClassVar``.  In a pinch you can also use ClassVar in ``# type``
+:py:data:`~typing.ClassVar`. In a pinch you can also use :py:data:`~typing.ClassVar` in ``# type``
 comments.  Example:
 
 .. code-block:: python
@@ -49,7 +49,7 @@ Asynchronous generators (:pep:`525`) and comprehensions (:pep:`530`)
 
 Python 3.6 allows coroutines defined with ``async def`` (:pep:`492`) to be
 generators, i.e. contain ``yield`` expressions. It also introduced a syntax for
-asynchronous comprehensions. This example uses the ``AsyncIterator`` type to
+asynchronous comprehensions. This example uses the :py:class:`~typing.AsyncIterator` type to
 define an async generator:
 
 .. code-block:: python

docs/source/running_mypy.rst

@@ -371,7 +371,7 @@ This is computed from the following items:
 
 .. note::
 
-    You cannot point to a PEP 561 package via the MYPYPATH, it must be
+    You cannot point to a :pep:`561` package via the ``MYPYPATH``, it must be
     installed (see :ref:`PEP 561 support <installed-packages>`)
 
 For sources given on the command line, the path is adjusted by crawling

docs/source/stubs.rst

@@ -103,7 +103,7 @@ Python code -- for example, when writing methods in
 
 The recommended style is to use ellipses to do so, just like in
 stub files. It is also considered stylistically acceptable to
-throw a ``NotImplementedError`` in cases where the user of the
+throw a :py:exc:`NotImplementedError` in cases where the user of the
 code may accidentally call functions with no actual logic.
 
 You can also elide default arguments as long as the function body
@@ -137,5 +137,4 @@ For example:
     Ellipsis expressions are legal syntax in Python 3 only. This means
     it is not possible to elide default arguments in Python 2 code.
     You can still elide function bodies in Python 2 by using either
-    the ``pass`` statement or by throwing a ``NotImplementedError``.
-
+    the ``pass`` statement or by throwing a :py:exc:`NotImplementedError`.

docs/source/supported_python_features.rst

@@ -13,7 +13,7 @@ or module outside its definition -- but only if this is visible to the
 type checker. This only affects static checking, as mypy performs no
 additional type checking at runtime. You can easily work around
 this. For example, you can use dynamically typed code or values with
-``Any`` types, or you can use ``setattr`` or other introspection
+``Any`` types, or you can use :py:func:`setattr` or other introspection
 features. However, you need to be careful if you decide to do this. If
 used indiscriminately, you may have difficulty using static typing
 effectively, since the type checker cannot see functions defined at

docs/source/type_inference_and_annotations.rst

@@ -65,7 +65,7 @@ possible with the comment syntax:
 
    The best way to think about this is that the type annotation sets the
    type of the variable, not the type of the expression. To force the
-   type of an expression you can use ``cast(<type>, <expression>)``.
+   type of an expression you can use :py:func:`cast(\<type\>, \<expression\>) <typing.cast>`.
 
 Explicit types for collections
 ******************************
@@ -114,7 +114,7 @@ assignment could result in non-int values stored in a list of ``int``:
        l.append('x')
        print(k[-1])  # Ouch; a string in List[int]
 
-Other container types like ``Dict`` and ``Set`` behave similarly. We
+Other container types like :py:class:`~typing.Dict` and :py:class:`~typing.Set` behave similarly. We
 will discuss how you can work around this in :ref:`variance`.
 
 You can still run the above program; it prints ``x``. This illustrates