PyCharm 2018.2 Help

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 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: 7 August 2018