Clean up and rewrite most docstrings

A big spring clean of the docstrings (sure long time coming!)

 *  Fix typos,

 *  rewrite clumsy explanations,

 *  omit unnecessary and misleading parts,

 *  remove awkward and "smart" language,

 *  use consistent here-doc formatting across small and big docstrings
    (isolate quote mark triplets on own line.)

sznqalibs/bottleneck.py

@@ -2,7 +2,9 @@ import time
 
 
 class FrameState:
-    """Abstraction and tracking of frame state"""
+    """
+    Abstraction and tracking of frame state
+    """
 
     def __init__(self, max_load, size, debug):
         self.start = 0
@@ -53,7 +55,8 @@ class FrameState:
 
 
 class Throttle:
-    """Throttle to allow only certain amount of iteration per given time.
+    """
+    Throttle to allow only certain amount of iteration per given time.
 
     Usage:
 
@@ -75,11 +78,11 @@ class Throttle:
     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
@@ -95,15 +98,21 @@ class Throttle:
                                 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

@@ -141,7 +141,9 @@ def regression_test(argsrc, tests, driver_settings=None, cleanup_hack=None,
 
 
 def get_data_and_stats(driverClass, argset, driver_settings, only_own=False):
-    """Run test with given driver"""
+    """
+    Run single test, return data and stats.
+    """
     start = time.time()
     d = driverClass()
     d.setup(driver_settings, only_own=only_own)
@@ -150,7 +152,9 @@ def get_data_and_stats(driverClass, argset, driver_settings, only_own=False):
 
 
 def get_data(driverClass, argset, driver_settings, only_own=False):
-    """Run test with given driver"""
+    """
+    Run single test, return data only.
+    """
     d = driverClass()
     d.setup(driver_settings, only_own=only_own)
     d.run(argset)
@@ -194,15 +198,25 @@ class RuleOp:
 
     @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.
         """
 
@@ -226,8 +240,8 @@ class RuleOp:
 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
@@ -335,12 +349,13 @@ class DictPath:
 # ########################################################################### #
 
 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`
@@ -350,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:
+
+     *  avoid known and tracked bugs,
+     *  help normalize results (remove irrelevant details),
+     *  solve certain limitations in oracle machines.
 
-    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`.)
+    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):
@@ -479,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:
@@ -557,33 +601,62 @@ class DriverDataError(Exception):
 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()`
@@ -591,7 +664,7 @@ class BaseTestDriver:
         *   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
@@ -683,15 +756,25 @@ class BaseTestDriver:
 
     @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:
                 driver_class_name, setting_name = ckey.split(".", 2)
@@ -702,7 +785,9 @@ class BaseTestDriver:
         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()?"
@@ -736,7 +821,9 @@ class MockDriverTrue(BaseTestDriver):
 # ########################################################################### #
 
 class StatCounter:
-    """A simple counter with formulas support."""
+    """
+    A simple counter with support for custom formulas.
+    """
 
     def __init__(self):
         self.generic_stats = {}
@@ -807,18 +894,24 @@ class StatCounter:
         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)
@@ -828,15 +921,21 @@ class StatCounter:
             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.items():
             for key, value in dstats.items():
@@ -846,7 +945,8 @@ class StatCounter:
 
 
 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
@@ -861,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,
@@ -897,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)
 
@@ -934,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"
@@ -948,16 +1061,20 @@ class Tracker(dict):
                 + "\n\n" + error_list)
 
     def getstats(self):
-        """Return basic and driver stats
+        """
+        Return basic and driver stats
+
+        Returns dictionary with following values:
 
-            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)`)
+            '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():
@@ -978,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
@@ -990,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:
@@ -999,12 +1119,14 @@ 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 = {}
@@ -1028,13 +1150,18 @@ def dataMatch(pattern, data):
 
     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:
@@ -1045,7 +1172,9 @@ def dataMatch(pattern, data):
         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:
@@ -1068,13 +1197,16 @@ def dataMatch(pattern, data):
 
 
 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.
 
@@ -1235,33 +1367,31 @@ def jsDiff(dira, dirb, namea="A", nameb="B", chara="a", charb="b"):
 
 
 class Cartman:
-    """Create argument sets from ranges (or ay iterators) of values.
+    """
+    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: