From 3a931bf3270a10cb277e55352ebdd28698af0ffd Mon Sep 17 00:00:00 2001
From: Jukka Lehtosalo <jukka.lehtosalo@iki.fi>
Date: Fri, 29 Nov 2019 16:07:16 +0000
Subject: [PATCH 1/6] Various small tweaks to mypy daemon documentation

Document the `recheck` command and update wording in several
places.
---
 docs/source/mypy_daemon.rst | 120 ++++++++++++++++++++----------------
 1 file changed, 68 insertions(+), 52 deletions(-)

diff --git a/docs/source/mypy_daemon.rst b/docs/source/mypy_daemon.rst
index bb0c87126920..54166ac5fe10 100644
--- a/docs/source/mypy_daemon.rst
+++ b/docs/source/mypy_daemon.rst
@@ -87,6 +87,11 @@ require more precise control over the lifetime of the daemon process:
 * ``dmypy check <files>`` checks a set of files using an already
   running daemon.
 
+* ``dmypy recheck`` checks the same set of files as the most recent
+  ``check`` or ``recheck`` command. (You can also use the ``--update``
+  and ``--remove`` options to alter the set of files, and to define
+  which files should be processed.)
+
 * ``dmypy status`` checks whether a daemon is running. It prints a
   diagnostic and exits with ``0`` if there is a running daemon.
 
@@ -101,60 +106,68 @@ Additional daemon flags
 
    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.
+   connection. The default path is ``.dmypy.json`` in the current working
+   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.
+   crashes, since the server traceback is not always printed by the client.
+   This is available for the ``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.
+   This is available for the ``start``, ``restart``, and ``run`` commands.
 
-.. option:: --fswatcher-dump-file FILE
+.. option:: --update 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.
+   Re-check ``FILE``, or add it to the set of files being
+   checked. This option may be repeated. This is only available for
+   the ``recheck`` command.  By default, mypy checks all files for
+   changes since the previous run.  However, if you use this option
+   (and/or ``--remove``), mypy assumes that only the explicitly
+   specified files need to be reprocessed. This is only useful to
+   speed up mypy if you type check thousands of files, and use an
+   external, fast file system watcher, such as `watchman`_ or
+   `watchdog`_, to determine which files need to be type checked.
+   *Note:* This option is never required and is only available for
+   performance tuning.
 
-.. option:: --perf-stats-file FILE
+.. option:: --remove FILE
 
-   Write performance profiling information to ``FILE``. Only available
-   for ``check``, ``recheck``, and ``run`` commands.
+   Remove ``FILE`` from the set of files being checked. This option may be
+   repeated. This is only available for the
+   ``recheck`` command. See ``--update`` above for when this may be useful.
+   *Note:* This option is never required and is only available for performance
+   tuning.
 
-.. option:: --update FILE
+.. option:: --fswatcher-dump-file 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.
+   Collect information about the current internal file state. This is
+   only available for the ``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:: --remove FILE
+.. option:: --perf-stats-file 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.
+   Write performance profiling information to ``FILE``. This is only available
+   for the ``check``, ``recheck``, and ``run`` commands.
 
 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).
+The mypy daemon supports (as an experimental feature) statically inferring
+draft function and method type annotations. Use ``dmypy suggest FUNCTION`` to
+generate a draft signature in the format
+``(param_type_1, param_type_2, ...) -> ret_type`` (types are included for all
+arguments, including keyword-only arguments, ``*args`` and ``**kwargs``).
 
-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.
+This is a low-level feature intended to be used by editor integations,
+IDEs, and other tools (for example, the `mypy plugin for PyCharm`_),
+to automatically add annotations to source files.
 
 In this example, the function ``format_id()`` has no annotation:
 
@@ -165,26 +178,29 @@ In this example, the function ``format_id()`` has no annotation:
 
    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:
+``dymyp suggest`` uses call sites, return statements, and other heuristics (such as
+looking for signatures in base classes) to infer that ``format_id()`` accepts
+an ``int`` argument and returns a ``str``. Use ``dmypy suggest module.format_id`` to
+display a suggested signature for the function.
+
+More generally, the target function may be specified in two ways:
 
 * 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
+* By its location in a source file, 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``
+This command can also be used to find a more precise alternative for an existing,
+imprecise annotation with ``Any`` types.
+
+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:
+   Output the signature as JSON, so that `PyAnnotate`_ can read it and add
+   the signature to the source file. Here is what the JSON looks like:
 
    .. code-block:: python
 
@@ -196,7 +212,7 @@ command.
 
 .. option:: --no-errors
 
-   Only produce suggestions that cause no errors in the checked code. By default
+   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
@@ -204,31 +220,31 @@ command.
    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
+.. option:: --flex-any FRACTION
 
-   Allow ``Any`` types in suggested signature if they go above a certain score.
-   Scores are from ``0`` (same as ``--no-any``) to ``1``.
+   Only allow some fraction of types in the suggested signature to be ``Any`` types.
+   The fraction ranges from ``0`` (same as ``--no-any``) to ``1``.
 
 .. option:: --try-text
 
