Crossreferences to standard library in mypy docs (#7652)

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

Author: hoefling

docs/source/additional_features.rst

@@ -26,7 +26,7 @@ They can be defined using the :py:func:`@dataclasses.dataclass
     test = Application("Testing...")  # OK
     bad = Application("Testing...", "with plugin")  # Error: List[str] expected
 
-Mypy will detect special methods (such as ``__lt__``) depending on the flags used to
+Mypy will detect special methods (such as :py:meth:`__lt__ <object.__lt__>`) depending on the flags used to
 define dataclasses. For example:
 
 .. code-block:: python
@@ -72,10 +72,10 @@ and :pep:`557`.
 Caveats/Known Issues
 ====================
 
-Some functions in the ``dataclasses`` module, such as ``replace()`` and ``asdict()``,
+Some functions in the :py:mod:`dataclasses` module, such as :py:func:`~dataclasses.replace` and :py:func:`~dataclasses.asdict`,
 have imprecise (too permissive) types. This will be fixed in future releases.
 
-Mypy does not yet recognize aliases of ``dataclasses.dataclass``, and will
+Mypy does not yet recognize aliases of :py:func:`dataclasses.dataclass <dataclasses.dataclass>`, and will
 probably never recognize dynamically computed decorators. The following examples
 do **not** work:
 
@@ -140,7 +140,7 @@ If you're using ``auto_attribs=True`` you must use variable annotations.
         three: int = attr.ib(8)
 
 Typeshed has a couple of "white lie" annotations to make type checking
-easier. ``attr.ib`` and ``attr.Factory`` actually return objects, but the
+easier. :py:func:`attr.ib` and :py:class:`attr.Factory` actually return objects, but the
 annotation says these return the types that they expect to be assigned to.
 That enables this to work:
 
@@ -175,7 +175,7 @@ Caveats/Known Issues
 
 * Currently, ``converter`` only supports named functions.  If mypy finds something else it
   will complain about not understanding the argument and the type annotation in
-  ``__init__`` will be replaced by ``Any``.
+  :py:meth:`__init__ <object.__init__>` will be replaced by ``Any``.
 
 * :ref:`Validator decorators <attrs:examples_validators>`
   and `default decorators <http://www.attrs.org/en/stable/examples.html#defaults>`_
@@ -348,16 +348,16 @@ Extended Callable types
    This feature is deprecated.  You can use
    :ref:`callback protocols <callback_protocols>` as a replacement.
 
-As an experimental mypy extension, you can specify ``Callable`` types
+As an experimental mypy extension, you can specify :py:data:`~typing.Callable` types
 that support keyword arguments, optional arguments, and more.  When
-you specify the arguments of a Callable, you can choose to supply just
+you specify the arguments of a :py:data:`~typing.Callable`, you can choose to supply just
 the type of a nameless positional argument, or an "argument specifier"
 representing a more complicated form of argument.  This allows one to
 more closely emulate the full range of possibilities given by the
 ``def`` statement in Python.
 
 As an example, here's a complicated function definition and the
-corresponding ``Callable``:
+corresponding :py:data:`~typing.Callable`:
 
 .. code-block:: python
 
@@ -434,7 +434,7 @@ purpose:
 In all cases, the ``type`` argument defaults to ``Any``, and if the
 ``name`` argument is omitted the argument has no name (the name is
 required for ``NamedArg`` and ``DefaultNamedArg``).  A basic
-``Callable`` such as
+:py:data:`~typing.Callable` such as
 
 .. code-block:: python
 
@@ -446,7 +446,7 @@ is equivalent to the following:
 
    MyFunc = Callable[[Arg(int), Arg(str), Arg(int)], float]
 
-A ``Callable`` with unspecified argument types, such as
+A :py:data:`~typing.Callable` with unspecified argument types, such as
 
 .. code-block:: python
 

docs/source/casts.rst

@@ -6,7 +6,7 @@ Casts and type assertions
 Mypy supports type casts that are usually used to coerce a statically
 typed value to a subtype. Unlike languages such as Java or C#,
 however, mypy casts are only used as hints for the type checker, and they
-don't perform a runtime type check. Use the function ``cast`` to perform a
+don't perform a runtime type check. Use the function :py:func:`~typing.cast` to perform a
 cast:
 
 .. code-block:: python

docs/source/class_basics.rst

@@ -24,7 +24,7 @@ initialized within the class. Mypy infers the types of attributes:
    a.y = 3  # Error: 'A' has no attribute 'y'
 
 This is a bit like each class having an implicitly defined
-``__slots__`` attribute. This is only enforced during type
+:py:data:`__slots__ <object.__slots__>` attribute. This is only enforced during type
 checking and not when your program is running.
 
 You can declare types of variables in the class body explicitly using
@@ -40,7 +40,7 @@ a type annotation:
 
 As in Python generally, a variable defined in the class body can be used
 as a class or an instance variable. (As discussed in the next section, you
-can override this with a ``ClassVar`` annotation.)
+can override this with a :py:data:`~typing.ClassVar` annotation.)
 
 Type comments work as well, if you need to support Python versions earlier
 than 3.6:
