PyCharm 2017.3 Help

Type Hinting in PyCharm

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:

py type hinting attributes

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:

py stub1

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

py stub2

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

py type hinting local var1

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

py type hinting local var2

Specifying types of fields

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

py type hinting field

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

py type hinting class attributes

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

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

Using Typeshed

Typeshed is a set of files with type annotations for the standard Python library and various packages. Typeshed stubs provide definitions for Python classes, functions, and modules defined with type hints. PyCharm uses this information for better code completion, inspections, and other code insight features.

PyCharm is switching to Typeshed, the common repository for Python stubs. The Typeshed stubs bundled with PyCharm are shown in the project view under the node External Libraries | <Python interpreter> | Typeshed Stubs. Note that PyCharm currently uses only a few of the bundled stubs (i.e. builtins.pyi, typing.pyi, and several others).

To override the bundled Typeshed repository with your own version, follow these steps:

  1. Copy some or all the stubs into a directory in your project.
  2. Mark a directory as a source root by choosing Mark Directory as | Sources Root from the context menu of the directory.

The Python skeletons repository https://github.com/JetBrains/python-skeletons is now deprecated.

Last modified: 28 March 2018

See Also