Basics

Function Signatures

A function without a type signature is dynamically typed. You can declare the signature of a function using the Python 3 annotation syntax This makes the function statically typed (the type checker reports type errors within the function):

.. code-block:: python

.. code-block:: python

A None return type indicates a function that does not explicitly return a value. Using a None result in a statically typed context results in a type check error:

.. code-block:: python

The typing module

We cheated a bit in the above examples: a module is type checked only if it imports the module typing. Here is a complete statically typed example from the previous section:

.. code-block:: python

The typing module contains many definitions that are useful in statically typed code. You can also use from ... import to import them (we'll explain Iterable later in this document):

.. code-block:: python

For brevity, we often omit the typing import in code examples, but you should always include it in modules that contain statically typed code.

You can still have dynamically typed functions in modules that import typing:

.. code-block:: python

Mixing dynamic and static typing within a single file is often useful. For example, if you are migrating existing Python code to static typing, it may be easiest to do this incrementally, such as by migrating a few functions at a time. Also, when prototyping a new feature, you may decide to first implement the relevant code using dynamic typing and only add type signatures later, when the code is more stable.

.. note::

Currently the type checker checks the top levels and annotated functions of all modules, even those that don't import typing. However, you should not rely on this, as this will change in the future.

Type checking and running programs

You can type check a program by using the mypy tool, which is basically a linter — it checks you program for errors without actually running it::

You can always run a mypy program as a Python program, without type checking, even it it has type errors::

All errors reported by mypy are essentially warnings that you are free to ignore, if you so wish.

The `README <https://github.com/JukkaL/mypy/blob/master/README.md>`_ explains how to download and install mypy.

.. note::

Depending on how mypy is configured, you may have to explicitly use the Python interpreter to run mypy. The mypy tool is an ordinary mypy (and so also Python) program.

Built-in types

These are examples of some of the most common built-in types:

.. code-block:: python

The type Any and type constructors List, Dict, Iterable and Sequence are defined in the typing module.

The type Dict is a *generic* class, signified by type arguments within [...]. For example, Dict[int, str] is a dictionary from integers to strings and and Dict[Any, Any] is a dictionary of dynamically typed (arbitrary) values and keys. List is another generic class. Dict and List are aliases for the built-ins dict and list, respectively.

Iterable and Sequence are generic abstract base classes that correspond to Python protocols. For example, a str object is valid when Iterable[str] or Sequence[str] is expected. Note that even though they are similar to abstract base classes defined in abc.collections (formerly collections), they are not identical, since the built-in collection type objects do not support indexing.

Casts

Mypy supports type casts that are usually used to coerce a statically typed value to a subtype. Unlike languages such as Java or C#, however, mypy casts are only used as hints for the type checker when using Python semantics, and they have no runtime effect. Use the function cast to perform a cast:

.. code-block:: python

Supporting runtime checking of casts such as the above when using Python semantics would require emulating reified generics and this would be difficult to do and would likely degrade performance and make code more difficult to read. You should not rely in your programs on casts being checked at runtime. Use an assertion if you want to perform an actual runtime check. Casts are used to silence spurious type checker warnings.

You don't need a cast for expressions with type Any, of when assigning to a variable with type Any, as was explained earlier.

You can cast to a dynamically typed value by just calling Any:

.. code-block:: python

Class basics

Instance and class attributes

Mypy type checker detects if you are trying to access a missing attribute, which is a very common programming error. For this to work correctly, instance and class attributes must be defined or initialized within the class. Mypy infers the types of attributes:

.. code-block:: python

This is a bit like each class having an implicitly defined __slots__ attribute. In Python semantics this is only enforced during type checking: at runtime we use standard Python semantics. You can selectively define a class as *dynamic*; dynamic classes have Python-like compile-time semantics, and they allow you to assign to arbitrary attributes anywhere in a program without the type checker complaining:

.. code-block:: python

Mypy also lets you read arbitrary attributes of dynamic class instances. This limits type checking effectiveness, so you should only use dynamic classes when you really need them.

.. note::

Dynamic classes are not implemented in the current mypy version.

You can declare variables in the class body explicitly using Undefined or a type comment:

.. code-block:: python

As in Python, a variable defined in the class body can used as a class or an instance variable.

Similarly, you can give explicit types to instance variables defined in a method:

.. code-block:: python

You can only define an instance variable within a method if you assign to it explicitly using self:

.. code-block:: python

Overriding statically typed methods

When overriding a statically typed method, mypy checks that the override has a compatible signature:

.. code-block:: python

.. note::

You can also vary return types **covariantly** in overriding. For example, you could override the return type 'object' with a subtype such as 'int'.

You can also override a statically typed method with a dynamically typed one. This allows dynamically typed code to override methods defined in library classes without worrying about their type signatures, similar to Python.

There is no runtime enforcement that the method override returns a value that is compatible with the original return type, since types are erased in the Python semantics:

.. code-block:: python

Abstract base classes and multiple inheritance

Mypy uses Python abstract base classes for protocol types. There are several built-in abstract base classes types (for example, Sequence, Iterable and Iterator). You can define abstract base classes using the abc.ABCMeta metaclass and the abc.abstractmethod function decorator.

.. code-block:: python

Common issues

Statically typed function bodies are often identical to normal Python code, but sometimes you need to do things slightly differently. This section introduces some of the most common cases which require different conventions in statically typed code.

First, you need to specify the type when creating an empty list or dict and when you assign to a new variable, as mentioned earlier:

.. code-block:: python

Sometimes you can avoid the explicit list item type by using a list comprehension. Here a type annotation is needed:

.. code-block:: python

.. note::

A future mypy version may be able to deal with cases such as the above without type annotations.

No type annotation needed if using a list comprehension:

.. code-block:: python

However, in more complex cases the explicit type annotation can improve the clarity of your code, whereas a complex list comprehension can make your code difficult to understand.

Second, each name within a function only has a single type. You can reuse for loop indices etc., but if you want to use a variable with multiple types within a single function, you may need to declare it with the Any type.

.. code-block:: python

.. note::

This is another limitation that could be lifted in a future mypy version.

Third, sometimes the inferred type is a subtype of the desired type. The type inference uses the first assignment to infer the type of a name:

.. code-block:: python

You can just give an explicit type for the variable in cases such the above example:

.. code-block:: python

Fourth, if you use isinstance tests or other kinds of runtime type tests, you may have to add casts (this is similar to instanceof tests in Java):

.. code-block:: python

Note that the object type used in the above example is similar to Object in Java: it only supports operations defined for all objects, such as equality and isinstance(). The type Any, in contrast, supports all operations, even if they may fail at runtime. The cast above would have been unnecessary if the type of o was Any.

Some consider casual use of isinstance tests a sign of bad programming style. Often a method override or an overloaded function is a cleaner way of implementing functionality that depends on the runtime types of values. However, use whatever techniques that work for you. Sometimes isinstance tests *are* the cleanest way of implementing a piece of functionality.

Type inference in mypy is designed to work well in common cases, to be predictable and to let the type checker give useful error messages. More powerful type inference strategies often have complex and difficult-to-prefict failure modes and could result in very confusing error messages.