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) Helponbuilt-infunctionappend: append(object, /) methodofbuiltins.listinstanceAppendobjecttotheendofthelist. >>>help(print) Helponbuilt-infunctionprintinmodulebuiltins: print(...) print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False) Printsthevaluestoastream, ortosys.stdoutbydefault. Optionalkeywordarguments: ...

Docstrings

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

>>>defthing(stuff): ... returnstuff*2 ... >>>help(thing) Helponfunctionthinginmodule__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:

>>>defthing(stuff): ... "hello there" ... returnstuff*2 ... >>>help(thing) Helponfunctionthinginmodule__main__: thing(stuff) hellothere

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?

>>>defthing(): ... "This thing does stuff.\n\nIt always returns None." ... >>>help(thing) Helponfunctionthinginmodule__main__: thing() Thisthingdoesstuff. ItalwaysreturnsNone. >>>

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:

>>>defthing(): ... """This thing does stuff....... It always returns None.... """ ... >>>help(thing) Helponfunctionthinginmodule__main__: thing() Thisthingdoesstuff. ItalwaysreturnsNone. >>>

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."""classThing: """This is a test class."""defthingy(self): """This is a test method."""print("hello") defdo_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:

classVehicles: """ 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=argdefcars(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.

classVehicles: """ 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=argdefcars(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.

classVehicles: """ 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=argdefcars(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