Kinds of types — Mypy 0.630+dev-734a166d380bfb0de05ce0e3c61dc7e675898e9c-dirty documentation

# Kinds of types

We’ve mostly restricted ourselves to built-in types until now. This section introduces several additional kinds of types. You are likely to need at least some of them to type check any non-trivial programs.

## Class types

Every class is also a valid type. Any instance of a subclass is also compatible with all superclasses – it follows that every value is compatible with the `object` type (and incidentally also the `Any` type, discussed below). Mypy analyzes the bodies of classes to determine which methods and attributes are available in instances. This example uses subclassing:

    class A:
        def f(self) -> int:  # Type of self inferred (A)
            return 2

    class B(A):
        def f(self) -> int:
             return 3
        def g(self) -> int:
            return 4

    def foo(a: A) -> None:
        print(a.f())  # 3
        a.g()         # Error: "A" has no attribute "g"

    foo(B())  # OK (B is a subclass of A)

## The Any type

A value with the `Any` type is dynamically typed. Mypy doesn’t know anything about the possible runtime types of such value. Any operations are permitted on the value, and the operations are only checked at runtime. You can use `Any` as an “escape hatch” when you can’t use a more precise type for some reason.

`Any` is compatible with every other type, and vice versa. You can freely assign a value of type `Any` to a variable with a more precise type:

    a: Any = None
    s: str = ''
    a = 2     # OK (assign "int" to "Any")
    s = a     # OK (assign "Any" to "str")

Declared (and inferred) types are ignored (or erased) at runtime. They are basically treated as comments, and thus the above code does not generate a runtime error, even though `s` gets an `int` value when the program is run, while the declared type of `s` is actually `str`! You need to be careful with `Any` types, since they let you lie to mypy, and this could easily hide bugs.

If you do not define a function return value or argument types, these default to `Any`:

    def show_heading(s) -> None:
        print('=== ' + s + ' ===')  # No static type checking, as s has type Any

    show_heading(1)  # OK (runtime error only; mypy won't generate an error)

You should give a statically typed function an explicit `None` return type even if it doesn’t return a value, as this lets mypy catch additional type errors:

    def wait(t: float):  # Implicit Any return value
        print('Waiting...')
        time.sleep(t)

    if wait(2) > 1:   # Mypy doesn't catch this error!
        ...

If we had used an explicit `None` return type, mypy would have caught the error:

    def wait(t: float) -> None:
        print('Waiting...')
        time.sleep(t)

    if wait(2) > 1:   # Error: can't compare None and int
        ...

The `Any` type is discussed in more detail in section Dynamically typed code.

Note

A function without any types in the signature is dynamically typed. The body of a dynamically typed function is not checked statically, and local variables have implicit `Any` types. This makes it easier to migrate legacy Python code to mypy, as mypy won’t complain about dynamically typed functions.

## Tuple types

The type `Tuple[T1, ..., Tn]` represents a tuple with the item types `T1`, …, `Tn`:

    def f(t: Tuple[int, str]) -> None:
        t = 1, 'foo'    # OK
        t = 'foo', 1    # Type check error

A tuple type of this kind has exactly a specific number of items (2 in the above example). Tuples can also be used as immutable, varying-length sequences. You can use the type `Tuple[T, ...]` (with a literal `...` – it’s part of the syntax) for this purpose. Example:

    def print_squared(t: Tuple[int, ...]) -> None:
        for n in t:
            print(n, n ** 2)

    print_squared(())           # OK
    print_squared((1, 3, 5))    # OK
    print_squared([1, 2])       # Error: only a tuple is valid

Note

Usually it’s a better idea to use `Sequence[T]` instead of `Tuple[T, ...]`, as `Sequence` is also compatible with lists and other non-tuple sequences.

Note

`Tuple[...]` is valid as a base class in Python 3.6 and later, and always in stub files. In earlier Python versions you can sometimes work around this limitation by using a named tuple as a base class (see section Named tuples).

## Callable types (and lambdas)

You can pass around function objects and bound methods in statically typed code. The type of a function that accepts arguments `A1`, …, `An` and returns `Rt` is `Callable[[A1, ..., An], Rt]`. Example:

    from typing import Callable

    def twice(i: int, next: Callable[[int], int]) -> int:
        return next(next(i))

    def add(i: int) -> int:
        return i + 1

    print(twice(3, add))   # 5

