Python docstring

In Python, a docstring is a string literal used to document various Python objects, such as functions, modules, classes, their methods, and packages. It is the first line in the definition of any of these structures and becomes the value of the doc attribute.

Function Docstring

def addition(x, y):
'''This function returns the sum of two numeric arguments'''
return x+y
print ("Docstring of addition function:", addition.__doc__)

This will produce the following output –

Docstring of addition function: This function returns the sum of two numeric arguments

Docstrings can be written using single, double, or triple quotes. However, in most cases, you’ll want to include descriptive text as documentation, so triple quotes are preferred.

All built-in modules and functions have a doc attribute that returns their docstring.

Docstring of the math module

import math

print ("Docstring of math module:", math.__doc__)

This will produce the following output –

Docstring of math module: This module provides access to the mathematical functions
defined by the C standard.

Docstrings for built-in functions

The following code shows the docstrings for the abs() and randint() functions in the random module.

print ("Docstring of built-in abs() function:", abs.__doc__)
import random

print ("Docstring of random.randint() function:",
random.randint.__doc__)

It will produce the following output −

Docstring of built-in abs() function: Return the absolute value of the
argument.

Docstring of random.randint() function: Return a random integer in the range
[a, b], including both end points.

Documentation Strings for Built-in Classes

Documentation strings for built-in classes are typically more explanatory, so the text spans multiple lines. Next, we examine the documentation string for the built-in dictionary class.

print ("Docstring of built-in dict class:", dict.__doc__)

This will produce the following output –

Docstring of built-in dict class: dict() -> new empty dictionary
dict(mapping) -> new dictionary initialized from a mapping object's
(key, value) pairs
dict(iterable) -> new dictionary initialized as if via:
d = {}
for k, v in iterable:
d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

Documentation String for the Template Class

The Template class is defined in the string module of the Python standard library. Its documentation string is as follows:

from string import Template

print ("Docstring of Template class:", Template.__doc__)

This will produce the following output: −

Docstring of Template class: A string class for supporting $- substitutions.

Documentation Strings in the Help System

Documentation strings are also used by Python’s built-in help service. For example, check the help information for the abs() function in the Python interpreter:

>>> help (abs)
Help on built-in function abs in module builtins:
abs(x, /)
Return the absolute value of the argument.

Similarly, define a function in the interpreter terminal and run the help command.

>>> def addition(x,y):
... '''addition(x,y)
... Returns the sum of x and y
... '''
... return x+y
...
>>> help (addition)
Help on function addition in module __main__:
addition(x, y)
addition(x,y)
Returns the sum of x and y

Document strings are also used by integrated development environments (IDEs) to provide helpful auto-completion information while editing code.

Documentation Strings as Comments

String literals appearing anywhere other than within a function, method, class, module, or package object are ignored by the interpreter, so they are similar to comments (starting with a # symbol).

# This is a comment
print ("Hello World")
'''This is also a comment'''
print ("How are you?")