Real Python: Python's doctest: Document and Test Your Code at Once

Are you interested in writing usage examples for your code that work as documentation and test cases simultaneously? If your answer is yes, then Python’s doctest module is for you. This module provides a testing framework that doesn’t have too steep a learning curve. It’ll allow you to use code examples for two purposes: documenting and testing your code.

Apart from allowing you to use your code’s documentation for testing the code itself, doctest will help you keep your code and its documentation in perfect sync at any moment.

In this tutorial, you’ll:

• Write doctest tests in your code’s documentation and docstrings
• Understand how doctest works internally
• Explore the limitations and security implications of doctest
• Use doctest for test-driven development
• Run your doctest tests using different strategies and tools

You won’t have to install any third-party libraries or learn complex APIs to follow this tutorial. You only need to know the basics of Python programming and how to use the Python REPL or interactive shell.

Documenting Your Code With Examples and Tests

Almost all experienced programmers will tell you that documenting your code is a best practice. Some will say that code and its documentation are equally important and necessary. Others will tell you that documentation is even more important than the code itself.

In Python, you’ll find many ways to document a project, app, or even modules and scripts. Larger projects generally require dedicated external documentation. But in small projects, using explicit names, comments, and docstrings might be sufficient:

 1"""This module implements functions to process iterables.""" 2 3deffind_value(value,iterable): 4"""Return True if value is in iterable, False otherwise.""" 5# Be explicit by using iteration instead of membership 6foriteminiterable: 7ifvalue==item:# Find the target value by equality 8returnTrue 9returnFalse

Explicit names like find_value() help you clearly express the content and aim of a given object. Such names improve your code’s readability and maintainability.

Comments, like the ones on lines 5 and 7, are pieces of text that you insert at different places in your code to clarify what the code does and why. Note that a Python comment starts with a # symbol and can occupy its own line or be part of an existing line.

Comments have a couple of drawbacks:

• They’re ignored by the interpreter or compiler, which makes them unreachable at runtime.
• They often get outdated when the code evolves and the comments remain untouched.

Documentation strings, or simply docstrings, are a neat Python feature that can help you document your code as you go. The advantage of docstrings compared to comments is that the interpreter doesn’t ignore them. They’re a living part of your code.

Because docstrings are active parts of your code, you can access them at runtime. To do this, you can use the .__doc__ special attributes on your packages, modules, classes, methods, and functions.

Tools like MkDocs and Sphinx can take advantage of docstrings for generating project documentation automatically.

You can add docstrings to your packages, modules, classes, methods, and functions in Python. If you want to learn how to write good docstrings, then PEP 257 proposes a series of conventions and recommendations that you can follow.

When you write docstrings, a common practice is to embed usage examples for your code. Those examples typically simulate REPL sessions.

Embedding code examples in your docstrings provides an effective way to document the code and a quick way to test the code as you write it. Yes, your code examples can work as test cases if you write them in a proper manner and use the right tool to run them.

Embedding REPL-like code examples in your code helps you:

• Keep the documentation in sync with the current state of your code
• Express your code’s intended usage
• Test your code as you write it

Those benefits sound neat! Now, how can you run the code examples that you’ve embedded in your documentation and docstrings? You can use Python’s doctest module from the standard library.

Getting to Know Python’s doctest Module

In this section, you’ll get to know Python’s doctest module. This module is part of the standard library, so you don’t have to install any third-party library to be able to use it in your day-to-day coding. Among other things, you’ll learn what doctest is and when to use this neat Python tool. To kick things off, you’ll start by diving into what doctest is.