IntelliJ IDEA 2016.3 Help

Using Docstrings to Specify Types

On this page:

Introduction

You debug your code permanently, and now in course of debugging you can also collect type information and specify these types in docstrings.

IntelliJ IDEA provides an intention action that makes it possible to collect type information at runtime, and define type specifications.

However, it is quite possible to specify the types of parameters manually, without the debugger.

Both cases are explored in the section Examples.

Prerequisite

Make sure that the check box Collect run-time types information for code insight in the Python Debugger page of the Debugger settings is selected.

Parameter type specification

To specify the parameter types, follow these general steps

  1. Open the desired Python class in the editor, and debug its calls.
  2. Place the caret at the function name, and press Alt+Enter.
  3. In the list of intention actions that opens, choose Insert documentation string stub. IntelliJ IDEA creates a documentation stub, according to the selected docstring format, with the type specification, collected during the debugger session.

Examples

Consider the following code:

import math class SimpleEquation: def demo(self, a, b, c): d = math.sqrt(b ** 2 - 4 * a * c) root1 = (-b + d) / (2 * a) root2 = (-b - d) / (2 * a) print(root1, root2) SimpleEquation().demo(3, 2, 1)

Let us suppose that reStructuredText has been selected as the docstring format on the page Python Integrated Tools.

Manually

Place the caret at the name of the function (here it is demo). The suggested intention action is Insert documentation string stub (refer to the section Creating Documentation Comments for details). Click this intention to produce the documentation comment stub in reStructuredText format:

/help/img/idea/2016.3/docstring_example_1.png

Then, manually specify the desired types of the parameters:

/help/img/idea/2016.3/docstring_example_10.png

Note that is's possible to specify types in two modes:

  • :param param_type param_name: parameter description (type description is on the same line as the parameter description).
  • :type param_name: param_type (type description is on a separate line)

Both variants are shown below:

/help/img/idea/2016.3/docstring_example_100.png

with the aid of the debugger

In the Settings/Preferences dialog, do the following:

  1. In the Python Debugger page of the debugger settings, select the check box Collect run-time information for code insight.
  2. In the Smart Keys page of the editor settings, select the check box Insert type placeholders in the documentation comment stub (if this check box is selected, the type placeholders are generated.)

Debug the function call. IntelliJ IDEA collects information about types, and suggests intention action Insert documentation string stub. To show this intention action, it is enough to place the caret at the function declaration.

/help/img/idea/2016.3/docstring_example_2.png

The obtained results is:

/help/img/idea/2016.3/docstring_example_11.png

Next, select Epytext format of the docstrings, and repeat the whole procedure. The documentation comment with types includes parameters in Epytext format.

/help/img/idea/2016.3/docstring_example_4.png

See Also

Last modified: 29 November 2016