`assert` keyword can be disabled by interpreter, so it's not reliable
for functional code.

doc/examples/example_test.py

@@ -1,10 +1,10 @@
 #!/usr/bin/python
 
-import httplib
+import http.client
 import operator
 import subprocess
 import unittest
-import urlparse
+import urllib.parse
 
 from sznqalibs import hoover
 
@@ -46,8 +46,8 @@ class CgiCalcDriver(BaseCalcDriver):
 
     def _get_data(self):
         pq = "op=%(op)s&a=%(a)s&b=%(b)s" % self._args
-        parsed_url = urlparse.urlparse(self._settings['uri'])
-        conn = httplib.HTTPConnection(parsed_url.hostname)
+        parsed_url = urllib.parse.urlparse(self._settings['uri'])
+        conn = http.client.HTTPConnection(parsed_url.hostname)
         conn.request("GET", "%s?%s" % (parsed_url.path, pq))
         resp = conn.getresponse()
         assert resp.status == 200
@@ -92,7 +92,8 @@ class TestCase(unittest.TestCase):
             (operator.eq, PyCalcDriver, CliCalcDriver),
         ]
         tracker = hoover.regression_test(argsrc, tests, self.driver_settings)
-        print hoover.jsDump(tracker.getstats())
+        stats_text = hoover.jsDump(tracker.getstats())
+        print(stats_text)
         if tracker.errors_found():
             self.fail(tracker.format_report())
 

sznqalibs/bottleneck.py

@@ -1,8 +1,10 @@
 import time
 
 
-class FrameState(object):
-    """Abstraction and tracking of frame state"""
+class FrameState:
+    """
+    Abstraction and tracking of frame state
+    """
 
     def __init__(self, max_load, size, debug):
         self.start = 0
@@ -36,10 +38,11 @@ class FrameState(object):
 
     def debug(self):
         if self.DEBUG_MODE:
-            print("%4d; %4d; %5s; %0.3f; %0.3f; %5s; %5s"
-                  % (self.load, self.MAX_LOAD, self.load_ok,
-                     self.pos, self.SIZE, self.time_ok,
-                     self.allows))
+            msg = ("%4d; %4d; %5s; %0.3f; %0.3f; %5s; %5s"
+                   % (self.load, self.MAX_LOAD, self.load_ok,
+                      self.pos, self.SIZE, self.time_ok,
+                      self.allows))
+            print(msg)
 
     def is_closed(self):
         return not self.is_open()
@@ -51,8 +54,9 @@ class FrameState(object):
         return self.allows
 
 
-class Throttle(object):
-    """Throttle to allow only certain amount of iteration per given time.
+class Throttle:
+    """
+    Throttle to allow only certain amount of iteration per given time.
 
     Usage:
 
@@ -74,11 +78,11 @@ class Throttle(object):
     of calls in time.  If your loop takes 1ms and you throttle to 1000 loops
     per 10 minutes, all loops will happen in the first second, and the last
     call will block for 599 seconds.
-
     """
 
     def __init__(self, max_load, frame_size=60, debug=False):
-        """Create new Throttle.
+        """
+        Create new Throttle.
 
         Only required parameter is `max_load`, which is number of times per
         frame `Throttle.wait()` returns without blocking.  Optionally you can
@@ -94,15 +98,21 @@ class Throttle(object):
                                 debug=self.debug)
 
     def is_closed(self):
-        """True if throttle is closed."""
+        """
+        True if throttle is closed.
+        """
         return self.frame.is_closed()
 
     def is_open(self):
-        """True if throttle is open."""
+        """
+        True if throttle is open.
+        """
         return self.frame.is_open()
 
     def wait(self):
-        """Return now if throttle is open, otherwise block until it is."""
+        """
+        Return now if throttle is open, otherwise block until it is.
+        """
         self.frame.debug()
         self.waiting = self.is_closed()
         while self.waiting:

sznqalibs/hoover.py

@@ -1,6 +1,7 @@
 # coding=utf-8
 
 import collections
+import functools
 import csv
 import difflib
 import hashlib
@@ -16,7 +17,7 @@ from copy import deepcopy
 # ## The Motor                                                             ## #
 # ########################################################################### #
 
-def regression_test(argsrc, tests, driver_settings, cleanup_hack=None,
+def regression_test(argsrc, tests, driver_settings=None, cleanup_hack=None,
                     apply_hacks=None, on_next=None):
     """Perform regression test with argsets from `argsrc`.
 
