New upstream version 0.600

Metadata-Version: 2.1

Name: mypy

Version: 0.590

Version: 0.600

Summary: Optional static typing for Python

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

Author: Jukka Lehtosalo

Additional features

-------------------

Several mypy features are not currently covered by this tutorial,

including the following:

- inheritance between generic classes

- compatibility and subtyping of generic types, including covariance of generic types

- ``super()``

This section discusses various features outside core mypy features.

.. _attrs_package:

* Method definitions added by mypy currently overwrite any existing method

  definitions.

.. _remote-cache:

Using a remote cache to speed up mypy runs

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

Mypy performs type checking *incrementally*, reusing results from

previous runs to speed up successive runs. If you are type checking a

large codebase, mypy can still be sometimes slower than desirable. For

example, if you create a new branch based on a much more recent commit

than the target of the previous mypy run, mypy may have to

process almost every file, as a large fraction of source files may

have changed. This can also happen after you've rebased a local

branch.

Mypy supports using a *remote cache* to improve performance in cases

such as the above.  In a large codebase, remote caching can sometimes

speed up mypy runs by a factor of 10, or more.

Mypy doesn't include all components needed to set

this up -- generally you will have to perform some simple integration

with your Continuous Integration (CI) or build system to configure

mypy to use a remote cache. This discussion assumes you have a CI

system set up for the mypy build you want to speed up, and that you

are using a central git repository. Generalizing to different

environments should not be difficult.

Here are the main components needed:

* A shared repository for storing mypy cache files for all landed commits.

* CI build that uploads mypy incremental cache files to the shared repository for

  each commit for which the CI build runs.

* A wrapper script around mypy that developers use to run mypy with remote

  caching enabled.

Below we discuss each of these components in some detail.

Shared repository for cache files

=================================

You need a repository that allows you to upload mypy cache files from

your CI build and make the cache files available for download based on

a commit id.  A simple approach would be to produce an archive of the

``.mypy_cache`` directory (which contains the mypy cache data) as a

downloadable *build artifact* from your CI build (depending on the

capabilities of your CI system).  Alternatively, you could upload the

data to a web server or to S3, for example.

Continuous Integration build

============================

The CI build would run a regular mypy build and create an archive containing

the ``.mypy_cache`` directory produced by the build. Finally, it will produce

the cache as a build artifact or upload it to a repository where it is

accessible by the mypy wrapper script.

Your CI script might work like this:

* Run mypy normally. This will generate cache data under the

  ``.mypy_cache`` directory.

* Create a tarball from the ``.mypy_cache`` directory.

* Determine the current git master branch commit id (say, using

  ``git rev-parse HEAD``).

* Upload the tarball to the shared repository with a name derived from the

  commit id.

Mypy wrapper script

===================

The wrapper script is used by developers to run mypy locally during

development instead of invoking mypy directly.  The wrapper first

populates the local ``.mypy_cache`` directory from the shared

repository and then runs a normal incremental build.

The wrapper script needs some logic to determine the most recent

central repository commit (by convention, the ``origin/master`` branch

for git) the local development branch is based on. In a typical git

setup you can do it like this:

.. code::

    git merge-base HEAD origin/master

The next step is to download the cache data (contents of the

``.mypy_cache`` directory) from the shared repository based on the

commit id of the merge base produced by the git command above. The

script will decompress the data so that mypy will start with a fresh

``.mypy_cache``. Finally, the script runs mypy normally. And that's all!

Caching with mypy daemon

========================

You can also use remote caching with the :ref:`mypy daemon <mypy_daemon>`.

The remote cache will significantly speed up the the first ``dmypy check``

run after starting or restarting the daemon.

The mypy daemon requires extra fine-grained dependency data in

the cache files which aren't included by default. To use caching with

the mypy daemon, use the ``--cache-fine-grained`` option in your CI

build::

    $ mypy --cache-fine-grained <args...>

This flag adds extra information for the daemon to the cache. In

order to use this extra information, you will also need to use the

``--use-fine-grained-cache`` option with ``dymypy start`` or

``dmypy restart``. Example::

    $ dmypy start -- --use-fine-grained-cache <options...>