-   Try using ``unicode`` wherever ``str`` is inferred. This flag may be useful
+   Try also 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
+   This will produce a list with line numbers 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
+   Use a dummy name 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.
+   couldn'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``).
+   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.

From 1dd5c2d07dba2602d900976d4991b6a605a0eee1 Mon Sep 17 00:00:00 2001
From: Jukka Lehtosalo <jukka.lehtosalo@iki.fi>
Date: Fri, 29 Nov 2019 17:55:36 +0000
Subject: [PATCH 2/6] More updates

---
 docs/source/mypy_daemon.rst | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/docs/source/mypy_daemon.rst b/docs/source/mypy_daemon.rst
index 54166ac5fe10..e96f10fc9d0b 100644
--- a/docs/source/mypy_daemon.rst
+++ b/docs/source/mypy_daemon.rst
@@ -123,12 +123,12 @@ Additional daemon flags
 .. option:: --update FILE
 
    Re-check ``FILE``, or add it to the set of files being
-   checked. This option may be repeated. This is only available for
-   the ``recheck`` command.  By default, mypy checks all files for
-   changes since the previous run.  However, if you use this option
+   checked (and check it). This option may be repeated, and it's only available for
+   the ``recheck`` command.  By default, mypy finds and checks all files changed
+   since the previous run.  However, if you use this option
    (and/or ``--remove``), mypy assumes that only the explicitly
    specified files need to be reprocessed. This is only useful to
-   speed up mypy if you type check thousands of files, and use an
+   speed up mypy if you type check a very large number of files, and use an
    external, fast file system watcher, such as `watchman`_ or
    `watchdog`_, to determine which files need to be type checked.
    *Note:* This option is never required and is only available for
@@ -145,7 +145,7 @@ Additional daemon flags
 .. option:: --fswatcher-dump-file FILE
 
    Collect information about the current internal file state. This is
-   only available for the ``status`` command. This will dump a JSON to
+   only available for the ``status`` command. This will dump 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
@@ -165,9 +165,10 @@ generate a draft signature in the format
 ``(param_type_1, param_type_2, ...) -> ret_type`` (types are included for all
 arguments, including keyword-only arguments, ``*args`` and ``**kwargs``).
 
-This is a low-level feature intended to be used by editor integations,
+This is a low-level feature intended to be used by editor integrations,
 IDEs, and other tools (for example, the `mypy plugin for PyCharm`_),
-to automatically add annotations to source files.
+to automatically add annotations to source files, or to propose function
+signatures.
 
 In this example, the function ``format_id()`` has no annotation:
 
@@ -178,21 +179,21 @@ In this example, the function ``format_id()`` has no annotation:
 
    root = format_id(0)
 
