Test-Driven Python Development

Chapter 7. Executable Documentation with doctest

Throughout this book, we have emphasized the need for code to be self-documenting as far as possible. We have mentioned how the cool docstring feature of Python helps us in this objective. There is one problem with documentation in general—it can easily go out of sync with the code. Many times we have seen changes to the code, but the corresponding change is not made to the documentation, leaving a new developer confused about how the code actually works. Enter the doctest module to our rescue.

The doctest module allows us to specify examples inside our docstrings. The module then extracts the examples, runs them, and verifies that they still work.

Our first doctest

The following is the current version ...