A python docstring allows you to document your code more formally. We’ll first look at what a docstring is exactly. Next, we’ll create our own docstrings. Finally, I’ll show you how to read docstrings.
Table of contents
What is a Python docstring?
Let’s start by defining what a docstring is. This is taken straight from PEP-0257, which introduces docstrings:
- A docstring is a string that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the
__doc__special attribute of that object.
There’s a clear distinction between Python comments and docstrings. A comment is ignored completely by the Python interpreter, while a docstring is an actual string that the interpreter sees. Because we don’t assign the string, it’s considered useless by the interpreter while running the code and is effectively ignored. So the effect of a docstring, in short, is the same: it’s a piece of text that documents your code.
However, there’s still an essential difference between comments and docstrings, because Python can actually find and show the docstring when asked for, since it gets assigned to the
__doc__ special attribute. It can be used as a way to formally document your code, as you’ll soon learn.
How to create Python docstrings
As defined above, we can simply insert a string as the first statement of any module, function, class, or method and it becomes the docstring. Here’s an example of how to document a Python class and its functions using docstrings:
class MyDocumentedClass: """This class is well documented but doesn't do anything special.""" def do_nothing(self): """This method doesn't do anything but feel free to call it anyway.""" pass
As you can see, I created these strings with triple quotes. It’s for a reason: they are more recognizable as a docstring, and it’s easier to expand them to multi-line strings later on (if needed).
How to read docstrings
The docstring is internally assigned to the
__doc__ special attribute. Usually, you don’t access it that way, though. Instead, we call
help(MyDocumentedClass) in a Python REPL to see the result of these docstrings:
Help on class MyDocumentedClass in module __main__: class MyDocumentedClass(builtins.object) | This class is well documented but doesn't do anything special | | Methods defined here: | | do_nothing(self) | This method doesn't do anything but feel free to call it anyway
Here’s an interactive example of the same class to experiment with this yourself:
You can use help on any object in Python. I encourage you to try this. E.g., enter
help(print) to get the docstring from the print function, or
help(str) to view the string class with all its useful methods. You can also ask for the documentation of methods within a class, e.g. with
help(str.title) you can learn what the
title() method on a string object does.
- Docstrings were proposed and described in detail in PEP-0257
- Python comments are used to further document and explain your code