MANIFEST.in

@@ -3,5 +3,6 @@ recursive-include test-data *
 recursive-include extensions *
 recursive-include docs *
 include runtests.py
+include waiter.py
 include mypy_self_check.ini
 include LICENSE

PKG-INFO

 Metadata-Version: 2.1
 Name: mypy
-Version: 0.610
+Version: 0.620
 Summary: Optional static typing for Python
 Home-page: http://www.mypy-lang.org/
 Author: Jukka Lehtosalo

README.md

+<img src="http://mypy-lang.org/static/mypy_light.svg" alt="mypy logo" width="300px"/>
+
 Mypy: Optional Static Typing for Python
 =======================================
 
 [![Build Status](https://api.travis-ci.org/python/mypy.svg?branch=master)](https://travis-ci.org/python/mypy)
 [![Chat at https://gitter.im/python/typing](https://badges.gitter.im/python/typing.svg)](https://gitter.im/python/typing?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
 
 
 Got a question? Join us on Gitter!
@@ -108,7 +111,8 @@ Mypy can be integrated into popular IDEs:
 * Emacs: using [Flycheck](https://github.com/flycheck/) and [Flycheck-mypy](https://github.com/lbolla/emacs-flycheck-mypy)
 * Sublime Text: [SublimeLinter-contrib-mypy](https://github.com/fredcallaway/SublimeLinter-contrib-mypy)
 * Atom: [linter-mypy](https://atom.io/packages/linter-mypy)
-* PyCharm: PyCharm integrates [its own implementation of PEP 484](https://www.jetbrains.com/help/pycharm/2017.1/type-hinting-in-pycharm.html).
+* PyCharm: [mypy plugin](https://github.com/dropbox/mypy-PyCharm-plugin) (PyCharm integrates [its own implementation of PEP 484](https://www.jetbrains.com/help/pycharm/type-hinting-in-product.html))
+* VS Code: provides [basic integration](https://code.visualstudio.com/docs/python/linting#_mypy) with mypy.
 
 Mypy can also be integrated into [Flake8] using [flake8-mypy].
 

debian/changelog

+mypy (0.620-1) unstable; urgency=medium
+
+  * New upstream release.
+
+ -- Michael R. Crusoe <michael.crusoe@gmail.com>  Tue, 07 Aug 2018 11:09:09 -0700
+
 mypy (0.610-1) unstable; urgency=medium
 
   * New upstream release.

debian/control

@@ -17,7 +17,7 @@ Build-Depends: debhelper (>= 11),
                python3-sphinx-rtd-theme,
                python3-typed-ast (>= 1.1.0),
                python3-psutil (>= 5.4.0)
-Standards-Version: 4.1.4
+Standards-Version: 4.2.0
 Vcs-Browser: https://salsa.debian.org/med-team/mypy
 Vcs-Git: https://salsa.debian.org/med-team/mypy.git
 Homepage: http://www.mypy-lang.org/

debian/rules

@@ -2,9 +2,6 @@
 SHELL=bash  # needed for the <(echo …) process subsitution temporary file
 # tricks with help2man
 
-# Uncomment this to turn on verbose mode.
-#export DH_VERBOSE=1
-
 export PYBUILD_NAME=mypy
 export PYBUILD_DESTDIR_python3=debian/python3-$(PYBUILD_NAME)
 

docs/source/additional_features.rst

@@ -4,121 +4,72 @@ Additional features
 This section discusses various features that did not fit in naturally in one
 of the previous sections.
 
-.. _function-overloading:
+.. _dataclasses_support:
 
-Function overloading
-********************
+Dataclasses
+***********
 
-Sometimes the types in a function depend on each other in ways that
-can't be captured with a ``Union``.  For example, the ``__getitem__``
-(``[]`` bracket indexing) method can take an integer and return a
-single item, or take a ``slice`` and return a ``Sequence`` of items.
-You might be tempted to annotate it like so:
+In Python 3.7, a new ``dataclasses`` module has been added to the standard library.
+This module allows defining and customizing simple boilerplate-free classes.
+They can be defined using the ``@dataclasses.dataclass`` decorator:
 
 .. code-block:: python
 
-    from typing import Sequence, TypeVar, Union
-    T = TypeVar('T')
+    from dataclasses import dataclass, field
+
+    @dataclass
+    class Application:
+        name: str
+        plugins: List[str] = field(default_factory=list)
+
+    test = Application("Testing...")  # OK
+    bad = Application("Testing...", "with plugin")  # Error: List[str] expected
+
+Mypy will detect special methods (such as ``__lt__``) depending on the flags used to
+define dataclasses. For example:
+
+.. code-block:: python
+
+    from dataclasses import dataclass
 
-    class MyList(Sequence[T]):
-        def __getitem__(self, index: Union[int, slice]) -> Union[T, Sequence[T]]:
-            if isinstance(index, int):
-                ...  # Return a T here
-            elif isinstance(index, slice):
-                ...  # Return a sequence of Ts here
-            else:
-                raise TypeError(...)
-
-But this is too loose, as it implies that when you pass in an ``int``
-you might sometimes get out a single item and sometimes a sequence.
-The return type depends on the parameter type in a way that can't be
-expressed using a type variable.  Instead, we can use `overloading
-<https://www.python.org/dev/peps/pep-0484/#function-method-overloading>`_
-to give the same function multiple type annotations (signatures) and
-accurately describe the function's behavior.
+    @dataclass(order=True)
+    class OrderedPoint:
+        x: int
+        y: int
+
+    @dataclass(order=False)
+    class UnorderedPoint:
+        x: int
+        y: int
+
+    OrderedPoint(1, 2) < OrderedPoint(3, 4)  # OK
+    UnorderedPoint(1, 2) < UnorderedPoint(3, 4)  # Error: Unsupported operand types
+
+Dataclasses can be generic and can be used in any other way a normal
+class can be used:
 
 .. code-block:: python
 
-    from typing import overload, Sequence, TypeVar, Union
+    from dataclasses import dataclass
+    from typing import Generic, TypeVar
+
     T = TypeVar('T')
 
-    class MyList(Sequence[T]):
-
-        # The @overload definitions are just for the type checker,
-        # and overwritten by the real implementation below.
-        @overload
-        def __getitem__(self, index: int) -> T:
-            pass  # Don't put code here
-
-        # All overloads and the implementation must be adjacent
-        # in the source file, and overload order may matter:
-        # when two overloads may overlap, the more specific one
-        # should come first.
-        @overload
-        def __getitem__(self, index: slice) -> Sequence[T]:
-            pass  # Don't put code here
-
-        # The implementation goes last, without @overload.
-        # It may or may not have type hints; if it does,
-        # these are checked against the overload definitions
-        # as well as against the implementation body.
-        def __getitem__(self, index: Union[int, slice]) -> Union[T, Sequence[T]]:
-            # This is exactly the same as before.
-            if isinstance(index, int):
-                ...  # Return a T here
-            elif isinstance(index, slice):
-                ...  # Return a sequence of Ts here
-            else:
-                raise TypeError(...)
-
-Calls to overloaded functions are type checked against the variants,
-not against the implementation. A call like ``my_list[5]`` would have
-type ``T``, not ``Union[T, Sequence[T]]`` because it matches the
-first overloaded definition, and ignores the type annotations on the
-implementation of ``__getitem__``. The code in the body of the
-definition of ``__getitem__`` is checked against the annotations on
-the corresponding declaration. In this case the body is checked
-with ``index: Union[int, slice]`` and a return type
-``Union[T, Sequence[T]]``. If there are no annotations on the
-corresponding definition, then code in the function body is not type
-checked.
-
-The annotations on the function body must be compatible with the
-types given for the overloaded variants listed above it. The type
-checker will verify that all the types for the overloaded variants
-are compatible with the types given for the implementation. In this
-case it checks that the parameter type ``int`` and the return type
-``T`` are compatible with ``Union[int, slice]`` and
-``Union[T, Sequence[T]]`` for the first variant. For the second
-variant it verifies that the parameter type ``slice`` and the return
-type ``Sequence[T]`` are compatible with ``Union[int, slice]`` and
-``Union[T, Sequence[T]]``.
-
-Overloaded function variants are still ordinary Python functions and
-they still define a single runtime object. There is no automatic
-dispatch happening, and you must manually handle the different types
-in the implementation (usually with :func:`isinstance` checks, as
-shown in the example).
-
-The overload variants must be adjacent in the code. This makes code
-clearer, as you don't have to hunt for overload variants across the
-file.
-
-Overloads in stub files are exactly the same, except there is no
-implementation.
+    @dataclass
+    class BoxedData(Generic[T]):
+        data: T
+        label: str
 
-.. note::
+    def unbox(bd: BoxedData[T]) -> T:
+        ...
 
-   As generic type variables are erased at runtime when constructing
-   instances of generic types, an overloaded function cannot have
-   variants that only differ in a generic type argument,
-   e.g. ``List[int]`` and ``List[str]``.
+    val = unbox(BoxedData(42, "<important>"))  # OK, inferred type is int
 
-.. note::
+For more information see `official docs <https://docs.python.org/3/library/dataclasses.html>`_
+and `PEP 557 <https://www.python.org/dev/peps/pep-0557/>`_.
 
-   If you just need to constrain a type variable to certain types or
-   subtypes, you can use a :ref:`value restriction
-   <type-variable-value-restriction>`.
+**Note:** Some functions in the ``dataclasses`` module, such as ``replace()`` and ``asdict()``,
+have imprecise (too permissive) types. This will be fixed in future releases.
 
 .. _attrs_package:
 

docs/source/cheat_sheet_py3.rst

@@ -47,14 +47,13 @@ Built-in types
 
 .. code-block:: python
 
-   from typing import List, Set, Dict, Tuple, Text, Optional, AnyStr
+   from typing import List, Set, Dict, Tuple, Optional
 
    # For simple built-in types, just use the name of the type
    x: int = 1
    x: float = 1.0
    x: bool = True
    x: str = "test"
-   x: str = u"test"
    x: bytes = b"test"
 
    # For collections, the name of the type is capitalized, and the
@@ -71,10 +70,6 @@ Built-in types
    # For tuples, we specify the types of all the elements
    x: Tuple[int, str, float] = (3, "yes", 7.5)
 
-   # For textual data, use Text if you care about Python 2 compatibility
-   # ("Text" means "unicode" in Python 2 and "str" in Python 3)
-   x: List[Text] = ["string", u"unicode"]
-
    # Use Optional[] for values that could be None
    x: Optional[str] = some_function()
    if x is not None:
@@ -269,7 +264,6 @@ See :ref:`async-and-await` for the full detail on typing coroutines and asynchro
 .. code-block:: python
 
    import asyncio
-   from typing import Generator, Any
 
    # A coroutine is typed like a normal function
    async def countdown35(tag: str, count: int) -> str:

docs/source/command_line.rst

@@ -152,6 +152,8 @@ This is computed from the following items:
   (a colon-separated list of directories).
 - The directories containing the sources given on the command line
   (see below).
+- The installed packages marked as safe for type checking (see
+  :ref:`PEP 561 support <installed-packages>`)
 - The relevant directories of the
   `typeshed <https://github.com/python/typeshed>`_ repo.
 
@@ -161,7 +163,7 @@ contain an ``__init__.py`` or ``__init__.pyi`` file.
 
 Second, mypy searches for stub files in addition to regular Python files
 and packages.
-The rules for searching a module ``foo`` are as follows:
+The rules for searching for a module ``foo`` are as follows:
 
 - The search looks in each of the directories in the search path
   (see above) until a match is found.
@@ -288,6 +290,8 @@ The following options are available:
   module (such as ``List[int]`` and ``Dict[str, str]``).
 
 
+.. _additional-command-line-flags:
+
 Additional command line flags
 *****************************
 
@@ -297,6 +301,21 @@ Here are some more useful flags:
 
 - ``--ignore-missing-imports`` suppresses error messages about imports
   that cannot be resolved (see :ref:`follow-imports` for some examples).
+  This doesn't suppress errors about missing names in successfully resolved
+  modules. For example, if one has the following files::
+
+    package/__init__.py
+    package/mod.py
+
+  Then mypy will generate the following errors with ``--ignore-missing-imports``:
+
+  .. code-block:: python
+
+     import package.unknown  # No error, ignored
+     x = package.unknown.func()  # OK
+
+     from package import unknown  # No error, ignored
+     from package.mod import NonExisting  # Error: Module has no attribute 'NonExisting'
 
 - ``--no-strict-optional`` disables strict checking of ``Optional[...]``
   types and ``None`` values. With this option, mypy doesn't

docs/source/config_file.rst

@@ -201,7 +201,7 @@ overridden by the pattern sections matching the module name.
   strict Optional checks. If False, mypy treats ``None`` as
   compatible with every type.
 
-  **Note::** This was False by default
+  **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

docs/source/index.rst

@@ -32,7 +32,6 @@ Mypy is a static type checker for Python 3 and Python 2.7.
    kinds_of_types
    class_basics
    protocols
-   metaclasses
    python2
    dynamic_typing
    casts
@@ -40,6 +39,7 @@ Mypy is a static type checker for Python 3 and Python 2.7.
    stubs
    generics
    more_types
+   metaclasses
 
 .. toctree::
    :maxdepth: 2

docs/source/installed_packages.rst

@@ -43,7 +43,7 @@ If you would like to publish a library package to a package repository (e.g.
 PyPI) for either internal or external use in type checking, packages that
 supply type information via type comments or annotations in the code should put
 a ``py.typed`` in their package directory. For example, with a directory
-structure as follows:
+structure as follows
 
 .. code-block:: text
 
@@ -53,7 +53,7 @@ structure as follows:
         lib.py
         py.typed
 
-the setup.py might look like:
+the setup.py might look like
 
 .. code-block:: python
 
@@ -67,8 +67,13 @@ the setup.py might look like:
         packages=["package_a"]
     )
 
+.. note::
+
+   If you use setuptools, you must pass the option ``zip_safe=False`` to
+   ``setup()``, or mypy will not be able to find the installed package.
+
 Some packages have a mix of stub files and runtime files. These packages also
-require a ``py.typed`` file. An example can be seen below:
+require a ``py.typed`` file. An example can be seen below
 
 .. code-block:: text
 

docs/source/more_types.rst

@@ -2,7 +2,8 @@ More types
 ==========
 
 This section introduces a few additional kinds of types, including ``NoReturn``,
-``NewType``, ``TypedDict``, and types for async code. All of these are only
+``NewType``, ``TypedDict``, and types for async code. It also discusses how to
+give functions more precise types using overloads. All of these are only
 situationally useful, so feel free to skip this section and come back when you
 have a need for some of them.
 
@@ -15,6 +16,10 @@ Here's a quick summary of what's covered here:
   For example, you can have ``UserId`` as a variant of ``int`` that is
   just an ``int`` at runtime.
 
+* ``@overload`` lets you define a function that can accept multiple distinct
+  signatures. This is useful for if you need to encode a relationship between
+  the arguments and the return type that would be difficult to express normally.
+
 * ``TypedDict`` lets you give precise types for dictionaries that represent
   objects with a fixed schema, such as ``{'id': 1, 'items': ['x']}``.
 
@@ -178,6 +183,385 @@ create subclasses of these objects either.
 
         name_by_id(3)  # int is not the same as UserId
 
+.. _function-overloading:
+
+Function overloading
+********************
+
+Sometimes the arguments and types in a function depend on each other
+in ways that can't be captured with a ``Union``. For example, suppose
+we want to write a function that can accept x-y coordinates. If we pass
+in just a single x-y coordinate, we return a ``ClickEvent`` object. However,
+if we pass in two x-y coordinates, we return a ``DragEvent`` object.
+
+Our first attempt at writing this function might look like this:
+
+.. code-block:: python
+
+    from typing import Union, Optional
+
+    def mouse_event(x1: int, 
+                    y1: int,
+                    x2: Optional[int] = None,
+                    y2: Optional[int] = None) -> Union[ClickEvent, DragEvent]:
+        if x2 is None and y2 is None:
+            return ClickEvent(x1, y1)
+        elif x2 is not None and y2 is not None:
+            return DragEvent(x1, y1, x2, y2)
+        else:
+            raise TypeError("Bad arguments")
+
+While this function signature works, it's too loose: it implies ``mouse_event``
+could return either object regardless of the number of arguments
+we pass in. It also does not prohibit a caller from passing in the wrong
+number of ints: mypy would treat calls like ``mouse_event(1, 2, 20)`` as being
+valid, for example.
+
+We can do better by using `overloading
+<https://www.python.org/dev/peps/pep-0484/#function-method-overloading>`_
+which lets us give the same function multiple type annotations (signatures)
+to more accurately describe the function's behavior:
+
+.. code-block:: python
+
+    from typing import Union, overload
+
+    # Overload *variants* for 'mouse_event'.
+    # These variants give extra information to the type checker.
+    # They are ignored at runtime.
+
+    @overload
+    def mouse_event(x1: int, y1: int) -> ClickEvent: ...
+    @overload
+    def mouse_event(x1: int, y1: int, x2: int, y2: int) -> DragEvent: ...
+
+    # The actual *implementation* of 'mouse_event'.
+    # The implementation contains the actual runtime logic.
+    #
+    # It may or may not have type hints. If it does, mypy
+    # will check the body of the implementation against the
+    # type hints.
+    #
+    # Mypy will also check and make sure the signature is
+    # consistent with the provided variants.
+
+    def mouse_event(x1: int, 
+                    y1: int,
+                    x2: Optional[int] = None,
+                    y2: Optional[int] = None) -> Union[ClickEvent, DragEvent]:
+        if x2 is None and y2 is None:
+            return ClickEvent(x1, y1)
+        elif x2 is not None and y2 is not None:
+            return DragEvent(x1, y1, x2, y2)
+        else:
+            raise TypeError("Bad arguments")
+
+This allows mypy to understand calls to ``mouse_event`` much more precisely.
+For example, mypy will understand that ``mouse_event(5, 25)`` will
+always have a return type of ``ClickEvent`` and will report errors for
+calls like ``mouse_event(5, 25, 2)``.
+
+As another example, suppose we want to write a custom container class that
+implements the ``__getitem__`` method (``[]`` bracket indexing). If this
+method receives an integer we return a single item. If it receives a
+``slice``, we return a ``Sequence`` of items.
+
+We can precisely encode this relationship between the argument and the
+return type by using overloads like so:
+
+.. code-block:: python
+
+    from typing import Sequence, TypeVar, Union, overload
+
+    T = TypeVar('T')
+
+    class MyList(Sequence[T]):
+        @overload
+        def __getitem__(self, index: int) -> T: ...
+
+        @overload
+        def __getitem__(self, index: slice) -> Sequence[T]: ...
+
+        def __getitem__(self, index: Union[int, slice]) -> Union[T, Sequence[T]]:
+            if isinstance(index, int):
+                # Return a T here
+            elif isinstance(index, slice):
+                # Return a sequence of Ts here
+            else:
+                raise TypeError(...)
+
+.. note::
+
+   If you just need to constrain a type variable to certain types or
+   subtypes, you can use a :ref:`value restriction
+   <type-variable-value-restriction>`.
+
+
+Runtime behavior
+----------------
+
+An overloaded function must consist of two or more overload *variants*
+followed by an *implementation*. The variants and the implementations
+must be adjacent in the code: think of them as one indivisible unit.
+
+The variant bodies must all be empty; only the implementation is allowed
+to contain code. This is because at runtime, the variants are completely
+ignored: they're overridden by the final implementation function.
+
+This means that an overloaded function is still an ordinary Python
+function! There is no automatic dispatch handling and you must manually
+handle the different types in the implementation (e.g. by using
+``if`` statements and ``isinstance`` checks).
+
+If you are adding an overload within a stub file, the implementation
+function should be omitted: stubs do not contain runtime logic.
+
+.. note::
+
+   While we can leave the variant body empty using the ``pass`` keyword,
+   the more common convention is to instead use the ellipsis (``...``) literal.
+
+Type checking calls to overloads
+--------------------------------
+
+When you call an overloaded function, mypy will infer the correct return
+type by picking the best matching variant, after taking into consideration
+both the argument types and arity. However, a call is never type
+checked against the implementation. This is why mypy will report calls
+like ``mouse_event(5, 25, 3)`` as being invalid even though it matches the
+implementation signature.
+
+If there are multiple equally good matching variants, mypy will select
+the variant that was defined first. For example, consider the following
+program:
+
+.. code-block:: python
+
+    from typing import List, overload
+
+    @overload
+    def summarize(data: List[int]) -> float: ...
+
+    @overload
+    def summarize(data: List[str]) -> str: ...
+
+    def summarize(data):
+        if not data:
+            return 0.0
+        elif isinstance(data[0], int):
+            # Do int specific code
+        else:
+            # Do str-specific code
+
+    # What is the type of 'output'? float or str?
+    output = summarize([])
+
+The ``summarize([])`` call matches both variants: an empty list could
+be either a ``List[int]`` or a ``List[str]``. In this case, mypy
+will break the tie by picking the first matching variant: ``output``
+will have an inferred type of ``float``. The implementor is responsible
+for making sure ``summarize`` breaks ties in the same way at runtime.
+
+There are however are two exceptions to the "pick the first match" rule.
+First, if multiple variants match due to an argument being of type
+``Any``, mypy will make the inferred type also be ``Any``:
+
+.. code-block:: python
+
+    dynamic_var: Any = some_dynamic_function()
+
+    # output2 is of type 'Any'
+    output2 = summarize(dynamic_var)
+
+Second, if multiple variants match due to one or more of the arguments
+being a union, mypy will make the inferred type be the union of the 
+matching variant returns:
+
+.. code-block:: python
+
+    some_list: Union[List[int], List[str]]
+
+    # output3 is of type 'Union[float, str]'
+    output3 = summarize(some_list)
+
+.. note::
+
+   Due to the "pick the first match" rule, changing the order of your
+   overload variants can change how mypy type checks your program.
+
+   To minimize potential issues, we recommend that you:
+   
+   1. Make sure your overload variants are listed in the same order as
+      the runtime checks (e.g. ``isinstance`` checks) in your implementation.   
+   2. Order your variants and runtime checks from most to least specific.
+      (See the following section for an example).
+
+Type checking the variants
+--------------------------
+
+Mypy will perform several checks on your overload variant definitions
+to ensure they behave as expected. First, mypy will check and make sure
+that no overload variant is shadowing a subsequent one. For example,
+consider the following function which adds together two ``Expression``
+objects, and contains a special-case to handle receiving two ``Literal``
+types:
+
+.. code-block:: python
+
+    from typing import overload, Union
+
+    class Expression:
+        # ...snip...
+
+    class Literal(Expression):
+        # ...snip...
+
+    # Warning -- the first overload variant shadows the second!
+
+    @overload
+    def add(left: Expression, right: Expression) -> Expression: ...
+
+    @overload
+    def add(left: Literal, right: Literal) -> Literal: ...
+
+    def add(left: Expression, right: Expression) -> Expression:
+        # ...snip...
+
+While this code snippet is technically type-safe, it does contain an
+anti-pattern: the second variant will never be selected! If we try calling
+``add(Literal(3), Literal(4))``, mypy will always pick the first variant
+and evaluate the function call to be of type ``Expression``, not ``Literal``.
+This is because ``Literal`` is a subtype of ``Expression``, which means
+the "pick the first match" rule will always halt after considering the
+first overload.
+
+Because having an overload variant that can never be matched is almost
+certainly a mistake, mypy will report an error. To fix the error, we can
+either 1) delete the second overload or 2) swap the order of the overloads:
+
+.. code-block:: python
+
+    # Everything is ok now -- the variants are correctly ordered
+    # from most to least specific.
+
+    @overload
+    def add(left: Literal, right: Literal) -> Literal: ...
+
+    @overload
+    def add(left: Expression, right: Expression) -> Expression: ...
+
+    def add(left: Expression, right: Expression) -> Expression:
+        # ...snip...
+
+Mypy will also type check the different variants and flag any overloads
+that have inherently unsafely overlapping variants. For example, consider
+the following unsafe overload definition:
+
+.. code-block:: python
+
+    from typing import overload, Union
+
+    @overload
+    def unsafe_func(x: int) -> int: ...
+
+    @overload
+    def unsafe_func(x: object) -> str: ...
+
+    def unsafe_func(x: object) -> Union[int, str]:
+        if isinstance(x, int):
+            return 42
+        else:
+            return "some string"
+
+On the surface, this function definition appears to be fine. However, it will
+result in a discrepency between the inferred type and the actual runtime type
+when we try using it like so:
+
+.. code-block:: python
+
+    some_obj: object = 42
+    unsafe_func(some_obj) + " danger danger"  # Type checks, yet crashes at runtime!
+
+Since ``some_obj`` is of type ``object``, mypy will decide that ``unsafe_func``
+must return something of type ``str`` and concludes the above will type check.
+But in reality, ``unsafe_func`` will return an int, causing the code to crash
+at runtime!
+
+To prevent these kinds of issues, mypy will detect and prohibit inherently unsafely
+overlapping overloads on a best-effort basis. Two variants are considered unsafely
+overlapping when both of the following are true:
+
+1. All of the arguments of the first variant are compatible with the second.
+2. The return type of the first variant is *not* compatible with (e.g. is not a
+   subtype of) the second.
+
+So in this example, the ``int`` argument in the first variant is a subtype of
+the ``object`` argument in the second, yet the ``int`` return type not is a subtype of
+``str``. Both conditions are true, so mypy will correctly flag ``unsafe_func`` as
+being unsafe.
+
+However, mypy will not detect *all* unsafe uses of overloads. For example,
+suppose we modify the above snippet so it calls ``summarize`` instead of
+``unsafe_func``:
+
+.. code-block:: python
+
+    some_list: List[str] = []
+    summarize(some_list) + "danger danger"  # Type safe, yet crashes at runtime!
+
+We run into a similar issue here. This program type checks if we look just at the
+annotations on the overloads. But since ``summarize(...)`` is designed to be biased
+towards returning a float when it receives an empty list, this program will actually
+crash during runtime.
+
+The reason mypy does not flag definitions like ``summarize`` as being potentially
+unsafe is because if it did, it would be extremely difficult to write a safe
+overload. For example, suppose we define an overload with two variants that accept
+types ``A`` and ``B`` respectively. Even if those two types were completely unrelated,
+the user could still potentially trigger a runtime error similar to the ones above by
+passing in a value of some third type ``C`` that inherits from both ``A`` and ``B``.
+
+Thankfully, these types of situations are relatively rare. What this does mean,
+however, is that you should exercise caution when designing or using an overloaded
+function that can potentially receive values that are an instance of two seemingly
+unrelated types.
+
+
+Type checking the implementation
+--------------------------------
+
+The body of an implementation is type-checked against the
+type hints provided on the implementation. For example, in the
+``MyList`` example up above, the code in the body is checked with
+argument list ``index: Union[int, slice]`` and a return type of 
+``Union[T, Sequence[T]]``. If there are no annotations on the
+implementation, then the body is not type checked. If you want to
+force mypy to check the body anyways, use the ``--check-untyped-defs``
+flag (:ref:`more details here <additional-command-line-flags>`).
+
+The variants must also also be compatible with the implementation
+type hints. In the ``MyList`` example, mypy will check that the
+parameter type ``int`` and the return type ``T`` are compatible with
+``Union[int, slice]`` and ``Union[T, Sequence]`` for the
+first variant. For the second variant it verifies the parameter
+type ``slice`` and the return type ``Sequence[T]`` are compatible
+with ``Union[int, slice]`` and ``Union[T, Sequence]``.
+
+.. note::
+
+   The overload semantics documented above are new as of mypy 0.620.
+
+   Previously, mypy used to perform type erasure on all overload variants. For
+   example, the ``summarize`` example from the previous section used to be
+   illegal because ``List[str]`` and ``List[int]`` both erased to just ``List[Any]``.
+   This restriction was removed in mypy 0.620.
+
+   Mypy also previously used to select the best matching variant using a different
+   algorithm. If this algorithm failed to find a match, it would default to returning
+   ``Any``. The new algorithm uses the "pick the first match" rule and will fall back
+   to returning ``Any`` only if the input arguments also contain ``Any``.
+
+
 .. _async-and-await:
 
 Typing async/await

docs/source/revision_history.rst

@@ -4,6 +4,13 @@ Revision history
 List of major changes (the `Mypy Blog <http://mypy-lang.blogspot.com/>`_ contains more
 detailed release notes):
 
+- July 2018
+    * Publish ``mypy`` version 0.620 on PyPI.
+
+      * Improve support for :ref:`overloads <function-overloading>`.
+
+      * Add support for :ref:`dataclasses <dataclasses_support>`.
+
 - June 2018
     * Publish ``mypy`` version 0.610 on PyPI.
 

extensions/mypy_extensions.py

@@ -46,7 +46,7 @@ class _TypedDictMeta(type):
         # This method is called directly when TypedDict is subclassed,
         # or via _typeddict_new when TypedDict is instantiated. This way
         # TypedDict supports all three syntaxes described in its docstring.
-        # Subclasses and instanes of TypedDict return actual dictionaries
+        # Subclasses and instances of TypedDict return actual dictionaries
         # via _dict_new.
         ns['__new__'] = _typeddict_new if name == 'TypedDict' else _dict_new
         tp_dict = super(_TypedDictMeta, cls).__new__(cls, name, (dict,), ns)
@@ -135,3 +135,7 @@ def KwArg(type=Any):
 
 # Return type that indicates a function does not return
 class NoReturn: pass
+
+
+def trait(cls):
+    return cls

extensions/setup.py

@@ -20,7 +20,6 @@ classifiers = [
     'Programming Language :: Python :: 2',
     'Programming Language :: Python :: 2.7',
     'Programming Language :: Python :: 3',
-    'Programming Language :: Python :: 3.3',
     'Programming Language :: Python :: 3.4',
     'Programming Language :: Python :: 3.5',
     'Programming Language :: Python :: 3.6',

mypy.egg-info/PKG-INFO

 Metadata-Version: 2.1
 Name: mypy
-Version: 0.610
+Version: 0.620
 Summary: Optional static typing for Python
 Home-page: http://www.mypy-lang.org/
 Author: Jukka Lehtosalo

mypy/applytype.py

-from typing import List, Dict, Sequence, Optional
+from typing import Dict, Sequence, Optional
 
 import mypy.subtypes
 from mypy.sametypes import is_same_type

mypy/binder.py

@@ -354,7 +354,7 @@ class ConditionalTypeBinder:
         continue_frame and 'continue' statements.
 
         If try_frame is true, then execution is allowed to jump at any
-        point within the newly created frame (or its descendents) to
+        point within the newly created frame (or its descendants) to
         its parent (i.e., to the frame that was on top before this
         call to frame_context).