You can only have positional arguments, and only ones without default values, in callable types. These cover the vast majority of uses of callable types, but sometimes this isn’t quite enough. Mypy recognizes a special form `Callable[..., T]` (with a literal `...`) which can be used in less typical cases. It is compatible with arbitrary callable objects that return a type compatible with `T`, independent of the number, types or kinds of arguments. Mypy lets you call such callable values with arbitrary arguments, without any checking – in this respect they are treated similar to a `(*args: Any, **kwargs: Any)` function signature. Example:

    from typing import Callable

     def arbitrary_call(f: Callable[..., int]) -> int:
         return f('x') + f(y=2)  # OK

     arbitrary_call(ord)   # No static error, but fails at runtime
     arbitrary_call(open)  # Error: does not return an int
     arbitrary_call(1)     # Error: 'int' is not callable

In situations where more precise or complex types of callbacks are necessary one can use flexible callback protocols. Lambdas are also supported. The lambda argument and return value types cannot be given explicitly; they are always inferred based on context using bidirectional type inference:

    l = map(lambda x: x + 1, [1, 2, 3])   # Infer x as int and l as List[int]

If you want to give the argument or return value types explicitly, use an ordinary, perhaps nested function definition.

## Union types

Python functions often accept values of two or more different types. You can use overloading to represent this, but union types are often more convenient.

Use the `Union[T1, ..., Tn]` type constructor to construct a union type. For example, if an argument has type `Union[int, str]`, both integers and strings are valid argument values.

You can use an `isinstance()` check to narrow down a union type to a more specific type:

    from typing import Union

    def f(x: Union[int, str]) -> None:
        x + 1     # Error: str + int is not valid
        if isinstance(x, int):
            # Here type of x is int.
            x + 1      # OK
        else:
            # Here type of x is str.
            x + 'a'    # OK

    f(1)    # OK
    f('x')  # OK
    f(1.1)  # Error

Note

Operations are valid for union types only if they are valid for every union item. This is why it’s often necessary to use an `isinstance()` check to first narrow down a union type to a non-union type. This also means that it’s recommended to avoid union types as function return types, since the caller may have to use `isinstance()` before doing anything interesting with the value.

## Optional types and the None type

You can use the `Optional` type modifier to define a type variant that allows `None`, such as `Optional[int]` (`Optional[X]` is the preferred shorthand for `Union[X, None]`):

    from typing import Optional

    def strlen(s: str) -> Optional[int]:
        if not s:
            return None  # OK
        return len(s)

    def strlen_invalid(s: str) -> int:
        if not s:
            return None  # Error: None not compatible with int
        return len(s)

Most operations will not be allowed on unguarded `None` or `Optional` values:

    def my_inc(x: Optional[int]) -> int:
        return x + 1  # Error: Cannot add None and int

Instead, an explicit `None` check is required. Mypy has powerful type inference that lets you use regular Python idioms to guard against `None` values. For example, mypy recognizes `is None` checks:

    def my_inc(x: Optional[int]) -> int:
        if x is None:
            return 0
        else:
            # The inferred type of x is just int here.
            return x + 1

Mypy will infer the type of `x` to be `int` in the else block due to the check against `None` in the if condition.

Other supported checks for guarding against a `None` value include `if x is not None`, `if x` and `if not x`. Additionally, mypy understands `None` checks within logical expressions:

    def concat(x: Optional[str], y: Optional[str]) -> Optional[str]:
        if x is not None and y is not None:
            # Both x and y are not None here
            return x + y
        else:
            return None

Sometimes mypy doesn’t realize that a value is never `None`. This notably happens when a class instance can exist in a partially defined state, where some attribute is initialized to `None` during object construction, but a method assumes that the attribute is no longer `None`. Mypy will complain about the possible `None` value. You can use `assert x is not None` to work around this in the method:

    class Resource:
        path: Optional[str] = None

        def initialize(self, path: str) -> None:
            self.path = path

        def read(self) -> str:
            # We require that the object has been initialized.
            assert self.path is not None
            with open(self.path) as f:  # OK
               return f.read()

    r = Resource()
    r.initialize('/foo/bar')
    r.read()

When initializing a variable as `None`, `None` is usually an empty place-holder value, and the actual value has a different type. This is why you need to annotate an attribute in a cases like the class `Resource` above:

    class Resource:
        path: Optional[str] = None
        ...

This also works for attributes defined within methods:

    class Counter:
        def __init__(self) -> None:
            self.count: Optional[int] = None

As a special case, you can use a non-optional type when initializing an attribute to `None` inside a class body and using a type comment, since when using a type comment, an initializer is syntactically required, and `None` is used as a dummy, placeholder initializer:

    from typing import List

    class Container:
        items = None  # type: List[str]  # OK (only with type comment)

This is not a problem when using variable annotations, since no initializer is needed:

    from typing import List

    class Container:
        items: List[str]  # No initializer