Now your first ``dmypy check`` run should be much faster, as it can use

cache information to avoid processing the whole program.

Refinements

===========

There are several optional refinements that may improve things further,

at least if your codebase is hundreds of thousands of lines or more:

* If the wrapper script determines that the merge base hasn't changed

  from a previous run, there's no need to download the cache data and

  it's better to instead reuse the existing local cache data.

* If you use the mypy daemon, you may want to restart the daemon each time

  after the merge base or local branch has changed to avoid processing a

  potentially large number of changes in an incremental build, as this can

  be much slower than downloading cache data and restarting the daemon.

* If the current local branch is based on a very recent master commit,

  the remote cache data may not yet be available for that commit, as

  there will necessarily be some latency to build the cache files. It

  may be a good idea to look for cache data for, say, the 5 latest

  master commits and use the most recent data that is available.

* If the remote cache is not accessible for some reason (say, from a public

  network), the script can still fall back to a normal incremental build.

* You can have multiple local cache directories for different local branches

  using the ``--cache-dir`` option. If the user switches to an existing

  branch where downloaded cache data is already available, you can continue

  to use the existing cache data instead of redownloading the data.

* You can set up your CI build to use a remote cache to speed up the

  CI build. This would be particularly useful if each CI build starts

  from a fresh state without access to cache files from previous

  builds. It's still recommended to run a full, non-incremental

  mypy build to create the cache data, as repeatedly updating cache

  data incrementally could result in drift over a long time period (due

  to a mypy caching issue, perhaps).

              [--warn-unused-ignores] [--warn-unused-configs]

              [--show-error-context] [--no-implicit-optional] [--no-incremental]

              [--quick-and-dirty] [--cache-dir DIR] [--cache-fine-grained]

              [--skip-version-check] [--strict-optional]

              [--skip-version-check] [--no-strict-optional]

              [--strict-optional-whitelist [GLOB [GLOB ...]]]

              [--always-true NAME] [--always-false NAME] [--junit-xml JUNIT_XML]

              [--pdb] [--show-traceback] [--stats] [--inferstats]

- ``--ignore-missing-imports`` suppresses error messages about imports

  that cannot be resolved (see :ref:`follow-imports` for some examples).

- ``--strict-optional`` enables strict checking of ``Optional[...]``

  types and ``None`` values. Without this option, mypy doesn't

- ``--no-strict-optional`` disables strict checking of ``Optional[...]``

  types and ``None`` values. With this option, mypy doesn't

  generally check the use of ``None`` values -- they are valid

  everywhere. See :ref:`strict_optional` for more about this feature.

  This flag will become the default in the near future.

  everywhere. See :ref:`no_strict_optional` for more about this feature.

  **Note:** Strict optional checking was enabled by default starting in

  mypy 0.600, and in previous versions it had to be explicitly enabled

  using ``--strict-optional`` (which is still accepted).

- ``--disallow-untyped-defs`` reports an error whenever it encounters

  a function definition without type annotations.

  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.

  ignored.  This flag can be useful for controlling cache use when using

  :ref:`remote caching <remote-cache>`.

.. _quick-mode:

- ``--config-file CONFIG_FILE`` causes configuration settings to be

  read from the given file.  By default settings are read from ``mypy.ini``

  or ``setup.cfg`` in the current directory.  Settings override mypy's

  built-in defaults and command line flags can override settings.

  See :ref:`config-file` for the syntax of configuration files.

  or ``setup.cfg`` in the current directory, or ``.mypy.ini`` in the user home

  directory.  Settings override mypy's built-in defaults and command line flags

  can override settings. See :ref:`config-file` for the syntax of configuration

  files.

- ``--junit-xml JUNIT_XML`` will make mypy generate a JUnit XML test

  result document with type checking results. This can make it easier

  If you don't know what types to add, you can use ``Any``, but beware:

- **One of the values involved has type ``Any``.** Extending the above

- **One of the values involved has type 'Any'.** Extending the above

  example, if we were to leave out the annotation for ``a``, we'd get

  no error:

  clarity about the latter use ``--follow-imports=error``.  You can

  read up about these and other useful flags in :ref:`command-line`.