@@ -54,12 +55,15 @@ def regression_test(argsrc, tests, driver_settings, cleanup_hack=None,
 
     on_next = on_next if on_next else lambda a, b: None
     apply_hacks = apply_hacks if apply_hacks else []
+    driver_settings = driver_settings if driver_settings else {}
 
     tracker = Tracker()
     last_argset = None
 
-    all_classes = set(reduce(lambda a, b: a+b,
-                             [triple[1:] for triple in tests]))
+    all_classes = set(functools.reduce(
+        lambda a, b: a+b,
+        [triple[1:] for triple in tests]
+    ))
 
     counter = StatCounter()
 
@@ -119,7 +123,9 @@ def regression_test(argsrc, tests, driver_settings, cleanup_hack=None,
                 diff = jsDiff(dira=case['oracle'],
                               dirb=case['result'],
                               namea=case['oname'],
-                              nameb=case['rname'])
+                              nameb=case['rname'],
+                              chara='o',
+                              charb='r')
 
             tracker.update(diff, argset)
 
@@ -134,19 +140,23 @@ def regression_test(argsrc, tests, driver_settings, cleanup_hack=None,
     return tracker
 
 
-def get_data_and_stats(driverClass, argset, driver_settings):
-    """Run test with given driver"""
+def get_data_and_stats(driverClass, argset, driver_settings, only_own=False):
+    """
+    Run single test, return data and stats.
+    """
     start = time.time()
     d = driverClass()
-    d.setup(driver_settings, only_own=True)
+    d.setup(driver_settings, only_own=only_own)
     d.run(argset)
     return (d.data, d.duration, time.time() - d.duration - start)
 
 
-def get_data(driverClass, argset, driver_settings):
-    """Run test with given driver"""
+def get_data(driverClass, argset, driver_settings, only_own=False):
+    """
+    Run single test, return data only.
+    """
     d = driverClass()
-    d.setup(driver_settings, only_own=True)
+    d.setup(driver_settings, only_own=only_own)
     d.run(argset)
     return d.data
 
@@ -155,7 +165,7 @@ def get_data(driverClass, argset, driver_settings):
 # ## The Pattern                                                           ## #
 # ########################################################################### #
 
-class _BaseRuleOp(object):
+class _BaseRuleOp:
 
     def __init__(self, items, item_ok):
         self._items = items
@@ -167,14 +177,14 @@ class _BaseRuleOp(object):
         except ValueError:                      # no, it's something else...
             return self._item_ok(item)
 
-    def __nonzero__(self):
+    def __bool__(self):
         try:
             return self._match()
         except TypeError:
             raise ValueError("items must be an iterable: %r" % self._items)
 
 
-class RuleOp(object):
+class RuleOp:
 
     class ALL(_BaseRuleOp):
 
@@ -188,15 +198,25 @@ class RuleOp(object):
 
     @staticmethod
     def Match(pattern, item_ok):
-        """Evaluate set of logically structured patterns using passed function.
+        """
+        Evaluate set of logically structured patterns using passed function.
+
+        *pattern* must be a tuple in form of `(op, items)` where *op* can be
+        either `RuleOp.ALL` or `RuleOp.ANY` and *items* is a list of items
+        to check using *item_ok* function.
 
-        pattern has form of `(op, [item1, item2, ...])` where op can be any of
-        pre-defined logical operators (`ALL`/`ANY`, I doubt you will ever need
-        more) and item_ok is a function that will be used to evaluate each one
-        in the list.  In case an itemN is actually pattern as well, it will be
-        recursed into, passing the item_ok on and on.
+        *item_ok* is a function that accepts single argument and its return
+        value is evaluated for true-ness.
 
-        Note that there is no data to evaluate "against",  you can use closure
+        Final result is True or False and is computed by combining results
+        of individual *item_ok* calls: either all must be true (when `op
+        == RuleOp.ALL`) or at least one must be true (when `op == RuleOp.ANY`).
+
+        The evaluation is done recursively, that is, if an item in the pattern
+        is also a pattern itself, it will be evaluated by calling RuleOp.Match
+        and passing the same *item_ok* function.
+
+        Note that there is no data to evaluate "against", you can use closure
         if you need to do that.
         """
 
@@ -204,11 +224,9 @@ class RuleOp(object):
             op, items = pattern
         except TypeError:
             raise ValueError("pattern is not a tuple: %r" % pattern)
-        try:
-            assert issubclass(op, _BaseRuleOp)
-        except TypeError:
+        if type(op) is not type:
             raise ValueError("invalid operator: %r" % op)
-        except AssertionError:
+        if not issubclass(op, _BaseRuleOp):
             raise ValueError("invalid operator class: %s" % op.__name__)
         return bool(op(items, item_ok))
 
@@ -217,11 +235,11 @@ class RuleOp(object):
 # ## The Path                                                              ## #
 # ########################################################################### #
 
-class DictPath(object):
+class DictPath:
     """Mixin that adds "path-like" behavior to the top dict of dicts.
 
-    Use this class as a mixin for a deep dic-like structure and you can access
-    the elements using a path.  For example:
+    Use this class as a mixin for a deep dictionary-like structure in order to
+    access the elements using a Unix-like path.  For example:
 
         MyData(dict, DictPath):
             pass
@@ -244,7 +262,7 @@ class DictPath(object):
 
     DIV = "/"
 
-    class Path(object):
+    class Path:
 
         def __init__(self, path, div):
             self.DIV = div
@@ -252,9 +270,11 @@ class DictPath(object):
 
         def _validate(self):
             try:
-                assert self._path.startswith(self.DIV)
-            except (AttributeError, AssertionError):
-                raise ValueError("invalid path: %r" % self._path)
+                has_root = self._path.startswith(self.DIV)
+            except AttributeError:
+                raise ValueError("invalid path: not a string: %r" % self._path)
+            if not has_root:
+                raise ValueError("invalid path: missing root: %r" % self._path)
 
         def stripped(self):
             return self._path.lstrip(self.DIV)
@@ -329,12 +349,13 @@ class DictPath(object):
 # ########################################################################### #
 
 class TinyCase(dict, DictPath):
-    """Abstraction of the smallest unit of testing.
+    """Test case for hoover.
 
-    This class is intended to hold relevant data after the actual test
-    and apply transformations (hacks) as defined by rules.
+    This class is used as an intermediary container for test parameters,
+    oracles and test results.  This is to allow post-test transformations
+    ("hacks") to happen before the result is evaluated for pass/fail.
 
-    The data form (self) is:
+    Instantiate TinyCase with data (self) in following format:
 
         {
             'argset': {},   # argset as fed into `BaseTestDriver.run`
@@ -344,40 +365,19 @@ class TinyCase(dict, DictPath):
             'rname': ""     # name of result driver's class
         }
 
-    The transformation is done using the `TinyCase.hack()` method to which
-    a list of rules is passed.  Each rule is applied, and rules are expected
-    to be in a following form:
+    Then call TinyCase.hack() with a set of rules which can alter oracles,
+    results or both based on the data stored in TinyCase.
 
-        {
-            'drivers': [{}],        # list of structures to match against self
-            'argsets': [{}],        # -ditto-
-            'action_name': <Arg>    # an action name with argument
-        }
+    Typical use cases for 'hacks' are:
 
-    For each of patterns ('drivers', argsets') present, match against self
-    is done using function `hoover.dataMatch`, which is basically a recursive
-    test if the pattern is a subset of the case.  If none of results is
-    negative (i.e. both patterns missing results in match), any known actions
-    included in the rule are called.  Along with action name a list or a dict
-    providing necessary parameters is expected: this is simply passed as only
-    parameter to corresponding method.
-
-    Actions use specific way how to address elements in the structures
-    saved in the oracle and result keys provided by `DictPath`, which makes
-    it easy to define rules for arbitrarily complex dictionary structures.
-    The format resembles to Unix path, where "directories" are dict
-    keys and "root" is the `self` of the `TinyCase` instance:
-
-        /oracle/temperature
-        /result/stats/word_count
-
-    Refer to each action's docstring for descriprion of their function
-    as well as expected format of argument.  The name of action as used
-    in the reule is the name of method without leading 'a_'.
-
-    Warning: All actions will silently ignore any paths that are invalid
-             or leading to non-existent data!
-             (This does not apply to a path leading to `None`.)
+     *  avoid known and tracked bugs,
+     *  help normalize results (remove irrelevant details),
+     *  solve certain limitations in oracle machines.
+
+    Note that while for most tests, you should strive for zero hacks,
+    sometimes they are inevitable.  In such cases, number of hacks can
+    be a useful quality metric.   For that reason, 'hoover.regression_test'
+    will count the applied hacks and return it in the test report.
     """
 
     def a_exchange(self, action):
@@ -387,7 +387,7 @@ class TinyCase(dict, DictPath):
         value is a list of paths.  For each key, it goes through the
         paths and if the value equals `a` it is set to `b`.
         """
-        for (oldv, newv), paths in action.iteritems():
+        for (oldv, newv), paths in action.items():
             for path in paths:
                 try:
                     curv = self.getpath(path)
@@ -408,7 +408,7 @@ class TinyCase(dict, DictPath):
         before comparison, since direct comparison of floats is unreliable
         on some architectures.
         """
-        for fmt, paths in action.iteritems():
+        for fmt, paths in action.items():
             for path in paths:
                 if self.ispath(path):
                     new = fmt % self.getpath(path)
@@ -457,7 +457,7 @@ class TinyCase(dict, DictPath):
         Expects dict with precision (ndigits, after the dot) as a key and
         list of paths as value.
         """
-        for ndigits, paths in action.iteritems():
+        for ndigits, paths in action.items():
             for path in paths:
                 try:
                     f = self.getpath(path)
@@ -473,7 +473,57 @@ class TinyCase(dict, DictPath):
                      'round': a_round}
 
     def hack(self, ruleset):
-        """Apply action from each rule, if patterns match."""
+        """
+        Run any matching actions in the *ruleset*.
+
+        Each rule must be in in a following form:
+
+            {
+                'drivers': [{}],        # list of structures to match
+                                        # against self
+                'argsets': [{}],        # -ditto-
+                <action_name>: <Arg>    # an action name with argument
+                <action_name>: <Arg>    # another action...
+            }
+
+        Each of the rules is first evaluated for match (does it apply to this
+        TinyCase?), and if the rule applies, transformation is done.  The
+        transformation is defined by `<action_name>: <Arg>` pairs and it can
+        alter 'oracle', 'result' or both.
+
+        The match evaluation is done using `hoover.dataMatch()` -- this is
+        basically a recursive pattern match against 'drivers' and 'argsets'.
+        Both 'drivers' and 'argsets' are optional, but when specified, all
+        items must must match in order for the rule to apply.  (If 'drivers'
+        and 'argsets' are both missing or empty, rule will apply to each and
+        all test cases.)
+
+        If rule does not match, `TinyCase.hack()` moves on to next one.
+
+        If a rule does match, `TinyCase.hack()` will look for actions defined
+        in it.  Action consists of action name (key of the rule dictionary,
+        <action_name>) and an argument (<Arg>).
+
+        Action name must be one of: 'remove', 'even_up', 'format_str',
+        'exchange' or 'round'.  Each action corresponds to a TinyCase method
+        prefixed by 'a_'; for example 'even_up' action corresponds to
+        TinyCase.a_even_up method.  Each action expects different argument
+        so see the corresponding method docstrings.
+
+        Because 'oracle' and 'result' can be relatively complex structures,
+        actions accept Unix-like paths to specify elements inside them.
+        The "root" of the path is the TinyCase instance, and "directories"
+        are keys under it.  For example, following would be valid paths
+        if test drivers work with dictionaries such as `{'temperature': 50,
+        'stats': {'word_count': 15}}`:
+
+            /oracle/temperature
+            /result/stats/word_count
+
+        Warning: All actions will silently ignore any paths that are invalid
+                 or leading to non-existent data!
+                 (This does not apply to a path leading to `None`.)
+        """
 
         def driver_matches(rule):
             if 'drivers' not in rule:
@@ -548,36 +598,65 @@ class DriverDataError(Exception):
         return result
 
 
-class BaseTestDriver(object):
+class BaseTestDriver:
     """Base class for test drivers used by `hoover.regression_test` and others.
 
-    This class is used to create a test driver, which is an abstraction
-    and encapsulation of the system being tested.  Or, the driver in fact
-    can be just a "mock" driver that provides data for comparison with
-    a "real" driver.
-
-    The minimum you need to create a working driver is to implement a working
-    `self._get_data` method that sets `self.data`.  Any exception from this
-    method will be re-raised as DriverError with additional information.
-
-    Also, you can set self.duration (in fractional seconds, as returned by
-    standard time module) in the _get_data method, but if you don't, it is
-    measured for you as time the method call took.  This is useful if you
-    need to fetch the data from some other driver or a gateway, and you
-    have better mechanism to determine how long the action would take "in
-    real life".
-
-    For example, if we are testing a Java library using a Py4J gateway,
-    we need to do some more conversions outside our testing code just to
-    be able to use the data in our Python test.  We don't want to include
-    this in the "duration", since we are measuring the Java library, not the
-    Py4J GW (or our ability to perform the conversions optimally).  So we
-    do our measurement within the Java machine and pass the result to the
-    Python driver.
+    This class tepresents test driver and can be used to:
+
+     *  Wrap system under test (SUT).
+
+        Provide simple interface to set up, sandbox and activate the system
+        and collect any relevant results.  This can be merely return value
+        (purely functional test) but also other characteristics such as
+        time to complete.
+
+     *  Mimic ("mock") the system under test.
+
+        Also called as oracle machine, this can be used to predict expected
+        behavior of SUT under given parameters.
+
+     *  Wrap an alternative implementation of SUT.
+
+        As a special case of the previous role, sometimes it's desirable to
+        use an alternative implementation of SUT as oracle machine.  This
+        can be a legacy implementation, reference implementation or other
+        platform implementation.
+
+    In either case, the driver makes sure that any input arguments are
+    interpreted (and passed on) correctly and any results are returned in
+    a consistent way.
+
+    To use this class, sub-class it and implement `_get_data()` method.
+    Tge `_get_data()` method must:
+
+     *  Accept single argument; this contains arguments to the SUT.
+
+        If using `hoover.regression_test()`, this value will be retrieved
+        from the *argsrc* iterator.
+
+     *  Implement the test case defined by the argument set.
+
+        The implementation can either be a wrapper to real SUT, alternative
+        one, or can be an oracle machine -- i.e. it can figure out the result
+        on its own.  Note that this can be much easier as it sounds, given
+        that you can "cheat" by crafting the set of test cases so that the
+        prediction is easy (but still effective at hitting bugs), or you
+        can "hide the answer" in the *args* itself, and define set of
+        test cases statically in form of "question, answer" pairs.
+
+     *  Collect any relevant data and set it to `data` property.
+
+        Optionally, you can also set `duration` property (in fractional
+        seconds, as returned by standard time module).  If you don't
+        it will be automatically measured.
+
+    Any exception from the *_get_data* method will be re-raised as
+    DriverError.
 
     Optionally, you can:
 
-    *   Make an __init__ and after calling base __init__, set
+    *   Implement *__init__* method calling base __init__ and setting more
+        properties:
 
         *   `self._mandatory_args`, a list of keys that need to be present
             in `args` argument to `run()`
@@ -585,7 +664,7 @@ class BaseTestDriver(object):
         *   and `self._mandatory_settings`, a list of keys that need to be
             present in the `settings` argument to `__init__`
 
-    *   implement methods
+    *   Implement methods
 
         *   `_decode_data` and `_normalize_data`, which are intended to decode
              the data from any raw format it is received, and to prepare it
@@ -651,7 +730,7 @@ class BaseTestDriver(object):
 
     def __cleanup_data(self):
         """remove hidden data; e.g. what was only there for _check_data"""
-        for key in self.data.keys():
+        for key in self.data:
             if key.startswith("_"):
                 del self.data[key]
 
@@ -677,17 +756,27 @@ class BaseTestDriver(object):
 
     @classmethod
     def check_values(cls, args=None):
-        """check args in advance before running or setting up anything"""
+        """
+        Check args in advance before running or setting up anything.
+        """
         for fn in cls.bailouts:
             if fn(args):
                 raise NotImplementedError(inspect.getsource(fn))
 
     def setup(self, settings, only_own=False):
-        """Load settings. only_own means that only settings that belong to us
-        are loaded ("DriverClass.settingName", the first discriminating part
-        is removed)"""
+        """
+        Load settings.
+
+        If *only_own* is false, *settings* are merely assigned to
+        settings attribute.
+
+        if *only_own* is true, settings are filtered:  Any keys that don't
+        begin with the prefix of driver class name and period are ignored.
+        Settings that do start with this prefix are assigned to settings
+        attribute with the prefix removed.
+        """
         if only_own:
-            for ckey in settings.keys():
+            for ckey in settings:
                 driver_class_name, setting_name = ckey.split(".", 2)
                 if self.__class__.__name__ == driver_class_name:
                     self._settings[setting_name] = settings[ckey]
@@ -696,7 +785,9 @@ class BaseTestDriver(object):
         self._setup_ok = True
 
     def run(self, args):
-        """validate, run and store data"""
+        """
+        Validate args, run SUT and store data.
+        """
 
         self._args = args
         assert self._setup_ok, "run() before setup()?"
@@ -705,7 +796,7 @@ class BaseTestDriver(object):
         start = time.time()
         try:
             self._get_data()        # run the test, i.e. obtain raw data
-        except StandardError as e:
+        except Exception as e:
             raise DriverError(e, self)
         self.duration = (time.time() - start if self.duration is None
                          else self.duration)
@@ -713,7 +804,7 @@ class BaseTestDriver(object):
             self._decode_data()     # decode raw data
             self._normalize_data()  # normalize decoded data
             self._check_data()      # perform arbitrarty checking
-        except StandardError, e:
+        except Exception as e:
             raise DriverDataError(e, self)
         self.__cleanup_data()   # cleanup (remove data['_*'])
 
@@ -729,8 +820,10 @@ class MockDriverTrue(BaseTestDriver):
 # ## Helpers                                                               ## #
 # ########################################################################### #
 
-class StatCounter(object):
-    """A simple counter with formulas support."""
+class StatCounter:
+    """
+    A simple counter with support for custom formulas.
+    """
 
     def __init__(self):
         self.generic_stats = {}
@@ -791,8 +884,8 @@ class StatCounter(object):
         )
 
     def _computed_stats(self):
-        computed = dict.fromkeys(self.formulas.keys())
-        for fname, fml in self.formulas.iteritems():
+        computed = dict.fromkeys(self.formulas)
+        for fname, fml in self.formulas.items():
             try:
                 v = fml(self.generic_stats, self.driver_stats)
             except ZeroDivisionError:
@@ -801,18 +894,24 @@ class StatCounter(object):
         return computed
 
     def add_formula(self, vname, formula):
-        """Add a function to work with generic_stats, driver_stats."""
+        """
+        Add a function to work with generic_stats, driver_stats.
+        """
         self.formulas[vname] = formula
 
     def add(self, vname, value):
-        """Add a value to generic stat counter."""
+        """
+        Add a value to generic stat counter.
+        """
         if vname in self.generic_stats:
             self.generic_stats[vname] += value
         else:
             self.generic_stats[vname] = value
 
     def add_for(self, dclass, vname, value):
-        """Add a value to driver stat counter."""
+        """
+        Add a value to driver stat counter.
+        """
         dname = dclass.__name__
         if dname not in self.driver_stats:
             self._register(dname)
@@ -822,25 +921,32 @@ class StatCounter(object):
             self.driver_stats[dname][vname] = value
 
     def count(self, vname):
-        """Alias to add(vname, 1)"""
+        """
+        Alias to add(vname, 1)
+        """
         self.add(vname, 1)
 
     def count_for(self, dclass, vname):
-        """Alias to add_for(vname, 1)"""
+        """
+        Alias to add_for(vname, 1)
+        """
         self.add_for(dclass, vname, 1)
 
     def all_stats(self):
-        """Compute stats from formulas and add them to colledted data."""
+        """
+        Compute stats from formulas and add them to colledted data.
+        """
         stats = self.generic_stats
-        for dname, dstats in self.driver_stats.iteritems():
-            for key, value in dstats.iteritems():
+        for dname, dstats in self.driver_stats.items():
+            for key, value in dstats.items():
                 stats[dname + "_" + key] = value
         stats.update(self._computed_stats())
         return stats
 
 
 class Tracker(dict):
-    """Error tracker to allow for usable reports from huge regression tests.
+    """
+    Error tracker to allow for usable reports from huge regression tests.
 
     Best used as a result bearer from `regression_test`, this class keeps
     a simple in-memory "database" of errors seen during the regression
@@ -855,13 +961,14 @@ class Tracker(dict):
             a dict) that caused the error.
 
             If boolean value of the result is False, the object is thrown away
-            and nothing happen.  Otherwise, its string value is used as a key
+            and nothing happens.  Otherwise, its string value is used as a key
             under which the argument set is saved.
 
-            As you can see, the string is supposed to be ''as deterministic
-            as possible'', i.e. it should provide as little information
-            about the error as is necessary.  Do not include any timestamps
-            or "volatile" values.
+            The string interpretation of the result is supposed to be
+            "as deterministic as possible", i.e. it should provide only
+            necessary information about the error:  do not include any
+            timestamps or "volatile" values such as PID's, version numbers
+            or tempfile names.
 
          3. At final stage, you can retrieve statistics as how many (distinct)
             errors have been recorded, what was the duration of the whole test,
@@ -891,21 +998,29 @@ class Tracker(dict):
         self.driver_stats = {}
 
     def _csv_fname(self, errstr, prefix):
-        """Format name of file for this error string"""
+        """
+        Format name of file for this error string
+        """
         return '%s/%s.csv' % (prefix, self._eid(errstr))
 
     def _eid(self, errstr):
-        """Return EID for the error string (first 7 chars of SHA1)."""
+        """
+        Return EID for the error string (first 7 chars of SHA1).
+        """
         return hashlib.sha1(errstr).hexdigest()[:7]
 
     def _insert(self, errstr, argset):
-        """Insert the argset into DB."""
+        """
+        Insert the argset into DB.
+        """
         if errstr not in self._db:
             self._db[errstr] = []
         self._db[errstr].append(argset)
 
     def _format_error(self, errstr, max_aa=0):
-        """Format single error for output."""
+        """
+        Format single error for output.
+        """
         argsets_affected = self._db[errstr]
         num_aa = len(argsets_affected)
 
@@ -928,11 +1043,15 @@ class Tracker(dict):
     #
 
     def errors_found(self):
-        """Return number of non-distinct errors in db."""
+        """
+        Return number of non-distinct errors in db.
+        """
         return bool(self._db)
 
     def format_report(self, max_aa=0):
-        """Return complete report formatted as string."""
+        """
+        Return complete report formatted as string.
+        """
         error_list = "\n".join([self._format_error(e, max_aa=max_aa)
                                 for e in self._db])
         return ("Found %(total_errors)s (%(distinct_errors)s distinct) errors"
@@ -942,20 +1061,28 @@ class Tracker(dict):
                 + "\n\n" + error_list)
 
     def getstats(self):
-        """Return basic and driver stats
+        """
+        Return basic and driver stats
 
-            argsets_done - this should must be raised by outer code,
-                           once per each unique argset
-            tests_done   - how many times Tracker.update() was called
-            distinct_errors - how many distinct errors (same `str(error)`)
+        Returns dictionary with following values:
+
+            'tests_done' - how many times Tracker.update() was called
+
+            'distinct_errors' - how many distinct errors (same `str(error)`)
                            were seen by Tracker.update()
-            total_errors - how many times `Tracker.update()` saw an
+
+            'total_errors' - how many times `Tracker.update()` saw an
                            error, i.e. how many argsets are in DB
-            time         - how long since init (seconds)
+
+            'time'       - how long since init (seconds)
         """
 
         def total_errors():
-            return reduce(lambda x, y: x + len(y), self._db.values(), 0)
+            return functools.reduce(
+                lambda x, y: x + len(y),
+                self._db.values(),
+                initial=0,
+            )
 
         stats = {
             "argsets": self.argsets_done,
@@ -968,7 +1095,8 @@ class Tracker(dict):
         return stats
 
     def update(self, error, argset):
-        """Update tracker with test result.
+        """
+        Update tracker with test result.
 
         If `bool(error)` is true, it is considered error and argset
         is inserted to DB with `str(error)` as key.  This allows for later
@@ -980,7 +1108,9 @@ class Tracker(dict):
             self._insert(errstr, argset)
 
     def write_stats_csv(self, fname):
-        """Write stats to a simple one row (plus header) CSV."""
+        """
+        Write stats to a simple one row (plus header) CSV.
+        """
         stats = self.getstats()
         colnames = sorted(stats.keys())
         with open(fname, 'a') as fh:
@@ -989,18 +1119,20 @@ class Tracker(dict):
             cw.writerow(stats)
 
     def write_args_csv(self, prefix=''):
-        """Write out a set of CSV files, one per distinctive error.
+        """
+        Write out a set of CSV files, one per distinctive error.
 
         Each CSV is named with error EID (first 7 chars of SHA1) and lists
         all argument sets affected by this error.  This is supposed to make
         easier to further analyse impact and trigerring values of errors,
-        perhaps using a table processor software."""
+        perhaps using a table processor software.
+        """
 
         def get_all_colnames():
             cn = {}
-            for affected in self._db.itervalues():
+            for affected in self._db.values():
                 for argset in affected:
-                    cn.update(dict.fromkeys(argset.keys()))
+                    cn.update(dict.fromkeys(argset))
                 return sorted(cn.keys())
 
         all_colnames = get_all_colnames()
@@ -1013,41 +1145,45 @@ class Tracker(dict):
                     cw.writerow(argset)
 
 
-def dataMatch(pattern, data, rmax=10, _r=0):
+def dataMatch(pattern, data):
     """Check if data structure matches a pattern data structure.
 
     Supports lists, dictionaries and scalars (int, float, string).
 
-    For scalars, simple `==` is used.  Lists are converted to sets and
-    "to match" means "to have a matching subset (e.g. `[1, 2, 3, 4]`
-    matches `[3, 2]`).  Both lists and dictionaries are matched recursively.
+    For scalars, simple `==` is used.
+
+    Lists are converted to sets and "to match" means "to have a matching
+    subset (e.g. `[1, 2, 3, 4]` matches `[3, 2]`).
+
+    Both lists and dictionaries are matched recursively.
     """
 
     def listMatch(pattern, data):
-        """Match list-like objects"""
+        """
+        Match list-like objects
+        """
         assert all([hasattr(o, 'append') for o in [pattern, data]])
         results = []
         for pv in pattern:
-            if any([dataMatch(pv, dv, _r=_r+1) for dv in data]):
+            if any([dataMatch(pv, dv) for dv in data]):
                 results.append(True)
             else:
                 results.append(False)
         return all(results)
 
     def dictMatch(pattern, data):
-        """Match dict-like objects"""
+        """
+        Match dict-like objects
+        """
         assert all([hasattr(o, 'iteritems') for o in [pattern, data]])
         results = []
         try:
-            for pk, pv in pattern.iteritems():
-                results.append(dataMatch(pv, data[pk], _r=_r+1))
+            for pk, pv in pattern.items():
+                results.append(dataMatch(pv, data[pk]))
         except KeyError:
             results.append(False)
         return all(results)
 
-    if _r == rmax:
-        raise RuntimeError("recursion limit hit")
-
     result = None
     if pattern == data:
         result = True
@@ -1061,13 +1197,16 @@ def dataMatch(pattern, data, rmax=10, _r=0):
 
 
 def jsDump(data):
-    """A human-readable JSON dump."""
+    """
+    A human-readable JSON dump.
+    """
     return json.dumps(data, sort_keys=True, indent=4,
                       separators=(',', ': '))
 
 
 def jsDiff(dira, dirb, namea="A", nameb="B", chara="a", charb="b"):
-    """JSON-based human-readable diff of two data structures.
+    """
+    JSON-based human-readable diff of two data structures.
 
     '''BETA''' version.
 
@@ -1140,7 +1279,7 @@ def jsDiff(dira, dirb, namea="A", nameb="B", chara="a", charb="b"):
         def is_hdr_B(line):
             return line.startswith("+++")
 
-        class Level(object):
+        class Level:
 
             def __init__(self, hint):
                 self.hint = hint
@@ -1154,7 +1293,7 @@ def jsDiff(dira, dirb, namea="A", nameb="B", chara="a", charb="b"):
                     self.hinted = True
                     return self.hint
 
-        class ContextTracker(object):
+        class ContextTracker:
 
             def __init__(self):
                 self.trace = []
@@ -1212,7 +1351,7 @@ def jsDiff(dira, dirb, namea="A", nameb="B", chara="a", charb="b"):
                     buffb.append(line)
 
             else:
-                raise AssertionError("difflib.unified_diff emited"
+                raise AssertionError("difflib.unified_diff emitted"
                                      " unknown format (%s chars):\n%s"
                                      % (len(line), line))
 
@@ -1227,34 +1366,32 @@ def jsDiff(dira, dirb, namea="A", nameb="B", chara="a", charb="b"):
     return "\n".join(compress([line for line in udiff]))
 
 
-class Cartman(object):
-    """Create argument sets from ranges (or ay iterators) of values.
+class Cartman:
+    """
+    Create argument sets from ranges (or ay iterators) of values.
 
     This class is to enable easy definition and generation of dictionary
-    argument  sets using Cartesian product.  You only need to define:
-
-     *  structure of argument set (can be more than just flat dict)
+    argument sets using Cartesian product.
 
-     *  ranges, or arbitrary iterators of values on each "leaf" of the
-        argument set
+    To use Cartman iterator, you need to define structure of an argument
+    set.  Argument set--typically a dictionary--is a set of values that
+    together constitute a test case.  Within the argument set, values
+    will change from test case to test case, so for each changing value,
+    you will also need to define range of values you want to test on.
 
-    Since there is expectation that any argument can have any kind of values
-    even another iterables, the pure logic "iterate it if you can"
-    is insufficient.  Instead, definition is divided in two parts:
+    Cartman initiator expects following arguments:
 
-     *  scheme, which is a "prototype" of a final argument set, except
-        that for each value that will change, a `Cartman.Iterable`
-        sentinel is used.  For each leaf that is constant, `Cartman.Scalar`
-        is used
+     *  *scheme*, which is a "prototype" of a final argument set, except
+        that values are replaced by either `Cartman.Iterable` if the
+        value is changing from test case to another, and `Cartman.Scalar`
+        if the value is constant.
 
-     *  source, which has the same structure, except that where in scheme
-        is `Iterable`, an iterable object is expected, whereas in places
-        where `Scalar` is used, a value is assigned that does not change
-        during iteration.
+     *  *source*, which has the same structure, except that where in scheme
+        is `Cartman.Iterable`, the source has an iterable.  Where scheme has
+        `Cartman.Scalar`, the source can have any value.
 
-    Finally, when such instance is used in loop, argument sets are generated
-    uising Cartesian product of each iterable found.  This allows for
-    relatively easy definition of complex scenarios.
+    Finally, when Cartman instance is used in loop, it uses Cartesian product
+    in order to generate argument sets.
 
     Consider this example:
 
@@ -1310,12 +1447,11 @@ class Cartman(object):
     optimization became possible based on what was used.
     """
 
-
     # TODO: support for arbitrary ordering (profile / nginx)
     # TODO: implement getstats and fmtstats
     # TODO: N-wise
 
-    class _BaseMark(object):
+    class _BaseMark:
         pass
 
     class Scalar(_BaseMark):
@@ -1324,13 +1460,9 @@ class Cartman(object):
     class Iterable(_BaseMark):
         pass
 
-    def __init__(self, source, scheme, recursion_limit=10, _r=0):
+    def __init__(self, source, scheme):
         self.source = source
         self.scheme = scheme
-        self.recursion_limit = recursion_limit
-        self._r = _r
-        if self._r > self.recursion_limit:
-            raise RuntimeError("recursion limit exceeded")
 
         # validate scheme + source and throw useful error
         scheme_ok = isinstance(self.scheme, collections.Mapping)
@@ -1366,16 +1498,14 @@ class Cartman(object):
         elif self._means_iterable(subscheme):
             return subsource
         else:   # try to use it as scheme
-            return iter(Cartman(subsource, subscheme, _r=self._r+1))
+            return iter(Cartman(subsource, subscheme))
 
     def __iter__(self):
 
         names = []
         iterables = []
 
-        keys = self.scheme.keys()
-
-        for key in keys:
+        for key in self.scheme:
             try:
                 iterables.append(self._get_iterable_for(key))
             except KeyError:

tests/test_hoover.py

@@ -371,7 +371,7 @@ class CartmanTest(unittest.TestCase):
 
     def test_withCustomIterator_TypeA(self):
 
-        class ITER_A(object):
+        class ITER_A:
 
             def __init__(self, items):
                 self.items = items
@@ -380,7 +380,7 @@ class CartmanTest(unittest.TestCase):
             def __iter__(self):
                 return self
 
-            def next(self):
+            def __next__(self):
                 try:
                     item = self.items[self.n]
                 except IndexError:
@@ -438,7 +438,7 @@ class CartmanTest(unittest.TestCase):
 
     def test_withCustomIterator_TypeB(self):
 
-        class ITER_B(object):
+        class ITER_B:
 
             def __init__(self, items):
                 self.items = items
@@ -509,7 +509,7 @@ class CartmanTest(unittest.TestCase):
                 'p': ['a', 'b'],
                 'd': [False, True]
             }
-            iter(hoover.Cartman(source, scheme)).next()
+            next(iter(hoover.Cartman(source, scheme)))
 
         self.assertRaises(ValueError, fn)
 
@@ -529,7 +529,7 @@ class CartmanTest(unittest.TestCase):
                 'p': ['a', 'b'],
                 'd': [False, True]
             }
-            iter(hoover.Cartman(source, scheme)).next()
+            next(iter(hoover.Cartman(source, scheme)))
 
         self.assertRaises(ValueError, fn)
 
@@ -543,8 +543,8 @@ class CartmanTest(unittest.TestCase):
                 'b': hoover.Cartman.Iterable,
                 'c': a_mark
             }
-            source = dict.fromkeys(scheme.keys(), [])
-            iter(hoover.Cartman(source, scheme)).next()
+            source = dict.fromkeys(scheme, [])
+            next(iter(hoover.Cartman(source, scheme)))
 
         self.assertRaises(ValueError, fn)
 
@@ -610,7 +610,7 @@ class RuleOpTest(unittest.TestCase):
     # error handling
 
     def testBadOpClass(self):
-        class bad_op(object):
+        class bad_op:
             def _match(self):
                 return True
         fn = lambda: hoover.RuleOp.Match(((bad_op, [])), bool)