Mypy generally uses the first assignment to a variable to infer the type of the variable. However, if you assign both a `None` value and a non-`None` value in the same scope, mypy can usually do the right thing without an annotation:

    def f(i: int) -> None:
        n = None  # Inferred type Optional[int] because of the assignment below
        if i > 0:
             n = i
        ...

Sometimes you may get the error “Cannot determine type of <something>”. In this case you should add an explicit `Optional[...]` annotation (or type comment).

Note

`None` is a type with only one value, `None`. `None` is also used as the return type for functions that don’t return a value, i.e. functions that implicitly return `None`.

Note

The Python interpreter internally uses the name `NoneType` for the type of `None`, but `None` is always used in type annotations. The latter is shorter and reads better. (Besides, `NoneType` is not even defined in the standard library.)

Note

`Optional[...]` does not mean a function argument with a default value. However, if the default value of an argument is `None`, you can use an optional type for the argument, but it’s not enforced by default. You can use the `--no-implicit-optional` command-line option to stop treating arguments with a `None` default value as having an implicit `Optional[...]` type. It’s possible that this will become the default behavior in the future.

## Disabling strict optional checking

Mypy also has an option to treat `None` as a valid value for every type (in case you know Java, it’s useful to think of it as similar to the Java `null`). In this mode `None` is also valid for primitive types such as `int` and `float`, and `Optional[...]` types are not required.

The mode is enabled through the `--no-strict-optional` command-line option. In mypy versions before 0.600 this was the default mode. You can enable this option explicitly for backward compatibility with earlier mypy versions, in case you don’t want to introduce optional types to your codebase yet.

It will cause mypy to silently accept some buggy code, such as this example – it’s not recommended if you can avoid it:

    def inc(x: int) -> int:
        return x + 1

    x = inc(None)  # No error reported by mypy if strict optional mode disabled!

However, making code “optional clean” can take some work! You can also use the mypy configuration file to migrate your code to strict optional checking one file at a time, since there exists the per-module flag `strict_optional` to control strict optional mode.

Often it’s still useful to document whether a variable can be `None`. For example, this function accepts a `None` argument, but it’s not obvious from its signature:

    def greeting(name: str) -> str:
        if name:
            return 'Hello, {}'.format(name)
        else:
            return 'Hello, stranger'

    print(greeting('Python'))  # Okay!
    print(greeting(None))      # Also okay!

You can still use `Optional[t]` to document that `None` is a valid argument type, even if strict `None` checking is not enabled:

    from typing import Optional

    def greeting(name: Optional[str]) -> str:
        if name:
            return 'Hello, {}'.format(name)
        else:
            return 'Hello, stranger'

Mypy treats this as semantically equivalent to the previous example if strict optional checking is disabled, since `None` is implicitly valid for any type, but it’s much more useful for a programmer who is reading the code. This also makes it easier to migrate to strict `None` checking in the future.

## Class name forward references

Python does not allow references to a class object before the class is defined. Thus this code does not work as expected:

    def f(x: A) -> None:  # Error: Name A not defined
        ....

    class A:
        ...

In cases like these you can enter the type as a string literal — this is a forward reference:

    def f(x: 'A') -> None:  # OK
        ...

    class A:
        ...

Of course, instead of using a string literal type, you could move the function definition after the class definition. This is not always desirable or even possible, though.

Any type can be entered as a string literal, and you can combine string-literal types with non-string-literal types freely:

    def f(a: List['A']) -> None: ...  # OK
    def g(n: 'int') -> None: ...      # OK, though not useful

    class A: pass

String literal types are never needed in `# type:` comments.

String literal types must be defined (or imported) later in the same module. They cannot be used to leave cross-module references unresolved. (For dealing with import cycles, see Import cycles.)

## Type aliases

In certain situations, type names may end up being long and painful to type:

    def f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]:
        ...

When cases like this arise, you can define a type alias by simply assigning the type to a variable:

    AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]

    # Now we can use AliasType in place of the full name:

    def f() -> AliasType:
        ...

Note

A type alias does not create a new type. It’s just a shorthand notation for another type – it’s equivalent to the target type except for generic aliases.

## Named tuples

Mypy recognizes named tuples and can type check code that defines or uses them. In this example, we can detect code trying to access a missing attribute:

    Point = namedtuple('Point', ['x', 'y'])
    p = Point(x=1, y=2)
    print(p.z)  # Error: Point has no attribute 'z'

