PyCharm 2017.1 Help

Using Docstrings to Specify Types

In this section:

Introduction

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

PyCharm 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 Insert type placeholders in the Smart Keys page of the editor settings is selected.

Note also, that reStructuredText is used for all the subsequent examples, but it is possible to use any of the supported formats of the documentation strings, whether it is plain text, Epytext, Google or NumPy. Refer to the description of the page Python Integrated Tools for details.

Parameter type specification

To specify the parameter types, follow these general steps

  1. Place the caret at the function name, and press Alt+Enter.
  2. In the list of intention actions that opens, choose Insert documentation string stub. PyCharm 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/2017.1/docstring_example_1.png

Then, manually specify the desired types of the parameters:

/help/img/idea/2017.1/docstring_example_10.png

By the way, you can use quick documentation for the function in question. If you position the caret at the function name and press Ctrl+Q, you will see:

/help/img/idea/2017.1/docstring_example_10_quick_documentation.png

Important note about reStructuredText/Sphinx

Note that for the reStructuredText it's possible to specify types in two formats:

  • :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/2017.1/docstring_example_100.png

With the aid of the debugger

Now, in the Python Debugger page of the Settings/Preferences dialog, select the check box Collect run-time information for code insight.

Debug the function call, and use intention action Insert documentation string stub again. Information about the arguments and return values obtained during the debugging session will be used to pre-populate type annotations in a docstring.

/help/img/idea/2017.1/docstring_example_2.png

The obtained result is:

/help/img/idea/2017.1/docstring_example_11.png

See Also

Language and Framework-Specific Guidelines:

Last modified: 26 July 2017