Python Docstrings

We can comment the code in a python program to understand parts of the code. But to search for the comments and different parts of the comment we need to use the search(CTL+F) and we scroll through many lines. Also we have not the immediate way of knowing a given word being associated with how many sections of the code etc. To solve this issues, we have python Docstring which accesses the strings immediately after the definition of a function, module, class or method.

Print a Docstring

The __doc__ attribute is automatically associated with the name of the python object when it si declared immediately after the definition of that object. Below examples that make it clear.

Example

 Live Demo

def Add_nums(x):
   '''Ada a number to itself.'''
   return x + x
print(Add_nums.__doc__)

Output

Running the above code gives us the following result −

Ada a number to itself.

Single Line versus Multiline docsrings

The single-line docstrings are of one line and they should not be too descriptive. They are enclosed within triple quotes at the beginning and end of the string. The example above is a single line docstring.

Multi-Line docstring

Sometimes we may need to describe the module or function in more details. In that case we use the multi-line docstring. They show a summary line just like a one-line docstring and then a blank line, followed by a more elaborate description.

Example

 Live Demo

def Fibonacci(n):
   '''The Fibonacci numbers are the numbers in the following integer sequence.
0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, .'''
   return x + x
print(Fibonacci.__doc__)

Output

Running the above code gives us the following result −

The Fibonacci numbers are the numbers in the following integer sequence.
0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, .

Docstring of in-built Python objects

We can easily access the documentation associated with python objects like function, modules etc by using the class name along with __doc__.

Example

print(list.__doc__)

Output

Running the above code gives us the following result −

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list.
The argument must be an iterable if specified.

Indentation in Docstrings

Any indentation in the first line of the docstring (i.e., up to the first newline) is insignificant and removed. Relative indentation of later lines in the docstring is retained. The entire docstring is indented the same as the quotes at its first line.