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

Syntax

Description

Foo

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

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: 01 October 2021