PyCharm 2023.3 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 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 | Tools | Python Integrated Tools).

Using docstrings to define parameter type(:type)
Using docstrings to define parameter type(Args)
Last modified: 11 January 2024