-``dymyp suggest`` uses call sites, return statements, and other heuristics (such as
+``dymypy suggest`` uses call sites, return statements, and other heuristics (such as
 looking for signatures in base classes) to infer that ``format_id()`` accepts
 an ``int`` argument and returns a ``str``. Use ``dmypy suggest module.format_id`` to
-display a suggested signature for the function.
+print the suggested signature for the function.
 
 More generally, the target function may be specified in two ways:
 
-* By its fully qualified name, i.e. ``[package.]module.[class.]function``
+* By its fully qualified name, i.e. ``[package.]module.[class.]function``.
 
 * By its location in a source file, 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 a more precise alternative for an existing,
-imprecise annotation with ``Any`` types.
+imprecise annotation with some ``Any`` types.
 
 The following flags customize various aspects of the ``dmypy suggest``
 command.

From e4b5fe5d9bbb7fd525b44ed3a86c91b7adac796e Mon Sep 17 00:00:00 2001
From: Jukka Lehtosalo <jukka.lehtosalo@iki.fi>
Date: Fri, 29 Nov 2019 17:58:44 +0000
Subject: [PATCH 3/6] Add cross references

---
 docs/source/mypy_daemon.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/source/mypy_daemon.rst b/docs/source/mypy_daemon.rst
index e96f10fc9d0b..ec8b89493d0c 100644
--- a/docs/source/mypy_daemon.rst
+++ b/docs/source/mypy_daemon.rst
@@ -88,8 +88,8 @@ require more precise control over the lifetime of the daemon process:
   running daemon.
 
 * ``dmypy recheck`` checks the same set of files as the most recent
-  ``check`` or ``recheck`` command. (You can also use the ``--update``
-  and ``--remove`` options to alter the set of files, and to define
+  ``check`` or ``recheck`` command. (You can also use the :option:`--update`
+  and :option:`--remove` options to alter the set of files, and to define
   which files should be processed.)
 
 * ``dmypy status`` checks whether a daemon is running. It prints a
@@ -126,7 +126,7 @@ Additional daemon flags
    checked (and check it). This option may be repeated, and it's only available for
    the ``recheck`` command.  By default, mypy finds and checks all files changed
    since the previous run.  However, if you use this option
-   (and/or ``--remove``), mypy assumes that only the explicitly
+   (and/or :option:`--remove`), mypy assumes that only the explicitly
    specified files need to be reprocessed. This is only useful to
    speed up mypy if you type check a very large number of files, and use an
    external, fast file system watcher, such as `watchman`_ or
@@ -138,7 +138,7 @@ Additional daemon flags
 
    Remove ``FILE`` from the set of files being checked. This option may be
    repeated. This is only available for the
-   ``recheck`` command. See ``--update`` above for when this may be useful.
+   ``recheck`` command. See :option:`--update` above for when this may be useful.
    *Note:* This option is never required and is only available for performance
    tuning.
 

From 5024bbf1ef870b6c632673a4fcff66987924b7e2 Mon Sep 17 00:00:00 2001
From: Jukka Lehtosalo <jukka.lehtosalo@iki.fi>
Date: Fri, 29 Nov 2019 20:00:41 +0000
Subject: [PATCH 4/6] Update docs/source/mypy_daemon.rst

Co-Authored-By: Ivan Levkivskyi <levkivskyi@gmail.com>
---
 docs/source/mypy_daemon.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/mypy_daemon.rst b/docs/source/mypy_daemon.rst
index ec8b89493d0c..0a1ef716282d 100644
--- a/docs/source/mypy_daemon.rst
+++ b/docs/source/mypy_daemon.rst
@@ -125,7 +125,7 @@ Additional daemon flags
    Re-check ``FILE``, or add it to the set of files being
    checked (and check it). This option may be repeated, and it's only available for
    the ``recheck`` command.  By default, mypy finds and checks all files changed
-   since the previous run.  However, if you use this option
+   since the previous run and files that depend on them.  However, if you use this option
    (and/or :option:`--remove`), mypy assumes that only the explicitly
    specified files need to be reprocessed. This is only useful to
    speed up mypy if you type check a very large number of files, and use an

From 43e4398797b22adf8feacd7823da2dc97aafcf00 Mon Sep 17 00:00:00 2001
From: Jukka Lehtosalo <jukka.lehtosalo@iki.fi>
Date: Fri, 29 Nov 2019 20:00:51 +0000
Subject: [PATCH 5/6] Update docs/source/mypy_daemon.rst

Co-Authored-By: Ivan Levkivskyi <levkivskyi@gmail.com>
---
 docs/source/mypy_daemon.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/mypy_daemon.rst b/docs/source/mypy_daemon.rst
index 0a1ef716282d..ca23c95c7345 100644
--- a/docs/source/mypy_daemon.rst
+++ b/docs/source/mypy_daemon.rst
@@ -130,7 +130,7 @@ Additional daemon flags
    specified files need to be reprocessed. This is only useful to
    speed up mypy if you type check a very large number of files, and use an
    external, fast file system watcher, such as `watchman`_ or
-   `watchdog`_, to determine which files need to be type checked.
+   `watchdog`_, to determine which files got edited or deleted.
    *Note:* This option is never required and is only available for
    performance tuning.
 

From 24a8bb0cf3cf26e369fcfde573ad41b07561498c Mon Sep 17 00:00:00 2001
From: Jukka Lehtosalo <jukka.lehtosalo@iki.fi>
Date: Fri, 29 Nov 2019 20:01:01 +0000
Subject: [PATCH 6/6] Update docs/source/mypy_daemon.rst

Co-Authored-By: Ivan Levkivskyi <levkivskyi@gmail.com>
---
 docs/source/mypy_daemon.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/mypy_daemon.rst b/docs/source/mypy_daemon.rst
index ca23c95c7345..c3db1824f00c 100644
--- a/docs/source/mypy_daemon.rst
+++ b/docs/source/mypy_daemon.rst
@@ -127,7 +127,7 @@ Additional daemon flags
    the ``recheck`` command.  By default, mypy finds and checks all files changed
    since the previous run and files that depend on them.  However, if you use this option
    (and/or :option:`--remove`), mypy assumes that only the explicitly
-   specified files need to be reprocessed. This is only useful to
+   specified files have changed. This is only useful to
    speed up mypy if you type check a very large number of files, and use an
    external, fast file system watcher, such as `watchman`_ or
    `watchdog`_, to determine which files got edited or deleted.

<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>pFad - Phonifier reborn</title>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8' />
</head>
<body>
<h1>Pfad - The Proxy pFad of &#169; 2024 Garber Painting. All rights reserved.</h1>


<!-- Disclaimer -->
<p>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.</p>
<br>
<p>Alternative Proxies:</p><p><a href="http://rainy.clevelandohioweatherforecast.com/php-proxy/index.php?q=https://patch-diff.githubusercontent.com/raw/python/mypy/pull/8041.patch" target="_blank">Alternative Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/index.php?u=https://patch-diff.githubusercontent.com/raw/python/mypy/pull/8041.patch" target="_blank">pFad Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v3index.php?u=https://patch-diff.githubusercontent.com/raw/python/mypy/pull/8041.patch" target="_blank">pFad v3 Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v4index.php?u=https://patch-diff.githubusercontent.com/raw/python/mypy/pull/8041.patch" target="_blank">pFad v4 Proxy</a></p></body>
</html>