diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index dcd46dcd9aa7..3dfb124bf36c 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -14,14 +14,15 @@ flag (or its long form ``--help``):: [--disallow-untyped-calls] [--disallow-untyped-defs] [--check-untyped-defs] [--disallow-subclassing-any] [--warn-incomplete-stub] [--warn-redundant-casts] - [--warn-no-return] [--warn-unused-ignores] [--show-error-context] - [-i] [--cache-dir DIR] [--strict-optional] - [--strict-optional-whitelist [GLOB [GLOB ...]]] [--strict] + [--no-warn-no-return] [--warn-return-any] [--warn-unused-ignores] + [--show-error-context] [-i] [--quick-and-dirty] [--cache-dir DIR] + [--strict-optional] + [--strict-optional-whitelist [GLOB [GLOB ...]]] [--junit-xml JUNIT_XML] [--pdb] [--show-traceback] [--stats] [--inferstats] [--custom-typing MODULE] [--custom-typeshed-dir DIR] [--scripts-are-modules] [--config-file CONFIG_FILE] [--show-column-numbers] - [--find-occurrences CLASS.MEMBER] + [--find-occurrences CLASS.MEMBER] [--strict] [--strict-boolean] [--cobertura-xml-report DIR] [--html-report DIR] [--linecount-report DIR] [--linecoverage-report DIR] [--memory-xml-report DIR] [--old-html-report DIR] @@ -298,10 +299,31 @@ Here are some more useful flags: the base class even though that may not actually be the case. This flag makes mypy raise an error instead. -- ``--incremental`` is an experimental option that enables incremental - type checking. When enabled, mypy caches results from previous runs +.. _incremental: + +- ``--incremental`` is an experimental option that enables a module + cache. When enabled, mypy caches results from previous runs to speed up type checking. Incremental mode can help when most parts - of your program haven't changed since the previous mypy run. + of your program haven't changed since the previous mypy run. A + companion flag is ``--cache-dir DIR``, which specifies where the + cache files are written. By default this is ``.mypy_cache`` in the + current directory. While the cache is only read in incremental + mode, it is written even in non-incremental mode, in order to "warm" + the cache. To disable writing the cache, use + ``--cache-dir=/dev/null`` (UNIX) or ``--cache-dir=nul`` (Windows). + Cache files belonging to a different mypy version are ignored. + +.. _quick: + +- ``--quick-and-dirty`` is an experimental, unsafe variant of + :ref:`incremental mode `. Quick mode is faster than + regular incremental mode, because it only re-checks modules that + were modified since their cache file was last written (regular + incremental mode also re-checks all modules that depend on one or + more modules that were re-checked). Quick mode is unsafe because it + may miss problems caused by a change in a dependency. Quick mode + updates the cache, but regular incremental mode ignores cache files + written by quick mode. - ``--python-version X.Y`` will make mypy typecheck your code as if it were run under Python version X.Y. Without this option, mypy will default to using diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 504d62b05347..0accd57411cd 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -93,11 +93,17 @@ The following global flags may only be set in the global section - ``dump_inference_stats`` (Boolean, default False) dumps stats about type inference. -- ``incremental`` (Boolean, default False) enables the experimental - module cache. +- ``incremental`` (Boolean, default False) enables :ref:`incremental + mode `. - ``cache_dir`` (string, default ``.mypy_cache``) stores module cache - info in the given folder in incremental mode. + info in the given folder in :ref:`incremental mode `. + The cache is only read in incremental mode, but it is always written + unless the value is set to ``/dev/null`` (UNIX) or ``nul`` + (Windows). + +- ``quick_and_dirty`` (Boolean, default False) enables :ref:`quick + mode `. - ``show_error_context`` (Boolean, default False) shows context notes before errors. diff --git a/docs/source/kinds_of_types.rst b/docs/source/kinds_of_types.rst index 67b4b42a5074..f7c784c4b406 100644 --- a/docs/source/kinds_of_types.rst +++ b/docs/source/kinds_of_types.rst @@ -188,6 +188,130 @@ using bidirectional type inference: If you want to give the argument or return value types explicitly, use an ordinary, perhaps nested function definition. +Extended Callable types +*********************** + +As an experimental mypy extension, you can specify ``Callable`` types +that support keyword arguments, optional arguments, and more. Where +you specify the arguments of a 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``: + +.. code-block:: python + + from typing import Callable + from mypy_extensions import (Arg, DefaultArg, NamedArg, + DefaultNamedArg, VarArg, KwArg) + + def func(__a: int, # This convention is for nameless arguments + b: int, + c: int = 0, + *args: int, + d: int, + e: int = 0, + **kwargs: int) -> int: + ... + + F = Callable[[int, # Or Arg(int) + Arg(int, 'b'), + DefaultArg(int, 'c'), + VarArg(int), + NamedArg(int, 'd'), + DefaultNamedArg(int, 'e'), + KwArg(int)], + int] + + f: F = func + +Argument specifiers are special function calls that can specify the +following aspects of an argument: + +- its type (the only thing that the basic format supports) + +- its name (if it has one) + +- whether it may be omitted + +- whether it may or must be passed using a keyword + +- whether it is a ``*args`` argument (representing the remaining + positional arguments) + +- whether it is a ``**kwargs`` argument (representing the remaining + keyword arguments) + +The following functions are available in ``mypy_extensions`` for this +purpose: + +.. code-block:: python + + def Arg(type=Any, name=None): + # A normal, mandatory, positional argument. + # If the name is specified it may be passed as a keyword. + + def DefaultArg(type=Any, name=None): + # An optional positional argument (i.e. with a default value). + # If the name is specified it may be passed as a keyword. + + def NamedArg(type=Any, name=None): + # A mandatory keyword-only argument. + + def DefaultNamedArg(type=Any, name=None): + # An optional keyword-only argument (i.e. with a default value). + + def VarArg(type=Any): + # A *args-style variadic positional argument. + # A single VarArg() specifier represents all remaining + # positional arguments. + + def KwArg(type=Any): + # A **kwargs-style variadic keyword argument. + # A single KwArg() specifier represents all remaining + # keyword arguments. + +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 + +.. code-block:: python + + MyFunc = Callable[[int, str, int], float] + +is equivalent to the following: + +.. code-block:: python + + MyFunc = Callable[[Arg(int), Arg(str), Arg(int)], float] + +A ``Callable`` with unspecified argument types, such as + +.. code-block:: python + + MyOtherFunc = Callable[..., int] + +is (roughly) equivalent to + +.. code-block:: python + + MyOtherFunc = Callable[[VarArg(), KwArg()], int] + +.. note:: + + This feature is experimental. Details of the implementation may + change and there may be unknown limitations. **IMPORTANT:** + Each of the functions above currently just returns its ``type`` + argument, so the information contained in the argument specifiers + is not available at runtime. This limitation is necessary for + backwards compatibility with the existing ``typing.py`` module as + present in the Python 3.5+ standard library and distributed via + PyPI. + .. _union-types: Union types diff --git a/docs/source/python36.rst b/docs/source/python36.rst index 46a0bbf68713..12ec35ca6b3a 100644 --- a/docs/source/python36.rst +++ b/docs/source/python36.rst @@ -16,6 +16,7 @@ now have type annotations using either of the two forms: .. code-block:: python + from typing import Optional foo: Optional[int] bar: List[str] = [] @@ -26,6 +27,27 @@ Mypy fully supports this syntax, interpreting them as equivalent to foo = None # type: Optional[int] bar = [] # type: List[str] +An additional feature defined in PEP 526 is also supported: you can +mark names intended to be used as class variables with ``ClassVar``. +In a pinch you can also use ClassVar in ``# type`` comments. +Example: + +.. code-block:: python + + from typing import ClassVar + + class C: + x: int # instance variable + y: ClassVar[int] # class variable + z = None # type: ClassVar[int] + + def foo(self) -> None: + self.x = 0 # OK + self.y = 0 # Error: Cannot assign to class variable "y" via instance + + C.y = 0 # This is OK + + Literal string formatting (`PEP 498 `_) ---------------------------------------------------------------------------------