1. Python
  2. Type hinting in PyCharm

Type hinting in PyCharm

Last modified: 11 January 2023

PyCharm provides various means to assist inspecting and checking the types of the objects in your script. PyCharm supports type hinting in function annotations and type comments using the typing module and the format defined by PEP 484.

Adding type hints

Although PyCharm 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.

Example

Intention Action

Resulting Code for annotations (Python 3)

Variables

example of adding a type hint for a variable
example of adding a type hint for a variable (Python 3)

Functions

example of adding a type hint for a function
example of adding a type hint for a function (Python 3)

Class attributes

example of adding a type hint for a class attribute
example of adding a type hint for a class attribute (Python 3)

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

Converting comments 

For comment-based type hints, PyCharm 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:

warning

This feature is available in Python 3.

Before

After

from typing import List, Optional

xs = []  # type: List[Optional[str]]
from typing import List, Optional

xs: List[Optional[str]] = []

Type hints validation

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

Validation error

Suggested 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.

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.

Unexpected type in assignment expressions.

Unexpected type in an assignment expression

Align the types to match the expected pattern.

Assigning a value to a Final variable.

Assigning a value to a Final variable

You cannot alter a variable annotated as Final. Consider changing the type of the variable.

Inheriting a class annotated as Final.

Inheriting a final class

You cannot inherit a class with a Final annotation. Consider creating another class.

Overriding a method decorated with @final.

Overriding a final method

You cannot override a method decorated with @final. Consider defining another method.

Incorrect type of the function argument.

Function argument type validation

Pass a dictionary to the foo() function instead of a list.

Assigning a wrong type of value to the key in a TypedDict type.

Type validation for a TypedDict class

Provide the value of year as int:

add_movie({'title': 'Blade Runner', 'year': 1982})

Using wrong keys in a TypedDict type:

Missing key, extra key error

Assign the keys as specified in the type definition:

add_movie({'title': 'Blade Runner', 'year': 1982})

Incorrect usage of a decorated function. PyCharm validates the types of decorated functions based on the types of their decorators:

Infer type of a decorated function

Modify the decorator or the statement that uses the function return as required.

You can add a # type: ignore or # noqa comment to suppress a type validation warning or ignore a missing import statement.

Ignore type validation

Python stubs

You can use Python stub files to specify type hints using Python 3 syntax. Those hints will be available in your Python files regardless of which Python version is used in the interpreter.

In the following example type hints for sample_function from a stub file (stubs.pyi) become available in the Python file (stubs.py):

If you're using a package for which a stub analog is detected, the following message appears:

The stub package inspection

You can install the stub package, ignore this message and continue working with the currently installed package, or disable this kind of inspection in the project Settings.

note

When you choose to install the package, PyCharm attempts to install the latest available version of the stub package. If it is incompatible with the currently used non-stub package, the installation process will be terminated.

tip

You can specify a specific version of the package to be installed in the Available Packages dialog.

Using Typeshed

Typeshed is a set of files with type annotations for the standard Python library and various packages. Typeshed stubs provide definitions for Python classes, functions, and modules defined with type hints. PyCharm uses this information for better code completion, inspections, and other code insight features.

PyCharm comes bundled with Typeshed stubs. The list of available Typeshed stubs is shown in the project view under the node External Libraries | <Python interpreter> | Typeshed Stubs.

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 https://github.com/JetBrains/python-skeletons is now deprecated.

See also

Python Support

Procedures