Docstrings in Python
Sign up for FREE 1 month of Kindle and read all our books for free.
Get FREE domain for 1st year and build your brand new site
Reading time: 25 minutes
In this article we'll go through the Docstrings in Python. Docstrings stand for Documentation Strings.
Docstrings like comments provide us a convenient way of associating documentation to the source code. Unlike comments docstrings are not stripped but are retained through out the runtime of the program. They specify what the function does not how it does. Docstrings are used in functions, classes etc.
Docstrings Declaration
The docstrings are declared using a triple double quotes like """Docstring""". The docstring should should begin with a capital letter and end with a period.
"""Docstring."""
Accessing the Docstrings
The docstrings are accessed using the __ doc __ method or using the help() function.
Using the __ doc __ Method
>>> def my_doc():
"""This is a docstring"""
return None
>>> print(my_doc.__doc__)
This is a docstring
Using help() function
>>> def my_doc():
"""This is a docstring"""
return None
>>> help(my_doc)
Help on function my_doc in module __main__:
my_doc()
This is a docstring
Types of Docstrings
There are two types of docstrings. They are
 One line docstrings
 Multi line docstrings
One Line Docstrings
One line docstring fits in one line. In a one line docstring the opening and closing triple quotes lie on the same line.
>>> def square(a):
"""returns the square of arg"""
return a*a
>>> print(square.__doc__)
returns the square of arg
Multi Line Docstrings
In a multiline docstring the first line contains the summary of the docstring and the second line should be blank seperating the summary from the rest. The summary can be in the same line of the quotes or in the next line.
>>> def myfunc(arg):
"""
1st line contains the summary.
arg means argument.
This function returns nothing.
"""
return None
>>> print(myfunc.__doc__)
1st line contains the summary.
arg means argument.
This function returns nothing.
Docstrings in classes
Docstrings are also used in classes. In classes the docstrings are placed immediately after the class or class method indented by one level.
To access the Class Docstring
>>> class square:
"""This is a class for finding the perimeter of a square"""
def __init__(self,num):
"""
The constructor for complex number class.
Parameters:
num(int):The side of the square
"""
def perimeter(self):
"""
The function to calculate the perimeter.
Parameters:
self: The side of the square.
Returns the perimeter of te square.
"""
p = 4 * self.num
return square(p)
>>> help(square) #To access the class docstring
Help on class square in module __main__:
class square(builtins.object)
 square(num)

 This is a class for finding the perimeter of a square

 Methods defined here:

 __init__(self, num)
 The constructor for complex number class.

 Parameters:
 num(int): The side of the square

 perimeter(self)
 The function to calculate the perimeter.

 Parameters:
 self: The side of the square.

 Returns the perimeter of te square.

 
 Data descriptors defined here:

 __dict__
 dictionary for instance variables (if defined)

 __weakref__
 list of weak references to the object (if defined)
To access the class docstring we used the help() function and passed the class name square as the argument.
To access the Method's Docstring
>>> class square:
"""This is a class for finding the perimeter of a square"""
def __init__(self,num):
"""
The constructor for complex number class.
Parameters:
num(int):The side of the square
"""
def perimeter(self):
"""
The function to calculate the perimeter.
Parameters:
self: The side of the square.
Returns the perimeter of te square.
"""
p = 4 * self.num
return square(p)
>>> help(square.perimeter) #To access the method's docstring
Help on function perimeter in module __main__:
perimeter(self)
The function to calculate the perimeter.
Parameters:
self: The side of the square.
Returns the perimeter of the square.
Here, to access the method's docstring we used help() function and passed the method square.perimeter as the argument.
Indentation in Docstrings
Any indentation in the first line of the docstring is insignificant and removed. Relative indentation of the later lines of the docstring is retained. Blank lines should be removed from the beginning and from the end of the docstring.