Docstrings in Python

Summary: In this tutorial, we will learn what are docstrings in Python and how are they useful. In addition, we will also learn to write docstrings for classes, functions, and modules in Python.

What is a Docstring?

The docstring in Python is a string literal that serves as the documentation code for the python object (module, class, method, or function) in which it is defined.

It helps in knowing what the particular object intends to do, what parameters it accepts, and what data it may return (if the object is a function).

For example, if we want to know what the math module does in Python, we should read its docstring (documentation code):

>>> import math
>>> print(math.__doc__)
This module provides access to the mathematical functions
defined by the C standard.

Similarly, we can read the docstrings of methods and classes to know what they intend to do.

>>> print(math.sqrt.__doc__)
Return the square root of x.

How to Access Docstrings in Python?

There are two ways to access the docstring of a Python object:

1. Using the __doc__ attribute
2. Using the help() function

Unlike the __doc__ attribute which only describes the Python object, the help() function provides the full documentation of the object with information such as what parameters the function accepts and the task it performs, what functions and variables are available in a particular module, etc.

>>> print(math.pow.__doc__)
Return x**y (x to the power of y).
>>> help(math.pow)
Help on built-in function pow in module math:
pow(x, y, /)
    Return x**y (x to the power of y).

When executing code in Python shell, the __doc__ attribute and help() function often helps to learn about python objects that we have little information about.

How to Write Own Docstrings?

Each in-built module, function, and class have docstrings defined in Python, and Python allows doing the same for our own objects.

To define a docstring for an object, write them as string literals using the triple quotes (''' or """) as the first line of the object.

Here, for example, we have defined a docstring for a function that multiplies two numbers:

>>> def multiply(a, b):
...    '''Returns the multiplication of a and b.'''
...    return a*b

Now, if we try to access the __doc__ attribute of the function, we get the same docstring as the result:

>>> print(multiply.__doc__)
Returns the multiplication of a and b.

Using the same approach, we can write docstrings for Python classes and modules.

>>> class Student:
...     '''Student class represent a student.'''
...     def __init__(self, name):
...         '''__init__ accepts name of the student'''
...         self.name = name
...         
...     def display(self):
...         '''Displays the name of the student instance.'''
...         print("Name:",self.name)
... 
>>> help(Student)
Help on class Student in module __main__:
class Student(builtins.object)
 |  Student(name)
 |  
 |  Student class represent a student.
 |  
 |  Methods defined here:
 |  
 |  __init__(self, name)
 |      __init__ accepts name of the student
 |  
 |  display(self)
 |      Displays the name of the student instance.

The PEP 257 documentation provides the standard convention of writing a docstring in Python that can be summarized as:

• The docstring should describe what the function does, not how it works.
• The first line of the docstring should be a short and easy to understand.
• Divide the multiple-line docstring with line breaks.

Multi-Line Docstrings

Since we are writing docstring using triple quotes, it is not just limited to a single line. We can expand the docstring on multiple lines depending on the need.

For example, we can add more lines to the docstring to describe what parameters does the function accepts:

>>> def display(name='', id=-1):
...     '''Displays informations of the user.
...     
...     Parameters:
...         name (string): name of the user.
...         id (int): id of the user.
...     '''
...     print("Name:", name)
...     print("ID:", id)
... 
>>> print(display.__doc__)
Displays informations of the user.
    
    Parameters:
        name (string): name of the user.
        id (int): id of the user.

Similarly, we should define the docstrings for modules and classes, especially when they need to be exported to reuse in another module.

Writing docstrings for modules, classes, functions, or methods in Python helps other programmers to easily understand the code and is also a good programming practice.