PyCharm 2021.1 Help

Legacy type syntax for docstrings

PyCharm supports legacy approach to specifying types in Python using docstrings. In doing so, 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.BarClass Bar from x.y module
Foo | BarFoo or Bar
(Foo, Bar)Tuple of Foo and Bar
list[Foo]List of Foo elements
dict[Foo, Bar]Dict from Foo to Bar
TGeneric type (T-Z are reserved for generics)
T <= FooGeneric type with upper bound Foo
Foo[T]Foo parameterized with T
(Foo, Bar) -> BazFunction 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:

Type hinting for local vars

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

Type hinting for local vars

Specifying types of fields

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

Type hinting for fields

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

Type hinting for 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(): global i 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 docstrings. You can use different docstrings depending on the selected docstring format, for example, :type, @type, or Args. Use project settings to alter the docstring format (File | Settings/Preferences | Tools | Python Integrated Tools).

Using docstrings to define parameter type(:type)
Using docstrings to define parameter type(Args)
Last modified: 08 March 2021