Documentation and Testing

Question 1

**Basics. **

Classes, variables and functions

Answer 1

Classes and variables should be named as nouns. Classes get a capital letter and variables are lowercase with underscores

functions are lowercase verbs with underscores.

PEP-8 has more specifics

Question 2

Docstrings

Answer 2

placed at the beginning of a module, function or class. As long as it’s the first thing, Python will interpret it as a docstring

def find_words(text, word):

__”"”doc string can span multiple lines”””

accessible in code with the __doc__ attribute.

Docstrings should:

describe what the function does - preferably in one sentence

explain the arguments

explain the return value

include any expected exceptions

Question 3

Docutils

Answer 3

Certainly seems pretty handy and should probably be learned.

Restructured text looks cool.

Sphinx looks better.

Question 4

Doctests

Answer 4

places tests in the documentation string of any module, class, function, etc.

Pretty limited, I don’t think I’m interested in this just yet.

def times2(value):

__”””

__multiplies everything by 2. Be it a number, list

__or tuple

__>>> times2(5)

__10

__>>> times2(‘test’)

__‘testtest’

__>>> times2((‘a’, 1))

__(‘a’, 1, ‘a’, 1)

__”””

__ return value * 2

if __name__ == ‘__main__’:

__import doctest

__doctest.testmod()

Question 5

unittest module basics

Answer 5

1. First you setUp():

generally means esstablish values, make connections to dbs, open files, load data.

values that setUp defines cannot be returned, they must be attached to the object itself.

Tests are mthods on this object.

import unittest

class MultTestcase(unittest.TestCase):

__def setUp(self):

____self.factor = 2

Question 6

Writing tests for unittest

Answer 6

no single method that must implement all the tests.

the framework looks at your test case class for methods whose names start with test

for each of these methods, the framework executes setUp() before executing the test method.

utility methods describe how the code is supposed to work. These are inherited from unittest.TestCase. Each represents a condition that must be true in order to continue:

• assertTrue(expr, msg=None) - simplest assertion available.
• assertFalse(expr, msg=None)
• fail(msg=None) - generates failure explicitly. Better than raising an exception because it implies the code failed in a way the test understands.

Question 7

More unittest.TestCase methods

17 methods

Answer 7

• assertEqual(obj1, obj2, msg=None)
• assertNotEqual(obj1, obj2, msg=None)
• assertAlmostEqual(obj1, obj2, *, places=7, msg=None) - rounds values to given number of decimal places before checking for equality, helps with rounding errors and floating point arithmetic.
• assertNotAlmostEqual(obj1, obj2, *, places=7, msg=None) - fails when two numbers are equal within specified number of places
• assertSetEqual(set1, set2, msg=None)
• assertListEqual(list1, list2, msg=None)
• assertDictEqual(dict1, dict2, msg=None)
• assertTupleEqual(tup1, tup2, msg=None)
• assertSequenceEqual(seq1, seq2, msg=None)
• assertGreater(obj1, obj2, msg=None) - counterpart is less
• assertGreaterEqual(obj1, obj2, msg=None) - same counterpart
• assertMultiLineEqual(obj1, obj2, msg=None) - not (really clear
• assertRegexpMatches(text, regexp, msg=None)
• assertIn(obj, seq, msg=None)
• assertNotIn(obj, seq, msg=None)
• assertDictContainsSubset(dict1, dict2, msg=None)
• assertSameElements(seq1, seq2, msg=None) - tests all items in sequences and passes if they’re identical, order unimportant. Dict can be passed, but only looks at keys.

Question 8

Testing exceptions - verify unsuccessful outcomes.

Answer 8

• assertRaises(exception, callable, *args, **kwargs) - tests a callable to see that it raises a particular exception
• assertRaisesRegexp(exception, regex, callable, *args, **kwargs) - like above, but regex must match exceptions string value in order to pass. regex can be passed in as string or as regex object.

Question 9

Testing identity - checks if two objects are the same, not just equivalent values

Answer 9

Handy for when you cache some stuff. Can test if value returned from cache is the same value that was placed in it rather than an equivalent copy.

• assertIs(obj1, obj2, msg=None) - uses identity, not the value
• assertIsNot(obj1, obj2, msg=None) - uses identity, so different objects with equal/different values will pass.
• assertIsNone(obj, msg = None) -shortcut for common case of assertIs where object is compared to built-in None.
• assertIsNotNone(obj, msg=None) - inversion of the above.

Question 10

Tearing down a test case

Answer 10

tearDown() is conducted by a unittest.TestCase object when it’s tests have been run.

If writing to a DB or some other outside source is necessary for the tests, this allows you to undo all that.