New upstream version 0.761

Metadata-Version: 2.1

Name: mypy

Version: 0.750

Version: 0.761

Summary: Optional static typing for Python

Home-page: http://www.mypy-lang.org/

Author: Jukka Lehtosalo

Due to the way git submodules work, you'll have to do

```

  git submodule update typeshed

  git submodule update mypy/typeshed

```

whenever you change branches, merge, rebase, or pull.

.. code-block:: python

   from mypy_extensions import TypedDict

   from typing_extensions import TypedDict

   Movie = TypedDict('Movie', {'name': str, 'year': int})

.. note::

   You need to install ``mypy_extensions`` using pip to use ``TypedDict``:

   Unless you are on Python 3.8 or newer (where ``TypedDict`` is available in

   standard library :py:mod:`typing` module) you need to install ``typing_extensions``

   using pip to use ``TypedDict``:

   .. code-block:: text

       python3 -m pip install --upgrade mypy-extensions

      python3 -m pip install --upgrade typing-extensions

   Or, if you are using Python 2:

   .. code-block:: text

       pip install --upgrade mypy-extensions

      pip install --upgrade typing-extensions

Totality

--------

.. code-block:: python

   from mypy_extensions import TypedDict

   from typing_extensions import TypedDict

   class Movie(TypedDict):

       name: str

.. note::

    The mypy daemon is experimental. In particular, the command-line

    interface may change in future mypy releases.

    The command-line of interface of mypy daemon may change in future mypy

    releases.

.. note::

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),

* ``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 :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

  diagnostic and exits with ``0`` if there is a running daemon.

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

   This is available for the ``start``, ``restart``, and ``run`` commands.

.. option:: --update FILE

   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 and files that depend on them.  However, if you use this option

   (and/or :option:`--remove`), mypy assumes that only the explicitly

   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.

   *Note:* This option is never required and is only available for

   performance tuning.

.. option:: --remove FILE

   Remove ``FILE`` from the set of files being checked. This option may be

   repeated. This is only available for the

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

.. option:: --fswatcher-dump-file FILE

   Collect information about the current internal file state. This is

   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

   change.

.. option:: --perf-stats-file FILE

   Write performance profiling information to ``FILE``. This is only available

   for the ``check``, ``recheck``, and ``run`` commands.

Static inference of annotations

*******************************

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 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, or to propose function

signatures.

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)

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

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 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 some ``Any`` types.

The following flags customize various aspects of the ``dmypy suggest``

command.

.. option:: --json

   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

      [{"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 FRACTION

   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 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 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

   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

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

.. TODO: Add similar sections about go to definition, find usages, and

   reveal type when added, and then move this to a separate file.

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

   You can't mix paths and :option:`-m`/:option:`-p` options in the same stubgen

   invocation.

Stubgen applies heuristics to avoid generating stubs for submodules

that include tests or vendored third-party packages.

Specifying how to generate stubs

********************************

.. option:: --no-import

    Don't try to import modules. Instead use mypy's normal search mechanism to find

    Don't try to import modules. Instead only use mypy's normal search mechanism to find

    sources. This does not support C extension modules. This flag also disables

    runtime introspection functionality, which mypy uses to find the value of

    ``__all__``. As result the set of exported imported names in stubs may be

    incomplete. This flag is generally only useful when importing a module generates

    an error for some reason.

    incomplete. This flag is generally only useful when importing a module causes

    unwanted side effects, such as the running of tests. Stubgen tries to skip test

    modules even without this option, but this does not always work.

.. option:: --parse-only

    Include definitions that are considered private in stubs (with names such

    as ``_foo`` with single leading underscore and no trailing underscores).

.. option:: --export-less

    Don't export all names imported from other modules within the same package.

    Instead, only export imported names that are not referenced in the module

    that contains the import.

.. option:: --search-path PATH

    Specify module search directories, separated by colons (only used if

    ``./out`` directory. The output directory will be created if it doesn't

    exist. Existing stubs in the output directory will be overwritten without

    warning.

.. option:: -v, --verbose

    Produce more verbose output.

.. option:: -q, --quiet

    Produce less verbose output.