Doctests aren't confined to simple text files. You can put doctests into Python's docstrings.
Why would you want to do that? There are a couple of reasons. First of all, docstrings are an important part of the usability of Python code (but only if they tell the truth). If the behavior of a function, method, or module changes and the docstring doesn't get updated, then the docstring becomes misinformation, and a hindrance rather than a help. If the docstring contains a couple of doctest examples, then the out-of-date docstrings can be located automatically. Another reason for placing doctest examples into docstrings is simply that it can be very convenient. This practice keeps the tests, documentation and code all in the same place, where it can all be located easily.
If the docstring becomes home to too many tests, this can destroy its utility as documentation. This should be avoided; if you find yourself with so many tests in the docstrings that they aren't useful as a quick reference, move most of them to a separate file.
Time for action – embedding a doctest in a docstring
We'll embed a test right inside the Python source file that it tests, by placing it inside a docstring.
Create a file called test.py with the following contents:
def testable(x): r""" The `testable` function returns the square root of its parameter, or 3, whichever is larger. >>> testable(7) 3.0 >>> testable(16) 4.0 >>> testable(9) 3.0 >>> testable(10) == 10 ** 0.5 True """ if x < 9: return 3.0 return x ** 0.5
At the command prompt, change to the directory where you saved test.py and then run the tests by typing:
$ python -m doctest test.py
As mentioned earlier before, if you have an older version of Python, this isn't going to work for you. Instead, you need to type python -c "__import__('doctest').testmod(__import__('test'))"
If everything worked, you shouldn't see anything at all. If you want some confirmation that doctest is doing something, turn on verbose reporting by changing the command to:
python -m doctest -v test.py
For older versions of Python, instead use python -c "__import__('doctest').testmod(__import__('test'), verbose=True)"
What just happened
You put the doctest right inside the docstring of the function it was testing. This is a good place for tests that also show a user how to do something. It's not a good place for detailed, low-level tests (the above example, which was quite detailed for illustrative purposes, is skirting the edge of being too detailed), because docstrings need to serve as API documentation. You can see the reason for this just by looking back at the example, where the doctests take up most of the room in the docstring, without telling the readers any more than they would have learned from a single test.
Any test that will serve as good API documentation is a good candidate for including in the docstrings.
Notice the use of a raw string for the docstring (denoted by the r character before the first triple-quote). Using raw strings for your docstrings is a good habit to get into, because you usually don't want escape sequences—e.g. n for newline—to be interpreted by the Python interpreter. You want them to be treated as text, so that they are correctly passed on to doctest.
Doctest directives
Embedded doctests can accept exactly the same directives as doctests in text files can, using exactly the same syntax. Because of this, all of the doctest directives that we discussed before can also be used to aff ect the way embedded doctests are evaluated.
Execution scope
Doctests embedded in docstrings have a somewhat different execution scope than doctests in text files do. Instead of having a single scope for all of the tests in the file, doctest creates a single scope for each docstring. All of the tests that share a docstring, also share an execution scope, but they're isolated from tests in other docstrings.
The separation of each docstring into its own execution scope often means that we don't need to put much thought into isolating doctests, when they're embedded in docstrings. That is fortunate, since docstrings are primarily intended for documentation, and the tricks needed to isolate the tests might obscure the meaning.
Putting it in practice: an AVL tree
We'll walk step-by-step through the process of using doctest to create a testable specification for a data structure called an AVL Tree. An AVL tree is a way to organize key-value pairs, so that they can be quickly located by key. In other words, it's a lot like Python's built-in dictionary type. The name AVL references the initials of the people who invented this data structure.
As its name suggests, an AVL tree organizes the keys that are stored in it into a tree structure, with each key having up to two child keys—one child key that is less than the parent key by comparison, and one that is more. In the following picture, the key Elephant has two child keys, Goose has one, and Aardvark and Frog both have none.
The AVL tree is special, because it keeps one side of the tree from getting much taller than the other, which means that users can expect it to perform reliably and efficiently no matter what. In the previous image, an AVL tree would reorganize to stay balanced if Frog gained a child.
We'll write tests for an AVL tree implementation here, rather than writing the implementation itself. Therefore, we'll elaborate over the details of how an AVL tree works, in favor of looking at what it should do when it works right
If you want to know more about AVL Trees, you will find many good references on the Internet. Wikipedia's entry on the subject is a good place to start with:http://en.wikipedia.org/wiki/AVL_tree.
We'll start with a plain language specification, and then interject tests between the paragraphs.
You don't have to actually type all of this into a text file; it is here for you to read and to think about.
English specification
The first step is to describe what the desired result should be, in normal language. This might be something that you do for yourself, or something that somebody else does for you. If you're working for somebody, hopefully you and your employer can sit down together and work this part out.
In this case, there's not much to work out, because AVL Trees have been fully described for decades. Even so, the description here isn't quite like one you'd find anywhere else. This capacity for ambiguity is exactly the reason why a plain language specification isn't good enough. We need an unambiguous specification, and that's exactly what the tests in a doctest file can give us.
The following text goes in a file called AVL.txt, (which you can find in its final form in the accompanying code archive. At this stage of the process, the file contains only the normal language specification.):
An AVL Tree consists of a collection of nodes organized in a binarytree structure. Each node has left and right children, each of whichmay be either None or another tree node. Each node has a key, whichmust be comparable via the less-than operator. Each node has a value.Each node also has a height number, measuring how far the node is frombeing a leaf of the tree -- a node with height 0 is a leaf.The binary tree structure is maintained in ordered form, meaning thatof a node's two children, the left child has a key that comparesless than the node's key and the right child has a key that comparesgreater than the node's key.The binary tree structure is maintained in a balanced form, meaningthat for any given node, the heights of its children are either thesame or only differ by 1.The node constructor takes either a pair of parameters representinga key and a value, or a dict object representing the key-value pairswith which to initialize a new tree.The following methods target the node on which they are called, andcan be considered part of the internal mechanism of the tree:Each node has a recalculate_height method, which correctly sets theheight number.Each node has a make_deletable method, which exchanges the positionsof the node and one of its leaf descendants, such that the the treeordering of the nodes remains correct.Each node has rotate_clockwise and rotate_counterclockwise methods.Rotate_clockwise takes the node's right child and places it wherethe node was, making the node into the left child of its own formerchild. Other nodes in the vicinity are moved so as to maintainthe tree ordering. The opposite operation is performed by rotate_counterclockwise.Each node has a locate method, taking a key as a parameter, whichsearches the node and its descendants for a node with the specifiedkey, and either returns that node or raises a KeyError.The following methods target the whole tree rooted at the currentnode. The intent is that they will be called on the root node:Each node has a get method taking a key as a parameter, which locatesthe value associated with the specified key and returns it, or raisesKeyError if the key is not associated with any value in the tree.Each node has a set method taking a key and a value as parameters, andassociating the key and value within the tree.Each node has a remove method taking a key as a parameter, andremoving the key and its associated value from the tree. It raisesKeyError if no values was associated with that key.
Node data
The first three paragraphs of the specification describe the member variables of a AVL tree node, and tell us what the valid values for the variables are. They also tell us how tree height should be measured and define what a balanced tree means. It's our job now to take up those ideas, and encode them into tests that the computer can eventually use to check our code.
We could check these specifications by creating a node and then testing the values, but that would really just be a test of the constructor. It's important to test the constructor, but what we really want to do is to incorporate checks that the node variables are left in a valid state into our tests of each member function.
To that end, we'll define a function that our tests can call to check that the state of a node is valid. We'll define that function just after the third paragraph:
Notice that this test is written as if the AVL tree implementation already existed. It tries to import an avl_tree module containing an AVL class, and it tries to use the AVL class is specific ways. Of course, at the moment there is no avl_tree module, so the test will fail. That's as it should be. All that the failure means is that, when the ti me comes to implement the tree, we should do so in a module called avl_tree, with contents that function as our test assumes. Part of the benefit of testing like this is being able to test-drive your code before you even write it.
>>> from avl_tree import AVL>>> def valid_state(node):... if node is None:... return... if node.left is not None:... assert isinstance(node.left, AVL)... assert node.left.key < node.key... left_height = node.left.height + 1... else:... left_height = 0...... if node.right is not None:... assert isinstance(node.right, AVL)... assert node.right.key > node.key... right_height = node.right.height + 1... else:... right_height = 0...... assert abs(left_height - right_height) < 2... node.key < node.key... node.value>>> def valid_tree(node):... if node is None:... return... valid_state(node)... valid_tree(node.left)... valid_tree(node.right)
Notice that we didn't actually call those functions yet. They aren't tests, per se, but tools that we'll use to simplify writing tests. We define them here, rather than in the Python module that we're going to test, because they aren't conceptually part of the tested code, and because anyone who reads the tests will need to be able to see what the helper functions do.
Constructor
The fourth paragraph describes the constructor for an AVL node: The node constructor takes either a pair of parameters representing a key and a value, or a dict object representing the key-value pairs with which to initialize a new tree.
The constructor has two possible modes of operation:
it can either create a single initialized node
or it can create and initialize a whole tree of nodes. The test for the single node mode is easy:
>>> valid_state(AVL(2, 'Testing is fun'))
The other mode of the constructor is a problem, because it is almost certain that it will be implemented by creating an initial tree node and then calling its set method to add the rest of the nodes. Why is that a problem? Because we don't want to test the set method here: this test should be focused entirely on whether the constructor works correctly, when everything it depends on works.
In other words, the tests should be able to assume that everything outside of the specific chunk of code being tested works correctly.
However, that's not always a valid assumption. So, how can we write tests for things that call on code outside of what's being tested?
There is a solution for this problem. For now, we'll just leave the second mode of operation of the constructor untested.
Read more
United States
Great Britain
India
Germany
France
Canada
Russia
Spain
Brazil
Australia
Singapore
Canary Islands
Hungary
Ukraine
Luxembourg
Estonia
Lithuania
South Korea
Turkey
Switzerland
Colombia
Taiwan
Chile
Norway
Ecuador
Indonesia
New Zealand
Cyprus
Denmark
Finland
Poland
Malta
Czechia
Austria
Sweden
Italy
Egypt
Belgium
Portugal
Slovenia
Ireland
Romania
Greece
Argentina
Netherlands
Bulgaria
Latvia
South Africa
Malaysia
Japan
Slovakia
Philippines
Mexico
Thailand
