diff --git a/docs/source/additional_features.rst b/docs/source/additional_features.rst index 33af4d3bb393..c4922d330ae4 100644 --- a/docs/source/additional_features.rst +++ b/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__ `) 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 `, 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__ ` will be replaced by ``Any``. * :ref:`Validator decorators ` and `default decorators `_ @@ -348,16 +348,16 @@ Extended Callable types This feature is deprecated. You can use :ref:`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 diff --git a/docs/source/casts.rst b/docs/source/casts.rst index 741513744a3e..61eeb3062625 100644 --- a/docs/source/casts.rst +++ b/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 diff --git a/docs/source/class_basics.rst b/docs/source/class_basics.rst index ea16264dcace..347daee9a1db 100644 --- a/docs/source/class_basics.rst +++ b/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__ ` 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__ ` 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__ ` methods **if at least one argument is annotated**. For +example, in the following classes :py:meth:`__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__ ` 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] ` 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 ` (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 ` 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 ` 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 diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 673c6f144bd3..07ea54ae2b0a 100644 --- a/docs/source/command_line.rst +++ b/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] ` and :py:class:`Dict[str, str] `). ``--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.)