Improve daemon docs; add docs for dmypy suggest (#8032)

Author: ilevkivskyi

docs/source/mypy_daemon.rst

@@ -63,8 +63,8 @@ changed a few files. You can use :ref:`remote caching <remote-cache>`
 to speed up the initial run. The speedup can be significant if
 you have a large codebase.
 
-Additional features
-*******************
+Daemon client commands
+**********************
 
 While ``dmypy run`` is sufficient for most uses, some workflows
 (ones using :ref:`remote caching <remote-cache>`, perhaps),
@@ -94,6 +94,145 @@ Use ``dmypy --help`` for help on additional commands and command-line
 options not discussed here, and ``dmypy <command> --help`` for help on
 command-specific options.
 
+Additional daemon flags
+***********************
+
+.. option:: --status-file FILE
+
+   Use ``FILE`` as the status file for storing daemon runtime state. This is
+   normally a JSON file that contains information about daemon process and
+   connection. Default is ``.dmypy.json`` in current directory.
+
+.. option:: --log-file FILE
+
+   Direct daemon stdout/stderr to ``FILE``. This is useful for debugging daemon
+   crashes, since the server traceback may be not printed to client stderr.
+   Only available for ``start``, ``restart``, and ``run`` commands.
+
+.. option:: --timeout TIMEOUT
+
+   Automatically shut down server after ``TIMEOUT`` seconds of inactivity.
+   Only available for ``start``, ``restart``, and ``run`` commands.
+
+.. option:: --fswatcher-dump-file FILE
+
+   Collect information about the current file state. Only available for
+   ``status`` command. This will dump a JSON to ``FILE`` in the format
+   ``{path: [modification_time, size, content_hash]}``. This is useful for
+   debugging the built-in file system watcher. *Note:* this is an internal
+   flag and the format may change.
+
+.. option:: --perf-stats-file FILE
+
+   Write performance profiling information to ``FILE``. Only available
+   for ``check``, ``recheck``, and ``run`` commands.
+
+.. option:: --update FILE
+
+   Files in the run to add or check again, may be repeated. Default: all
+   files from the previous run. Only available for ``recheck`` command.
+   This is useful when type checking thousands of files and using external
+   fast file system watcher, like `watchman`_ or `watchdog`_, to speed
+   things up. *Note:* this option is never required and is only available
+   for performance tuning.
+
+.. option:: --remove FILE
+
+   Files to remove from the run, may be repeated. Only available for
+   ``recheck`` command. This flag an be used as an optimization to avoid
+   looking at all source files for deletions. *Note:* this option is never
+   required and is only available for performance tuning.
+
+Static inference of annotations
+*******************************
+
+Mypy daemon supports (as an experimental feature) statically inferring
+a draft type annotation for a given function or method. Running
+``dmypy suggest FUNCTION`` will produce a suggested signature in the format
+``(param_type_1, param_type_2, ...) -> ret_type`` (including named and
+star arguments).
+
+This low level command may be used by editors, IDEs, or similar tools, like
+`mypy plugin for PyCharm`_, to propose an annotation to user and/or to insert
+the annotation into a source file.
+
+In this example, the function ``format_id()`` has no annotation:
+
+.. code-block:: python
+
+   def format_id(user):
+       return "User: {}".format(user)
+
+   root = format_id(0)
+
+Mypy can use call sites and return statements (plus extra heuristics such as
+a signature in superclass for methods) to infer that ``format_id()`` takes
+an ``int`` and returns a ``str``. To get a suggested signature for a function,
+use ``dmypy suggest FUNCTION``, where the function may be specified in
+either of two forms:
+
+* By its fully qualified name, i.e. ``[package.]module.[class.]function``
+
+* By its textual location, i.e. ``/path/to/file.py:line``. The path can be
+  absolute or relative, and ``line`` can refer to any line number within
+  the function body.
+
+This command can also be used to find an improvement for an existing (imprecise)
+annotation. The following flags customize various aspects of the ``dmypy suggest``
+command.
+
+.. option:: --json
+
+   Output the signature as JSON, so that `PyAnnotate`_ can use it to apply
+   a suggestion to file. An example JSON looks like this:
+
+   .. code-block:: python
+
+      [{"func_name": "example.format_id",
+        "line": 1,
+        "path": "/absolute/path/to/example.py",
+        "samples": 0,
+        "signature": {"arg_types": ["int"], "return_type": "str"}}]
+
+.. option:: --no-errors
+
+   Only produce suggestions that cause no errors in the checked code. By default
+   mypy will try to find the most precise type, even if it causes some type errors.
+
+.. option:: --no-any
+
+   Only produce suggestions that don't contain ``Any`` types. By default mypy
+   proposes the most precise signature found, even if it contains ``Any`` types.
+
+.. option:: --flex-any PERCENTAGE
+
+   Allow ``Any`` types in suggested signature if they go above a certain score.
+   Scores are from ``0`` (same as ``--no-any``) to ``1``.
+
+.. option:: --try-text
+
+   Try using ``unicode`` wherever ``str`` is inferred. This flag may be useful
+   for annotating Python 2/3 straddling code.
+
+.. option:: --callsites
+
+   Only find call sites for a given function instead of suggesting a type.
+   This will produce a list including textual locations and types of actual
+   arguments for each call: ``/path/to/file.py:line: (arg_type_1, arg_type_2, ...)``.
+
+.. option:: --use-fixme NAME
+
+   A dummy name to use instead of plain ``Any`` for types that cannot
+   be inferred. This may be useful to emphasize to a user that a given type
+   can't be inferred and needs to be entered manually.
+
+.. option:: --max-guesses NUMBER
+
+   Set the maximum number of types to try for a function (default ``64``).
+
+.. TODO: Add similar sections about go to definition, find usages, and
+   reveal type when added, and then move this to a separate file.
+
 Limitations
 ***********
 
@@ -102,3 +241,8 @@ Limitations
   limitation. This can be defined
   through the command line or through a
   :ref:`configuration file <config-file>`.
+
+.. _watchman: https://facebook.github.io/watchman/
+.. _watchdog: https://pypi.org/project/watchdog/
+.. _PyAnnotate: https://github.com/dropbox/pyannotate
+.. _mypy plugin for PyCharm: https://github.com/dropbox/mypy-PyCharm-plugin

mypy/dmypy/client.py

@@ -72,14 +72,14 @@ def __init__(self, prog: str) -> None:
 p.add_argument('-v', '--verbose', action='store_true', help="Print detailed status")
 p.add_argument('-q', '--quiet', action='store_true', help=argparse.SUPPRESS)  # Deprecated
 p.add_argument('--junit-xml', help="Write junit.xml to the given file")
-p.add_argument('--perf-stats-file', help='write telemetry information to the given file')
+p.add_argument('--perf-stats-file', help='write performance information to the given file')
 p.add_argument('files', metavar='FILE', nargs='+', help="File (or directory) to check")
 
 run_parser = p = subparsers.add_parser('run', formatter_class=AugmentedHelpFormatter,
                                        help="Check some files, [re]starting daemon if necessary")
 p.add_argument('-v', '--verbose', action='store_true', help="Print detailed status")
 p.add_argument('--junit-xml', help="Write junit.xml to the given file")
-p.add_argument('--perf-stats-file', help='write telemetry information to the given file')
+p.add_argument('--perf-stats-file', help='write performance information to the given file')
 p.add_argument('--timeout', metavar='TIMEOUT', type=int,
                help="Server shutdown timeout (in seconds)")
 p.add_argument('--log-file', metavar='FILE', type=str,
@@ -88,13 +88,13 @@ def __init__(self, prog: str) -> None:
                help="Regular mypy flags and files (precede with --)")
 
 recheck_parser = p = subparsers.add_parser('recheck', formatter_class=AugmentedHelpFormatter,
-    help="Re-check the previous list of files, with optional modifications (requires daemon).")
+    help="Re-check the previous list of files, with optional modifications (requires daemon)")
 p.add_argument('-v', '--verbose', action='store_true', help="Print detailed status")
 p.add_argument('-q', '--quiet', action='store_true', help=argparse.SUPPRESS)  # Deprecated
 p.add_argument('--junit-xml', help="Write junit.xml to the given file")
-p.add_argument('--perf-stats-file', help='write telemetry information to the given file')
+p.add_argument('--perf-stats-file', help='write performance information to the given file')
 p.add_argument('--update', metavar='FILE', nargs='*',
-               help="Files in the run to add or check again (default: all from previous run)..")
+               help="Files in the run to add or check again (default: all from previous run)")
 p.add_argument('--remove', metavar='FILE', nargs='*',
                help="Files to remove from the run")