See Also

The following is only valid when Python Plugin is installed and enabled!

In this section:

Following pep484

IntelliJ IDEA supports type hinting in function annotations and type comments using the typing module defined by PEP 484.

Specifying types of parameters

When Python 3 is specified as the project interpreter, you can use annotations to specify the expected parameter type:

py_type_hinting_param2

For Python 2, you can specify the types of parameters in the Python stubs.

Specifying return types

When Python 3 is specified as the project interpreter, you can use annotations to specify the expected return type:

py_type_hinting_return1

For Python 2, you can specify return types in the Python stubs.

Specifying types of local variables and attributes

Use annotations to specify the types of local variables and attributes:

images/py_type_hinting_attributes.png

Also, you can specify the types of local variables and attributes in the Python stubs.

Python stubs

IntelliJ IDEA supports Python stub files with the .pyi extension. These files allow you to specify the type hints using Python 3 syntax for both Python 2 and 3.

The stub files are created as usual , but you must specify the extension .pyi explicitly.

IntelliJ IDEA shows an asterisk in the left gutter for those Python files that have stubs:

images/py_stub1.png

Clicking the asterisk results in jumping to the corresponding file with the .pyi extension:

images/py_stub2.png

Legacy type syntax for docstrings

IntelliJ IDEA supports legacy approach to specifying types in Python using docstrings. So doing, the supported formats are:

To choose the desired docstring format, use the Java Intergated Tools page of the Settings/Preferences dialog.

Type syntax in Python docstrings is not defined by any standard. Thus, IntelliJ IDEA suggests the following notation:

SyntaxDescription
FooClass Foo visible in the current scope
x.y.Bar Class Bar from x.y module
Foo | Bar Foo or Bar
(Foo, Bar) Tuple of Foo and Bar
list[Foo] List of Foo elements
dict[Foo, Bar]  Dict from Foo to Bar
T Generic type (T-Z are reserved for generics)
T <= Foo Generic type with upper bound Foo
Foo[T] Foo parameterized with T
(Foo, Bar) -> Baz Function of Foo and Bar that returns Baz
list[dict[str, datetime]] List of dicts from str to datetime (nested arguments)

Specifying types of local variables

Consider adding information about the expected type of a local variable using :type or @type docstrings:

images/py_type_hinting_local_var1.png

It is also possible to use isinstance to define the expected local variable type:

images/py_type_hinting_local_var2.png

Specifying types of fields

You can use type hinting to specify the expected type of fields:

images/py_type_hinting_field.png

Alternatively, you can specify types of fields in the docstring of a class:

images/py_type_hinting_class_attributes.png

Specifying return types

Use docstrings :rtype or @rtype to specify the expected return type:

py_type_hinting_return2

  • :rtype: collections.Iterable[int] # return type: 'items' is of type generator or collections.Iterable, 'a' is of type int, see the following code: 
    def my_iter():
    for i in range(10):
        yield i
        items = my_iter()
    for a in items:
        print a
  • :rtype: list[int] for my_iter # return type: 'a' is of type int, see the following code: 
    def my_iter():
    for i in range(10):
        yield i
    for a in my_iter():
        print a

Specifying parameter types

Consider adding information about the expected parameter type. This information is specified using :type or @type docstrings, for example, :param "type_name" "param_name": "param_description".

py_type_hinting_param1

Converting comments

For comment-based type hints, IntelliJ IDEA suggests an intention action that allows you to convert comment-based type hint to a variable annotation. This intention has the name Convert to variable annotation, and works as follows:

This is available for Python 3.6!

BeforeAfter
from typing import List, Optional

xs = []  # type: List[Optional[str]]
 
from typing import List, Optional

xs: List[Optional[str]] = []