But sometimes, this is useful: ::
x = x + 1 # Compensate for border
-Doc Strings
+Docstrings
-----------
PEP 257 is the primary reference for docstrings. (http://www.python.org/dev/peps/pep-0257/)
-------
The doctest module searches for pieces of text that look like interactive Python
-sessions, and then executes those sessions to verify that they work exactly as
+sessions in docstrings, and then executes those sessions to verify that they work exactly as
shown.
+Doctests have a different use case than proper unit tests: they are usually less
+detailed and don't catch special cases or obscure regression bugs. They are
+useful as an expressive documentation of the main use cases of a module and
+its components. However, doctests should run automatically each time
+the full test suite runs.
+
+A simple doctest in a function:
+
+::
+
+ def square(x):
+ """Squares x.
+
+ >>> square(2)
+ 4
+ >>> square(-2)
+ 4
+ """
+
+ return x * x
+
+ if __name__ == '__main__':
+ import doctest
+ doctest.testmod()
+
+When running this module from the command line as in ``python module.py``, the doctests
+will run and complain if anything is not behaving as described in the docstrings.
Tools
:::::