Learning Python - Part 6

This is part of an ongoing series on learning the Python programming language. If you haven't read them yet, I advise you to catch up on parts one, two, three, four and five before reading this article.

This particular tutorial will be fairly short because we'll be dealing with a single topic, docstrings.

Docstrings, or documentation strings, are special free-standing strings within your code which are used to help other programmers understand how your program works. These strings cannot be put just anywhere, however, they need to be placed as the first part of a code block, whether it is a function, a class or a module.

Let's use one of our previous functions as an example:

def say_hello():
    """
    This function prints out a hello message.
    """
    print 'Hello World'

As you can see, we use a set of 3 double quotes to signify that this is a docstring. The docstring is placed first in the function, indented the same amount as the body of the function.

Docstrings are not just for reading when you're looking at the code, they can be retrieved later when your program is running by looking at the __doc__ property on your function. Everything in Python is an object, so even your function has properties and methods!

Type out the example function above, and add this line below it:

print say_hello.__doc__

You'll see that you just printed out your docstring, amazing!

While docstrings have no mandatory format or contents, generally it is expected that your docstring will contain a summary of what your code does, a blurb if the method is long enough, and descriptions of any parameters. It is becoming commonplace to write docstrings in a text markup system called reStructuredText.

reStructuredText is a text formatting system which takes plain text and adds a few pieces of markup for a reStructuredText parser to read an produce pretty documentation in a variety of formats like HTML and PDF. Let's take a look at a docstring in restructured:

def say_hello(greeting='Hello', name='world'):
    """
    This function greets a person.

    :param greeting: The greeting to say. Defaults to 'Hello'.
    :param name: The name of the person being greeted. Defaults to 'world'
    """
    print greeting, name

As you can see, this docstring documents the function and its parameters, and is quite easy to read. You'll also note that it has some structure to it, and those funny double back quotes.

In reStructuredText, an open line denotes a new paragraph, so that first line in the docstring becomes a paragraph by itself. The next set of lines is a definition list. This is a specially formatted list with a term and then its definition below it. The double backquotes indicates that it should be formatted with a monospaced font to look like code.

To format some text as bold, put ** on either side of the words you want in bold. You can use * in the same manner for italics.

This is **bold** and this is *italics*

Which renders like this:

This is bold and this is italics

Links are a little more complicated, as they need to contain both text and a URL. A link looks like this:

Go to the `Python <http://www.python.org/>`_ web site.

Which becomes:

Go to the Python web site.

Note the backquotes around both the text and the link's URL, and the trailing underscore. Any text in single backquotes in reStructuredText is treated as special, and so additional markup is placed next to the quotes in order to specify what the speciality is. In this particular case, the trailing underscore indicates that this is a link.

Using these backquotes you can also highlight classes, functions and modules. For example:

The :class:`Apple` class is found in the :mod:`fruit` module, and provides a type of fruit.

Here you can see we used :class: to show that the special text is the name of a class, and :mod: for a module. You can also use :func: for a function.

The reason you want to add this formatting is not just to make the docstrings pretty, but because you can use a tool like Sphinx to extract those docstrings and make HTML or PDFs from them. This makes it easier to get other folks up-to-speed on your program without having to dive through the code itself.

Was this article helpful?

Update: Part 7


Comments

comments powered by Disqus