@@ -81,11 +81,11 @@ to it explicitly using ``self``:
 Annotating ``__init__`` methods
 *******************************
 
-The ``__init__`` method is somewhat special -- it doesn't return a
+The :py:meth:`__init__ <object.__init__>` method is somewhat special -- it doesn't return a
 value.  This is best expressed as ``-> None``.  However, since many feel
 this is redundant, it is allowed to omit the return type declaration
-on ``__init__`` methods **if at least one argument is annotated**.  For
-example, in the following classes ``__init__`` is considered fully
+on :py:meth:`__init__ <object.__init__>` methods **if at least one argument is annotated**.  For
+example, in the following classes :py:meth:`__init__ <object.__init__>` is considered fully
 annotated:
 
 .. code-block:: python
@@ -98,7 +98,7 @@ annotated:
        def __init__(self, arg: int):
            self.var = arg
 
-However, if ``__init__`` has no annotated arguments and no return type
+However, if :py:meth:`__init__ <object.__init__>` has no annotated arguments and no return type
 annotation, it is considered an untyped method:
 
 .. code-block:: python
@@ -111,7 +111,7 @@ annotation, it is considered an untyped method:
 Class attribute annotations
 ***************************
 
-You can use a ``ClassVar[t]`` annotation to explicitly declare that a
+You can use a :py:data:`ClassVar[t] <typing.ClassVar>` annotation to explicitly declare that a
 particular attribute should not be set on instances:
 
 .. code-block:: python
@@ -134,7 +134,7 @@ particular attribute should not be set on instances:
    PyPI). If you use Python 2.7, you can import it from ``typing``.
 
 It's not necessary to annotate all class variables using
-``ClassVar``. An attribute without the ``ClassVar`` annotation can
+:py:data:`~typing.ClassVar`. An attribute without the :py:data:`~typing.ClassVar` annotation can
 still be used as a class variable. However, mypy won't prevent it from
 being used as an instance variable, as discussed previously:
 
@@ -148,13 +148,13 @@ being used as an instance variable, as discussed previously:
   a = A()
   a.x = 1  # Also OK
 
-Note that ``ClassVar`` is not a class, and you can't use it with
-``isinstance()`` or ``issubclass()``. It does not change Python
+Note that :py:data:`~typing.ClassVar` is not a class, and you can't use it with
+:py:func:`isinstance` or :py:func:`issubclass`. It does not change Python
 runtime behavior -- it's only for type checkers such as mypy (and
 also helpful for human readers).
 
 You can also omit the square brackets and the variable type in
-a ``ClassVar`` annotation, but this might not do what you'd expect:
+a :py:data:`~typing.ClassVar` annotation, but this might not do what you'd expect:
 
 .. code-block:: python
 
@@ -165,7 +165,7 @@ In this case the type of the attribute will be implicitly ``Any``.
 This behavior will change in the future, since it's surprising.
 
 .. note::
-   A ``ClassVar`` type parameter cannot include type variables:
+   A :py:data:`~typing.ClassVar` type parameter cannot include type variables:
    ``ClassVar[T]`` and ``ClassVar[List[T]]``
    are both invalid if ``T`` is a type variable (see :ref:`generic-classes`
    for more about type variables).
@@ -232,10 +232,10 @@ effect at runtime:
 Abstract base classes and multiple inheritance
 **********************************************
 
-Mypy supports Python abstract base classes (ABCs). Abstract classes
+Mypy supports Python :doc:`abstract base classes <library/abc>` (ABCs). Abstract classes
 have at least one abstract method or property that must be implemented
 by any *concrete* (non-abstract) subclass. You can define abstract base
-classes using the ``abc.ABCMeta`` metaclass and the ``abc.abstractmethod``
+classes using the :py:class:`abc.ABCMeta` metaclass and the :py:func:`@abc.abstractmethod <abc.abstractmethod>`
 function decorator. Example:
 
 .. code-block:: python
@@ -263,11 +263,11 @@ function decorator. Example:
 
 .. note::
 
-   In Python 2.7 you have to use ``@abc.abstractproperty`` to define
+   In Python 2.7 you have to use :py:func:`@abc.abstractproperty <abc.abstractproperty>` to define
    an abstract property.
 
 Note that mypy performs checking for unimplemented abstract methods
-even if you omit the ``ABCMeta`` metaclass. This can be useful if the
+even if you omit the :py:class:`~abc.ABCMeta` metaclass. This can be useful if the
 metaclass would cause runtime metaclass conflicts.
 
 Since you can't create instances of ABCs, they are most commonly used in

docs/source/command_line.rst

