PyCharm 2016.3 Help

Type Hinting in PyCharm

In this section:

Following PEP484

PyCharm 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:

/help/img/idea/2016.3/py_type_hinting_attributes.png

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

Python stubs

PyCharm 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.

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

/help/img/idea/2016.3/py_stub1.png

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

/help/img/idea/2016.3/py_stub2.png

Legacy type syntax for docstrings

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

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

Type syntax in Python docstrings is not defined by any standard. Thus, PyCharm 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:

/help/img/idea/2016.3/py_type_hinting_local_var1.png

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

/help/img/idea/2016.3/py_type_hinting_local_var2.png

Specifying types of fields

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

/help/img/idea/2016.3/py_type_hinting_field.png

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

/help/img/idea/2016.3/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

See Also

Last modified: 23 December 2016