How To Create A Docstring In Python

Docstrings

Docstrings in Python are string literals that occur as the first statement in a module, function, class, or method definition. Using docstrings you can provide documentation for the code that you write.

Every Python library comes with proper documentation. In this tutorial, we will learn how to access these docstrings and how to set docstrings for your own functions. Let's get started.

First we will learn how to access Docstrings of Python modules.

How to access Docstrings in Python?

There are two methods available for accessing Docstrings. These are:

Using help()
Using .__doc__

Let's look at how to use these.

Method 1: Using help() to access Python module docstrings

You can access the docstring of a module in Python using the help method as shown :

import matplotlib help(matplotlib)

Output :

Helpmatplotlib docstrings in Python — help(matplotlib)

You can also use help to get the docstring for a particular package.

Output :

Help On Package docstrings in python — Help On Package

Similarly, you can also access the docstrings of a specific function under matplotlib.

help(matplotlib.pyplot.axis)

Output :

Method 2: Using .doc method to access module docstrings

You can access the docstring of a module using the .__doc__ method:

import matplotlib print(matplotlib.__doc__)

Output :

How to create your own Docstrings in Python?

In this section, we will learn how to add docstrings to the functions that we write in Python. Later we will use the two methods discussed above to access these docstrings.

You can either give a one-line docstring or a multi-line docstring to your function.

One-line docstrings usually contain a summary of what the function does.

Multi-line docstrings consist of:

A summary line just like a one-line docstring
followed by a blank line
followed by a more elaborate description.
It is a good practice to also provide a description of arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable).

Docstrings are written in accordance with the PEP 257 Docstring conventions.

How to write a single-line docstring in Python?

Let's write a simple function and add a docstring to it.

def sample_func():    ''' this function prints Hello World. '''    print("Hello World")   return

Let's try accessing the docstring with the two methods we discussed.

def sample_func():    ''' this function prints Hello World. '''    print("Hello World")   return  print("Method-1:-") help(sample_func) print("Method-2:-") print(sample_func.__doc__)

Output :

Method-1:- Help on function sample_func in module __main__:  sample_func()     this function prints Hello World.  Method-2:-  this function prints Hello World.

How to write multi-line docstrings in Python?

Let's write a multi-line docstring for our function. The common convention is to leave a line blank after every line in the docstring.

def sample_func():    '''    this function prints Hello World.           This is a multi-line docstring.        You can add a more descriptive help section        for your function here.          '''    print("Hello World")   return

Let's try accessing the docstring with the two methods we learnt.

def sample_func():    '''    this function prints Hello World.           This is a multi-line docstring.        You can add a more descriptive help section        for your function here.          '''    print("Hello World")   return  print("Mehtod-1 :-") help(sample_func) print("Mehtod-2 :-") print(sample_func.__doc__)

Output :

Mehtod-1 :- Help on function sample_func in module __main__:  sample_func()     this function prints Hello World.               This is a multi-line docstring.              You can add a more descriptive help section          for your function here.  Mehtod-2 :-     this function prints Hello World.           This is a multi-line docstring.        You can add a more descriptive help section        for your function here.

You can also use double quotes(") in place of single quotes(').

def sample_func():    """   this function prints Hello World.           This is a multi-line docstring.        You can add a more descriptive help section        for your function here.          """    print("Hello World")   return  print("Mehtod-1 :-") help(sample_func) print("Mehtod-2 :-") print(sample_func.__doc__)

Output :

Mehtod-1 :- Help on function sample_func in module __main__:  sample_func()     this function prints Hello World.               This is a multi-line docstring.              You can add a more descriptive help section          for your function here.  Mehtod-2 :-    this function prints Hello World.           This is a multi-line docstring.        You can add a more descriptive help section        for your function here.

Conclusion

This tutorial was about Docstrings in Python. We learn how to access a docstring using help and .__doc__ and how to create Docstrings in a function. Hope you had fun learning with us!