docstrings.md

Help and Docstrings

In this tutorial we have used help() a few times. It's great and you can use it as much as you want to. For example, running help(str) displays a nice list of all string methods and explanations of what they do, and help(list.extend) explains what extending something to a list does.

You can get help of many other things too. For example:

>>> stuff = []
>>> help(stuff.append)
Help on built-in function append:

append(object, /) method of builtins.list instance
    Append object to the end of the list.

>>> help(print)
Help on built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    ...

Docstrings

Let's see what happens if we define a function and call help() on that.

>>> def thing(stuff):
...     return stuff * 2
...
>>> help(thing)
Help on function thing in module __main__:

thing(stuff)
>>>

That sucked! We have no idea about what it does based on this. All we know is that it takes a stuff argument.

This is when documentation strings or docstrings come in. All we need to do is to add a string to the beginning of our function and it will show up in help(the_function). Like this:

>>> def thing(stuff):
...     "hello there"
...     return stuff * 2
...
>>> help(thing)
Help on function thing in module __main__:

thing(stuff)
    hello there

Note that docstrings are not comments. If you add a # comment to the beginning of the function it won't show up in help().

Multi-line strings

When we did help(print), we got more than one line of help. Maybe we could do that in our own docstring too?

>>> def thing():
...     "This thing does stuff.\n\nIt always returns None."
...
>>> help(thing)
Help on function thing in module __main__:

thing()
    This thing does stuff.

    It always returns None.
>>>

That's better, but how what if we want to do 5 lines of prints? Our "stuff\n\nstuff\nstuff" thing would be really long and hard to work with. But Python has multi-line strings too. They work like this:

>>> """bla bla bla
...
... bla bla
... bla bla bla"""
'bla bla bla\n\nbla bla\nbla bla bla'
>>>

So we can write documented functions like this:

>>> def thing():
...     """This thing does stuff.
...
...     It always returns None.
...     """
...
>>> help(thing)
Help on function thing in module __main__:

thing()
    This thing does stuff.

    It always returns None.

>>>

It's recommended to always use """strings like this""" for docstrings, even if the docstring is only one line long. This way it's easy to add more stuff to it later.

Documenting other stuff

Docstrings aren't actually limited to functions. You can use them for documenting classes and their methods too. For example, let's make a file like this and save it to test.py:

"""A test module.

It contains a class and a function.
"""


class Thing:
    """This is a test class."""

    def thingy(self):
        """This is a test method."""
        print("hello")


def do_hello():
    """This is a test function."""
    thing = Thing()
    thing.thingy()

Then we can import it and call help on it:

>>> import test
>>> help(test)
Help on module testie:

NAME
    testie - A test module.

DESCRIPTION
    It contains a class and a function.

CLASSES
    builtins.object
        Thing

    class Thing(builtins.object)
     |  This is a test class.
     |
     |  Methods defined here:
     |
     |  thingy(self)
     |      This is a test method.
     |
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |
     |  __dict__
     |      dictionary for instance variables (if defined)
     |
     |  __weakref__
     |      list of weak references to the object (if defined)

FUNCTIONS
    do_hello()
        This is a test function.

FILE
    /home/akuli/testie.py

That's pretty cool. We just added docstrings to our code and Python made this thing out of it.

You might be wondering what __weakref__ is. You don't need to care about it, and I think it would be better if help() would hide it.

Popular Docstring Formats

There are different styles for writing docstrings. If you are contributing to another Python project, make sure to use the same style as rest of that project is using.

If you are starting a new project, then you can use whichever style you want, but don't "reinvent the wheel"; use an existing style instead instead of making up your own. Here are some examples of popular docstring styles to choose from:

Sphinx Style

Sphinx is the Python documentation tool that the official Python documentation uses. By default, sphinx expects you to write docstrings like this:

class Vehicles:
    """
    The Vehicles object contains lots of vehicles.
    :param arg: The arg is used for ...
    :type arg: str
    :ivar arg: This is where we store arg
    :vartype arg: str
    """

    def __init__(self, arg):
        self.arg = arg

    def cars(self, distance, destination):
        """We can't travel a certain distance in vehicles without fuels, so here's the fuels

        :param distance: The amount of distance traveled
        :type amount: int
        :param bool destinationReached: Should the fuels be refilled to cover required distance?
        :raises: :class:`RuntimeError`: Out of fuel

        :returns: A Car mileage
        :rtype: Cars
        """  
        ...

Google Style

Google Style is meant to be easier to read and use without a tool like sphinx. Sphinx can be configured to use that with sphinx.ext.napoleon.

class Vehicles:
    """
    The Vehicles object contains lots of vehicles.

    Args:
        arg (str): The arg is used for...

    Attributes:
        arg (str): This is where we store arg.
    """

    def __init__(self, arg):
        self.arg = arg

    def cars(self, distance, destination):
        """We can't travel distance in vehicles without fuels, so here is the fuels

        Args:
            distance (int): The amount of distance traveled
            destination (bool): Should the fuels refilled to cover the distance?

        Raises:
            RuntimeError: Out of fuel

        Returns:
            cars: A car mileage
        """
        ...

Numpy Style

Numpy is a large and popular Python library, and numpy developers have their own docstring style.

class Vehicles:
    """
    The Vehicles object contains lots of vehicles.

    Parameters
    ----------
    arg : str
        The arg is used for ...
    *args
        The variable arguments are used for ...
    **kwargs
        The keyword arguments are used for ...

    Attributes
    ----------
    arg : str
        This is where we store arg.
    """

    def __init__(self, arg):
        self.arg = arg

    def cars(self, distance, destination):
        """We can't travel distance in vehicles without fuels, so here is the fuels

        Parameters
        ----------
        distance : int
            The amount of distance traveled
        destination : bool
            Should the fuels refilled to cover the distance?

        Raises
        ------
        RuntimeError
            Out of fuel

        Returns
        -------
        cars
            A car mileage
        """
        pass

When should we use docstrings?

I recommend using docstrings when writing code that other people will import. The help() function is awesome, so it's good to make sure it's actually helpful.

If your code is not meant to be imported, docstrings are usually a good idea anyway. Other people reading your code will understand what it's doing without having to read through all of the code.

Summary

• help() is awesome.
• A """triple-quoted string""" string in the beginning of a function, class or file is a docstring. It shows up in help().
• Docstrings are not comments.
• Usually it's a good idea to add docstrings everywhere.

---

If you have trouble with this tutorial, please tell me about it and I'll make this tutorial better, or ask for help online. If you like this tutorial, please give it a star.

You may use this tutorial freely at your own risk. See LICENSE.

Previous | Next | List of contents