- **A function annotated as returning a non-optional type returns ``None``

- **A function annotated as returning a non-optional type returns 'None'

  and mypy doesn't complain**.

  .. code-block:: python

      def foo() -> str:

          return None  # No error!

  By default, the ``None`` value is considered compatible with everything. See

  :ref:`optional` for details on strict optional checking, which allows mypy to

  check ``None`` values precisely, and will soon become default.

  You may have disabled strict optional checking (see

  :ref:`no_strict_optional` for more).

.. _silencing_checker:

    if we did have a stub available for ``frobnicate`` then mypy would

    ignore the ``# type: ignore`` comment and typecheck the stub as usual.

Unexpected errors about 'None' and/or 'Optional' types

------------------------------------------------------

Starting from mypy 0.600, mypy uses

:ref:`strict optional checking <strict_optional>` by default,

and ``None`` is not compatible with non-optional types.  It's

easy to switch back to the older behavior where ``None`` was

compatible with arbitrary types (see :ref:`no_strict_optional`).

Types of empty collections

--------------------------

===========================

Mypy supports reading configuration settings from a file.  By default

it uses the file ``mypy.ini`` (with fallback to ``setup.cfg``) in the

current directory; the ``--config-file`` command-line flag can be used to

read a different file instead (see :ref:`--config-file <config-file-flag>`).

it uses the file ``mypy.ini`` with fallback to ``setup.cfg`` in the current

directory, or ``.mypy.ini`` in the user home directory if none of them are

found; the ``--config-file`` command-line flag can be used to read a different

file instead (see :ref:`--config-file <config-file-flag>`).

It is important to understand that there is no merging of configuration

files, as it would lead to ambiguity.  The ``--config-file`` flag

  the global flags. The ``setup.cfg`` file is an exception to this.

- Additional sections named ``[mypy-PATTERN1,PATTERN2,...]`` may be

  present, where ``PATTERN1``, ``PATTERN2`` etc. are `fnmatch patterns

  <https://docs.python.org/3.6/library/fnmatch.html>`_

  separated by commas.  These sections specify additional flags that

  only apply to *modules* whose name matches at least one of the patterns.

  present, where ``PATTERN1``, ``PATTERN2``, etc., are comma-separated

  patterns of the form ``dotted_module_name`` or ``dotted_module_name.*``.

  These sections specify additional flags that only apply to *modules*

  whose name matches at least one of the patterns.

  A pattern of the form ``dotted_module_name`` matches only the named module,

  while ``dotted_module_name.*`` matches ``dotted_module_name`` and any

  submodules (so ``foo.bar.*`` would match all of ``foo.bar``,

  ``foo.bar.baz``, and ``foo.bar.baz.quux``).

.. note::

  per-module sections in the config file that didn't match any

  files processed in the current run.

- ``strict_optional`` (Boolean, default False) enables experimental

  strict Optional checks.

- ``scripts_are_modules`` (Boolean, default False) makes script ``x``

  become module ``x`` instead of ``__main__``.  This is useful when

  checking multiple scripts in a single run.

.. note::

   If multiple pattern sections match a module they are processed in

   order of their occurrence in the config file.

   If multiple pattern sections match a module, the options from the

   most specific section are used where they disagree.  This means

   that ``foo.bar`` will take values from sections with the patterns

   ``foo.bar``, ``foo.bar.*``, and ``foo.*``, but when they specify

   different values, it will use values from ``foo.bar`` before

   ``foo.bar.*`` before ``foo.*``.

- ``follow_imports`` (string, default ``normal``) directs what to do

  with imports when the imported module is found as a ``.py`` file and

- ``almost_silent`` (Boolean, deprecated) equivalent to

  ``follow_imports=skip``.

- ``strict_optional`` (Boolean, default True) enables or disables

  strict Optional checks. If False, mypy treats ``None`` as

  compatible with every type.

  **Note::** This was False by default

  in mypy versions earlier than 0.600.

- ``disallow_any_unimported`` (Boolean, default false) disallows usage of types that come

  from unfollowed imports (such types become aliases for ``Any``).