How to Use Docstrings in Python

Today we’ll be talking about docstrings.

Here’s the video version:

Docstrings are used to document functions, classes and modules. They’re placed at the top of a function or class definition or at the top of a module file, before any executable code.

Docstrings are strings, as the name suggests and they are stored in the __doc__ attribute of the object they document. Docstrings are often used in triple quotes, which allows for multiline text, but it’s not a requirement, any string will do.

Here’s how we document a module, a class and a function using docstrings:

"""
This module contains classes and functions
that can be used to perform fascinating 
operations.
"""

def func(n1, n2):
    """
    This function is used to 
    do a lot of interesting stuff.
    """
    pass

class Adder:
    """
    This class is used as a helper
    class that makes life easier.
    """
    pass

Learn how to make beautiful GUI apps

in Python using the Kivy framework.

Comprehensive, for Kivy beginners, easy to follow.

Get the book here (PDF) or on Amazon:

ebook / paperback (black and white) / paperback (full color)

The code above doesn’t do anything useful but it uses docstrings for the module, class and function. Let’s save this file as example.py and then let’s import the module in interactive mode. Now watch how we can use the __doc__ attribute to retrieve the documentation:

>>> import example
>>> print(example.__doc__)

This module contains classes and functions
that can be used to perform fascinating 
operations.

>>> print(example.Adder.__doc__)

    This class is used as a helper
    class that makes life easier.
    
>>> print(example.func.__doc__)

    This function is used to 
    do a lot of interesting stuff.

Your Panda3D Magazine

Make Awesome Games and Other 3D Apps

with Panda3D and Blender using Python.

Cool stuff, easy to follow articles.

Get the magazine here (PDF).

If you’re using Visual Studio or one of the other IDEs that support Intellisense, you can now hover your mouse cursor over the name of the function or class wherever it’s used in your code and you will see Intellisense display the documentation for that object.

You can also view the documentation of built-in types (modules, classes, functions) using the __doc__ attribute:

Let’s start with a module, like for example the random module:

# module
>>> import random
>>> print(random.__doc__)
Random variable generators.

    integers
    --------
           uniform within range

    sequences
    ---------
           pick random element
           pick random sample
           pick weighted random sample
           generate random permutation

    distributions on the real line:
    ------------------------------
           uniform
           triangular
           normal (Gaussian)
           lognormal
           negative exponential
           gamma
           beta
           pareto
           Weibull

    distributions on the circle (angles 0 to 2pi)
    ---------------------------------------------
           circular uniform
           von Mises

General notes on the underlying Mersenne Twister core generator:

* The period is 2**19937-1.
* It is one of the most extensively tested generators in existence.
* The random() method is implemented in C, executes in a single Python step,
  and is, therefore, threadsafe.

Python Jumpstart Course

Learn the basics of Python, including OOP.

with lots of exercises, easy to follow

The course is available on Udemy.

And now a class. How about the complex class?

# class
>>> print(complex.__doc__)
Create a complex number from a real part and an optional imaginary part.

This is equivalent to (real + imag*1j) where imag defaults to 0.

Blender Jumpstart Course

Learn the basics of 3D modeling in Blender.

step-by-step, easy to follow, visually rich

The course is available on Udemy and on Skillshare.

Finally a function. Let it be the len function:

# function
>>> print(len.__doc__)
Return the number of items in a container.

However, although you can read the documentation this way, you don’t have to. Instead you can use the help function which will do it automatically for you.