Various doc updates (#3314)

* flexible Callable
* --cache-dir=/dev/null
* --quick mode
* Refresh usage message
* ClassVar

Author: gvanrossum

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 <incremental>`.  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

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 <incremental>`.
 
 - ``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 <incremental>`.
+  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 <quick>`.
 
 - ``show_error_context`` (Boolean, default False) shows
   context notes before errors.

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

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 <https://www.python.org/dev/peps/pep-0498>`_)
 ---------------------------------------------------------------------------------