IntelliJ IDEA 2018.2 Help

Type Hinting in IntelliJ IDEA

IntelliJ IDEA provides various means to assist inspecting and checking the types of the objects in your script. This smart assistance is known as type hinting.

Support for PEP 484 type hints

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

NewType Support

The NewType helper function in PEP 484 facilitates creating simple classes. Its support can be enabled in IntelliJ IDEA by adding the corresponding import. Below is the example that solves a task opposite to one exampled in PEP 484. It builds a user Id by a user name.
from typing import NewType UserName = NewType('UserName', str) def id_by_name (user_name: UserName) -> int: pass UserName(33) # Integer is not allowed - correct warning id_by_name('John') # String is also not allowed - correct warning id_by_name(UserName('John')) # UserName is ok name = UserName('John') + 'Smith' # UserName object inherits all parent type methods

Adding type hints

Although IntelliJ IDEA supports all methods for adding types supported in PEP 484, using type hints through intention actions is the most convenient way. Depending on the interpreter you use, the type is added as an annotation (Python 3) or as a comment (Python 2).

To add a type hint, follow these steps:

  1. Select a code element.
  2. Press Alt+Enter.
  3. Select Add type hint for ....
  4. Press Enter to complete the action or edit the type if appropriate.
ExampleIntention ActionResulting Code
example of adding a type hint for a variable
example of adding a type hint for a variable
example of adding a type hint for a function
example of adding a type hint for a function
Class attributes
example of adding a type hint for a class attribute
example of adding a type hint for a class attribute

You can also use Python stubs or comments to specify the types of variables, functions, and class fields.

Specifying types by using comments

Use a # type: comment to specify the types of local variables and attributes:

py type hinting attributes

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, but you must specify the extension .pyi explicitly.

IntelliJ IDEA 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

Type hints validation

Any time you're applying type hints, IntelliJ IDEA checks if the type is used correctly. If there is a usage error, the corresponding warning is shown and the recommended action is suggested. Below are the validation examples.

Validation errorSuggested action
Duplication of type declaration.
incorrect type hint
Remove either of the type declarations.
Number of arguments in the type declaration differs from the number of function arguments.
too many arguments
Adjust the number of the arguments.
Missing brackets.
missing bracket
Add the required brackets where appropriate.

Type comments with unpacking do not match the corresponding targets.

incorrect type for unpacked variables

Check the target format and modify the type comment accordingly.

Incorrect syntax of Callable parameters.
Incorrect Callable format
Use the suggested format and add the required brackets to wrap Callable parameters.

Enabling postponed evaluation of annotations

IntelliJ IDEA supports changes introduced in PEP-563. With these changes, function and variable annotations are no longer evaluated at function definition time. Instead, a new __future__ import enables their postponed evaluation. Consider the following sample code:

class Foo: def foo(self) -> 'Foo': ... class Bar: def bar(self, param: 'Bar'): ...
With the __future__ import applied, you can benefit from forward references and avoid using string literals for class definitions:
from __future__ import annotations class Foo: def foo(self) -> Foo: ... class Bar: def bar(self, param: Bar): ...

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

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:

  • :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".


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:

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 Java library and various packages. Typeshed stubs provide definitions for Java classes, functions, and modules defined with type hints. IntelliJ IDEA uses this information for better code completion, inspections, and other code insight features.

IntelliJ IDEA is switching to Typeshed, the common repository for Java stubs. The Typeshed stubs bundled with IntelliJ IDEA are shown in the project view under the node External Libraries | <Python interpreter> | Typeshed Stubs. Note that IntelliJ IDEA 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 is now deprecated.

Last modified: 18 June 2018

See Also