@@ -129,17 +129,17 @@ imports.
 ``--python-executable EXECUTABLE``
     This flag will have mypy collect type information from :pep:`561`
     compliant packages installed for the Python executable ``EXECUTABLE``.
-    If not provided, mypy will use :pep:`561` compliant packages installed for
+    If not provided, mypy will use PEP 561 compliant packages installed for
     the Python executable running mypy.
 
-    See :ref:`installed-packages` for more on making :pep:`561` compliant packages.
+    See :ref:`installed-packages` for more on making PEP 561 compliant packages.
 
 ``--no-site-packages``
     This flag will disable searching for :pep:`561` compliant packages. This
     will also disable searching for a usable Python executable.
 
     Use this  flag if mypy cannot find a Python executable for the version of
-    Python being checked, and you don't need to use :pep:`561` typed packages.
+    Python being checked, and you don't need to use PEP 561 typed packages.
     Otherwise, use ``--python-executable``.
 
 ``--no-silence-site-packages``
@@ -213,7 +213,7 @@ The following options are available:
     This flag disallows all expressions in the module that have type ``Any``.
     If an expression of type ``Any`` appears anywhere in the module
     mypy will output an error unless the expression is immediately
-    used as an argument to ``cast`` or assigned to a variable with an
+    used as an argument to :py:func:`~typing.cast` or assigned to a variable with an
     explicit type annotation.
 
     In addition, declaring a variable of type ``Any``
@@ -230,9 +230,9 @@ The following options are available:
 
 ``--disallow-any-generics``
     This flag disallows usage of generic types that do not specify explicit
-    type parameters. Moreover, built-in collections (such as ``list`` and
-    ``dict``) become disallowed as you should use their aliases from the typing
-    module (such as ``List[int]`` and ``Dict[str, str]``).
+    type parameters. Moreover, built-in collections (such as :py:class:`list` and
+    :py:class:`dict`) become disallowed as you should use their aliases from the :py:mod:`typing`
+    module (such as :py:class:`List[int] <typing.List>` and :py:class:`Dict[str, str] <typing.Dict>`).
 
 ``--disallow-subclassing-any``
     This flag reports an error whenever a class subclasses a value of
@@ -292,7 +292,7 @@ For more details, see :ref:`no_strict_optional`.
 
 ``--no-implicit-optional``
     This flag causes mypy to stop treating arguments with a ``None``
-    default value as having an implicit ``Optional[...]`` type.
+    default value as having an implicit :py:data:`~typing.Optional` type.
 
     For example, by default mypy will assume that the ``x`` parameter
     is of type ``Optional[int]`` in the code snippet below since
@@ -312,7 +312,7 @@ For more details, see :ref:`no_strict_optional`.
             print(x)
 
 ``--no-strict-optional``
-    This flag disables strict checking of ``Optional[...]``
+    This flag disables strict checking of :py:data:`~typing.Optional`
     types and ``None`` values. With this option, mypy doesn't
     generally check the use of ``None`` values -- they are valid
     everywhere. See :ref:`no_strict_optional` for more about this feature.
@@ -362,7 +362,7 @@ potentially problematic or redundant in some way.
 
 ``--warn-return-any``
     This flag causes mypy to generate a warning when returning a value
-    with type ``Any`` from a function declared with a non- ``Any`` return type.
+    with type ``Any`` from a function declared with a non-``Any`` return type.
 
 ``--warn-unreachable``
     This flag will make mypy report an error whenever it encounters
@@ -387,7 +387,7 @@ potentially problematic or redundant in some way.
     unreachable" warning will be silenced in exactly two cases:
 
     1.  When the unreachable statement is a ``raise`` statement, is an
-        ``assert False`` statement, or calls a function that has the ``NoReturn``
+        ``assert False`` statement, or calls a function that has the :py:data:`~typing.NoReturn`
         return type hint. In other words, when the unreachable statement
         throws an error or terminates the program in some way.
     2.  When the unreachable statement was *intentionally* marked as unreachable
@@ -578,7 +578,7 @@ in developing or debugging mypy internals.
 
 ``--custom-typing MODULE``
     This flag lets you use a custom module as a substitute for the
-    ``typing`` module.
+    :py:mod:`typing` module.
 
 ``--custom-typeshed-dir DIR``
     This flag specifies the directory where mypy looks for typeshed
@@ -673,10 +673,10 @@ Miscellaneous
     This flag will give command line arguments that appear to be
     scripts (i.e. files whose name does not end in ``.py``)
     a module name derived from the script name rather than the fixed
-    name ``__main__``.
+    name :py:mod:`__main__`.
 
     This lets you check more than one script in a single mypy invocation.
-    (The default ``__main__`` is technically more correct, but if you
+    (The default :py:mod:`__main__` is technically more correct, but if you
     have many scripts that import a large package, the behavior enabled
     by this flag is often more convenient.)