If you use `namedtuple` to define your named tuple, all the items are assumed to have `Any` types. That is, mypy doesn’t know anything about item types. You can use `typing.NamedTuple` to also define item types:

    from typing import NamedTuple

    Point = NamedTuple('Point', [('x', int),
                                 ('y', int)])
    p = Point(x=1, y='x')  # Argument has incompatible type "str"; expected "int"

Python 3.6 introduced an alternative, class-based syntax for named tuples with types:

    from typing import NamedTuple

    class Point(NamedTuple):
        x: int
        y: int

    p = Point(x=1, y='x')  # Argument has incompatible type "str"; expected "int"

## The type of class objects

(Freely after PEP 484.)

Sometimes you want to talk about class objects that inherit from a given class. This can be spelled as `Type[C]` where `C` is a class. In other words, when `C` is the name of a class, using `C` to annotate an argument declares that the argument is an instance of `C` (or of a subclass of `C`), but using `Type[C]` as an argument annotation declares that the argument is a class object deriving from `C` (or `C` itself).

For example, assume the following classes:

    class User:
        # Defines fields like name, email

    class BasicUser(User):
        def upgrade(self):
            """Upgrade to Pro"""

    class ProUser(User):
        def pay(self):
            """Pay bill"""

Note that `ProUser` doesn’t inherit from `BasicUser`.

Here’s a function that creates an instance of one of these classes if you pass it the right class object:

    def new_user(user_class):
        user = user_class()
        # (Here we could write the user object to a database)
        return user

How would we annotate this function? Without `Type[]` the best we could do would be:

    def new_user(user_class: type) -> User:
        # Same  implementation as before

This seems reasonable, except that in the following example, mypy doesn’t see that the `buyer` variable has type `ProUser`:

    buyer = new_user(ProUser)
    buyer.pay()  # Rejected, not a method on User

However, using `Type[]` and a type variable with an upper bound (see Type variables with upper bounds) we can do better:

    U = TypeVar('U', bound=User)

    def new_user(user_class: Type[U]) -> U:
        # Same  implementation as before

Now mypy will infer the correct type of the result when we call `new_user()` with a specific subclass of `User`:

    beginner = new_user(BasicUser)  # Inferred type is BasicUser
    beginner.upgrade()  # OK

Note

The value corresponding to `Type[C]` must be an actual class object that’s a subtype of `C`. Its constructor must be compatible with the constructor of `C`. If `C` is a type variable, its upper bound must be a class object.

For more details about `Type[]` see PEP 484.

## Text and AnyStr

Sometimes you may want to write a function which will accept only unicode strings. This can be challenging to do in a codebase intended to run in both Python 2 and Python 3 since `str` means something different in both versions and `unicode` is not a keyword in Python 3.

To help solve this issue, use `typing.Text` which is aliased to `unicode` in Python 2 and to `str` in Python 3. This allows you to indicate that a function should accept only unicode strings in a cross-compatible way:

    from typing import Text

    def unicode_only(s: Text) -> Text:
        return s + u'\u2713'

In other cases, you may want to write a function that will work with any kind of string but will not let you mix two different string types. To do so use `typing.AnyStr`:

    from typing import AnyStr

    def concat(x: AnyStr, y: AnyStr) -> AnyStr:
        return x + y

    concat('a', 'b')     # Okay
    concat(b'a', b'b')   # Okay
    concat('a', b'b')    # Error: cannot mix bytes and unicode

For more details, see Type variables with value restriction.

Note

How `bytes`, `str`, and `unicode` are handled between Python 2 and Python 3 may change in future versions of mypy.

## Generators

A basic generator that only yields values can be annotated as having a return type of either `Iterator[YieldType]` or `Iterable[YieldType]`. For example:

    def squares(n: int) -> Iterator[int]:
        for i in range(n):
            yield i * i

If you want your generator to accept values via the `send` method or return a value, you should use the `Generator[YieldType, SendType, ReturnType]` generic type instead. For example:

    def echo_round() -> Generator[int, float, str]:
        sent = yield 0
        while sent >= 0:
            sent = yield round(sent)
        return 'Done'

Note that unlike many other generics in the typing module, the `SendType` of `Generator` behaves contravariantly, not covariantly or invariantly.

If you do not plan on receiving or returning values, then set the `SendType` or `ReturnType` to `None`, as appropriate. For example, we could have annotated the first example as the following:

    def squares(n: int) -> Generator[int, None, None]:
        for i in range(n):
            yield i * i

This is slightly different from using `Iterable[int]` or `Iterator[int]`, since generators have `close()`, `send()`, and `throw()` methods that generic iterables don’t. If you will call these methods on the returned generator, use the `Generator` type instead of `Iterable` or `Iterator`.