What are Python Docstrings and How Are They Used?

Python Docstring

This tutorial will explain what docstrings are in the Python programming language and how they can be used.

What is a Docstring in Python?

docstring is a string literal that is used to document your code.

A string literal is a sequence of characters 0 or more characters in length, which is to be treated as a single entity – i.e., it’s a string variable of any length.

docstring appears after the definition of a module, class, method, or function and should explain the purpose of the object it appears under.

These docstrings can then be accessed to find out about the module, class, method, or function you are using.

Defining a Docstring – Triple Quotes!

A docstring is defined a bit differently from regular strings. For example, it’s not assigned to a variable name, and it’s triple quoted instead of single-quoted.

Here’s a single line docstring:

""" This is a single line docstring """

Here’s a multi-line docstring:

"""
This is the first line of a multi-line docstring
This is the second line of a multi-line docstring

"""

Using Docstrings for Code Documentation

The primary purpose of a docstring is to document your code (hence the name).

Here’s the best practice for documenting various objects in Python.

Documenting Functions & Methods

When creating a docstring to document a function or method, the docstring should be placed immediately after the function declaration, inside the function code block.

It’s best practice to document the purpose of a function, the parameters the function accepts, and the value it is expected to return.

def multiplyNumbers(num1, num2):
    """
    Multiplies two given numbers passed as parameters

    Parameters:
    num1 (integer)
    num2 (integer)

    Returns:
    The product of num1 and num2

    """
    return num1 * num2

Documenting Classes

When creating a docstring to document a class, the docstring should be placed immediately after the line declaring the class inside the class code block.

Additional docstrings can be placed inside the class to document class methods.

Class FoodItem
    """
    A class representing a food item

    Attributes:
    name - The name of the food
    colour - The colour of the food
    category - The category of the food

    Methods:
    getFoodDetails() - returns all of the attributes in a single string
    randomFoodColour() - changes the colour of the food to one at random

    """

        def __init__(name, colour, category):
        """
        Class constructor 
        Defines and sets the attributes for the FoodItem Class

        Parameters:
        name (string)
        colour (string)
        category (string)
        """

        self.name = name
        self.colour = colour
        self.category = category

    # Code continues to define functions, etc

Documenting Modules

When documenting a module, you should document everything the module exports – so that when you access the docstring after importing the module, it can remind you what the module provides.

When documenting a module, the docstring should simply go at the top of the main Python file for the module.

The below docstring example is for a module FoodModule which performs some food-related tasks:

"""
FoodModule
Provides food related classes and functions

Classes:
FoodItem - a food item which contains name, colour and category fields
FoodContainer - a container which can hold a food item, with foodItem and containerShape fields

Functions:
ContainFood - adds a given food item to a given container
UncontainFood - removes a given food item from a given container
"""

# Code continues here

Accessing Docstrings with the doc Attribute

You can access the docstring for a module, function, method, or class by viewing its doc attribute:

print(multiplyNumbers.__doc__)

Accessing Docstrings with the help() Function

The help() function is built-in to Python and will display the docstring for a given object – this will not just print the docstring, but it will display the documentation for the function in an interactive shell similar to using the man command in the Linux shell:

help(multiplyNumbers)

Note that calling the help() function will halt the execution of your Python code until the q key is pressed to exit viewing the documentation/docstring.

Using Docstrings as Multi-line Comments

Docstrings can also be used to add multi-line comments to your Python code – find out more about that here.

SHARE:
nv-author-image

Brad Morton

I'm Brad, and I'm nearing 20 years of experience with Linux. I've worked in just about every IT role there is before taking the leap into software development. Currently, I'm building desktop and web-based solutions with NodeJS and PHP hosted on Linux infrastructure. Visit my blog or find me on Twitter to see what I'm up to.

Leave a Reply

Your email address will not be published. Required fields are marked *