Skip to content

Commit b7465de

Browse files
authored
Improve daemon docs; add docs for dmypy suggest (python#8032)
1 parent b5f4df9 commit b7465de

File tree

2 files changed

+151
-7
lines changed

2 files changed

+151
-7
lines changed

docs/source/mypy_daemon.rst

Lines changed: 146 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,8 @@ changed a few files. You can use :ref:`remote caching <remote-cache>`
6363
to speed up the initial run. The speedup can be significant if
6464
you have a large codebase.
6565

66-
Additional features
67-
*******************
66+
Daemon client commands
67+
**********************
6868

6969
While ``dmypy run`` is sufficient for most uses, some workflows
7070
(ones using :ref:`remote caching <remote-cache>`, perhaps),
@@ -94,6 +94,145 @@ Use ``dmypy --help`` for help on additional commands and command-line
9494
options not discussed here, and ``dmypy <command> --help`` for help on
9595
command-specific options.
9696

97+
Additional daemon flags
98+
***********************
99+
100+
.. option:: --status-file FILE
101+
102+
Use ``FILE`` as the status file for storing daemon runtime state. This is
103+
normally a JSON file that contains information about daemon process and
104+
connection. Default is ``.dmypy.json`` in current directory.
105+
106+
.. option:: --log-file FILE
107+
108+
Direct daemon stdout/stderr to ``FILE``. This is useful for debugging daemon
109+
crashes, since the server traceback may be not printed to client stderr.
110+
Only available for ``start``, ``restart``, and ``run`` commands.
111+
112+
.. option:: --timeout TIMEOUT
113+
114+
Automatically shut down server after ``TIMEOUT`` seconds of inactivity.
115+
Only available for ``start``, ``restart``, and ``run`` commands.
116+
117+
.. option:: --fswatcher-dump-file FILE
118+
119+
Collect information about the current file state. Only available for
120+
``status`` command. This will dump a JSON to ``FILE`` in the format
121+
``{path: [modification_time, size, content_hash]}``. This is useful for
122+
debugging the built-in file system watcher. *Note:* this is an internal
123+
flag and the format may change.
124+
125+
.. option:: --perf-stats-file FILE
126+
127+
Write performance profiling information to ``FILE``. Only available
128+
for ``check``, ``recheck``, and ``run`` commands.
129+
130+
.. option:: --update FILE
131+
132+
Files in the run to add or check again, may be repeated. Default: all
133+
files from the previous run. Only available for ``recheck`` command.
134+
This is useful when type checking thousands of files and using external
135+
fast file system watcher, like `watchman`_ or `watchdog`_, to speed
136+
things up. *Note:* this option is never required and is only available
137+
for performance tuning.
138+
139+
.. option:: --remove FILE
140+
141+
Files to remove from the run, may be repeated. Only available for
142+
``recheck`` command. This flag an be used as an optimization to avoid
143+
looking at all source files for deletions. *Note:* this option is never
144+
required and is only available for performance tuning.
145+
146+
Static inference of annotations
147+
*******************************
148+
149+
Mypy daemon supports (as an experimental feature) statically inferring
150+
a draft type annotation for a given function or method. Running
151+
``dmypy suggest FUNCTION`` will produce a suggested signature in the format
152+
``(param_type_1, param_type_2, ...) -> ret_type`` (including named and
153+
star arguments).
154+
155+
This low level command may be used by editors, IDEs, or similar tools, like
156+
`mypy plugin for PyCharm`_, to propose an annotation to user and/or to insert
157+
the annotation into a source file.
158+
159+
In this example, the function ``format_id()`` has no annotation:
160+
161+
.. code-block:: python
162+
163+
def format_id(user):
164+
return "User: {}".format(user)
165+
166+
root = format_id(0)
167+
168+
Mypy can use call sites and return statements (plus extra heuristics such as
169+
a signature in superclass for methods) to infer that ``format_id()`` takes
170+
an ``int`` and returns a ``str``. To get a suggested signature for a function,
171+
use ``dmypy suggest FUNCTION``, where the function may be specified in
172+
either of two forms:
173+
174+
* By its fully qualified name, i.e. ``[package.]module.[class.]function``
175+
176+
* By its textual location, i.e. ``/path/to/file.py:line``. The path can be
177+
absolute or relative, and ``line`` can refer to any line number within
178+
the function body.
179+
180+
This command can also be used to find an improvement for an existing (imprecise)
181+
annotation. The following flags customize various aspects of the ``dmypy suggest``
182+
command.
183+
184+
.. option:: --json
185+
186+
Output the signature as JSON, so that `PyAnnotate`_ can use it to apply
187+
a suggestion to file. An example JSON looks like this:
188+
189+
.. code-block:: python
190+
191+
[{"func_name": "example.format_id",
192+
"line": 1,
193+
"path": "/absolute/path/to/example.py",
194+
"samples": 0,
195+
"signature": {"arg_types": ["int"], "return_type": "str"}}]
196+
197+
.. option:: --no-errors
198+
199+
Only produce suggestions that cause no errors in the checked code. By default
200+
mypy will try to find the most precise type, even if it causes some type errors.
201+
202+
.. option:: --no-any
203+
204+
Only produce suggestions that don't contain ``Any`` types. By default mypy
205+
proposes the most precise signature found, even if it contains ``Any`` types.
206+
207+
.. option:: --flex-any PERCENTAGE
208+
209+
Allow ``Any`` types in suggested signature if they go above a certain score.
210+
Scores are from ``0`` (same as ``--no-any``) to ``1``.
211+
212+
.. option:: --try-text
213+
214+
Try using ``unicode`` wherever ``str`` is inferred. This flag may be useful
215+
for annotating Python 2/3 straddling code.
216+
217+
.. option:: --callsites
218+
219+
Only find call sites for a given function instead of suggesting a type.
220+
This will produce a list including textual locations and types of actual
221+
arguments for each call: ``/path/to/file.py:line: (arg_type_1, arg_type_2, ...)``.
222+
223+
.. option:: --use-fixme NAME
224+
225+
A dummy name to use instead of plain ``Any`` for types that cannot
226+
be inferred. This may be useful to emphasize to a user that a given type
227+
can't be inferred and needs to be entered manually.
228+
229+
.. option:: --max-guesses NUMBER
230+
231+
Set the maximum number of types to try for a function (default ``64``).
232+
233+
.. TODO: Add similar sections about go to definition, find usages, and
234+
reveal type when added, and then move this to a separate file.
235+
97236
Limitations
98237
***********
99238

@@ -102,3 +241,8 @@ Limitations
102241
limitation. This can be defined
103242
through the command line or through a
104243
:ref:`configuration file <config-file>`.
244+
245+
.. _watchman: https://facebook.github.io/watchman/
246+
.. _watchdog: https://pypi.org/project/watchdog/
247+
.. _PyAnnotate: https://github.com/dropbox/pyannotate
248+
.. _mypy plugin for PyCharm: https://github.com/dropbox/mypy-PyCharm-plugin

mypy/dmypy/client.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -72,14 +72,14 @@ def __init__(self, prog: str) -> None:
7272
p.add_argument('-v', '--verbose', action='store_true', help="Print detailed status")
7373
p.add_argument('-q', '--quiet', action='store_true', help=argparse.SUPPRESS) # Deprecated
7474
p.add_argument('--junit-xml', help="Write junit.xml to the given file")
75-
p.add_argument('--perf-stats-file', help='write telemetry information to the given file')
75+
p.add_argument('--perf-stats-file', help='write performance information to the given file')
7676
p.add_argument('files', metavar='FILE', nargs='+', help="File (or directory) to check")
7777

7878
run_parser = p = subparsers.add_parser('run', formatter_class=AugmentedHelpFormatter,
7979
help="Check some files, [re]starting daemon if necessary")
8080
p.add_argument('-v', '--verbose', action='store_true', help="Print detailed status")
8181
p.add_argument('--junit-xml', help="Write junit.xml to the given file")
82-
p.add_argument('--perf-stats-file', help='write telemetry information to the given file')
82+
p.add_argument('--perf-stats-file', help='write performance information to the given file')
8383
p.add_argument('--timeout', metavar='TIMEOUT', type=int,
8484
help="Server shutdown timeout (in seconds)")
8585
p.add_argument('--log-file', metavar='FILE', type=str,
@@ -88,13 +88,13 @@ def __init__(self, prog: str) -> None:
8888
help="Regular mypy flags and files (precede with --)")
8989

9090
recheck_parser = p = subparsers.add_parser('recheck', formatter_class=AugmentedHelpFormatter,
91-
help="Re-check the previous list of files, with optional modifications (requires daemon).")
91+
help="Re-check the previous list of files, with optional modifications (requires daemon)")
9292
p.add_argument('-v', '--verbose', action='store_true', help="Print detailed status")
9393
p.add_argument('-q', '--quiet', action='store_true', help=argparse.SUPPRESS) # Deprecated
9494
p.add_argument('--junit-xml', help="Write junit.xml to the given file")
95-
p.add_argument('--perf-stats-file', help='write telemetry information to the given file')
95+
p.add_argument('--perf-stats-file', help='write performance information to the given file')
9696
p.add_argument('--update', metavar='FILE', nargs='*',
97-
help="Files in the run to add or check again (default: all from previous run)..")
97+
help="Files in the run to add or check again (default: all from previous run)")
9898
p.add_argument('--remove', metavar='FILE', nargs='*',
9999
help="Files to remove from the run")
100100

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy