commit 3f9714d942656c552ad71e8172c83d55016a8c73 Author: Arturo Filastò <art@torproject.org> Date: Tue Jul 10 07:09:35 2012 +0200 Write some docstrings and minor refactor --- ooni/plugins/captiveportal.py | 6 +--- ooni/plugoo/tests.py | 44 +++++++++++++++++++++++++++++++++++++++++ ooni/plugoo/work.py | 27 +++++++++++++++++++++++++ 3 files changed, 73 insertions(+), 4 deletions(-) diff --git a/ooni/plugins/captiveportal.py b/ooni/plugins/captiveportal.py index 9b7bee3..1f13431 100644 --- a/ooni/plugins/captiveportal.py +++ b/ooni/plugins/captiveportal.py @@ -93,14 +93,12 @@ class CaptivePortal(OONITest): if fuzzy: pattern = re.compile(control_result) match = pattern.search(response_content) + log.msg("Fuzzy HTTP content comparison for experiment URL") + log.msg("'%s'" % experimental_url) if not match: - log.msg("Fuzzy HTTP content comparison for experiment URL") - log.msg("'%s'" % experimental_url) log.msg("does not match!") return False, response_code, response_headers else: - log.msg("Fuzzy HTTP content comparison of experiment URL") - log.msg("'%s'" % experimental_url) log.msg("and the expected control result yielded a match.") return True, response_code, response_headers else: diff --git a/ooni/plugoo/tests.py b/ooni/plugoo/tests.py index a3e9150..47bb135 100644 --- a/ooni/plugoo/tests.py +++ b/ooni/plugoo/tests.py @@ -15,11 +15,21 @@ from ooni.plugoo.interface import ITest class OONITest(object): + """ + This is the base class for writing OONI Tests. + + It should be used in conjunction with the ITest Interface. It allows the + developer to benefit from OONIs reporting system and command line argument + parsing system. + """ + # By default we set this to False, meaning that we don't block blocking = False def __init__(self, local_options, global_options, report, ooninet=None, reactor=None): + # These are the options that are read through the tests suboptions self.local_options = local_options + # These are the options global to all of OONI self.global_options = global_options self.assets = self.load_assets() self.report = report @@ -29,6 +39,10 @@ class OONITest(object): self.result = {} def initialize(self): + """ + Override this method if you are interested in having some extra + behavior when your test class is instantiated. + """ pass def load_assets(self): @@ -43,6 +57,10 @@ class OONITest(object): self.assets) def finished(self, control): + """ + The Test has finished running, we must now calculate the test runtime + and add all time data to the report. + """ #self.ooninet.report(result) self.end_time = date.now() result = self.result @@ -55,6 +73,13 @@ class OONITest(object): return result def _do_experiment(self, args): + """ + A wrapper around the launch of experiment. + If we are running a blocking test experiment will be run in a thread if + not we expect it to return a Deferred. + + @param args: the asset line(s) that we are working on. + """ if self.blocking: self.d = threads.deferToThread(self.experiment, args) else: @@ -65,6 +90,13 @@ class OONITest(object): return self.d def control(self, result, args): + """ + Run the control. + + @param result: what was returned by experiment. + + @param args: the asset(s) lines that we are working on. + """ log.msg("Doing control") if self.blocking: @@ -77,11 +109,23 @@ class OONITest(object): return d def experiment(self, args): + """ + Run the experiment. This sample implementation returns a deferred, + making it a non-blocking test. + + @param args: the asset(s) lines that we are working on. + """ log.msg("Doing experiment") d = defer.Deferred() return d def startTest(self, args): + """ + This method is invoked by the worker to start the test with one line of + the asset file. + + @param args: the asset(s) lines that we are working on. + """ self.start_time = date.now() log.msg("Starting test %s" % self.__class__) return self._do_experiment(args) diff --git a/ooni/plugoo/work.py b/ooni/plugoo/work.py index fc338d7..a8b6595 100644 --- a/ooni/plugoo/work.py +++ b/ooni/plugoo/work.py @@ -25,11 +25,23 @@ class Worker(object): runs them concurrently. """ def __init__(self, maxconcurrent=10): + """ + @param maxconcurrent: how many test instances should be run + concurrently. + """ self.maxconcurrent = maxconcurrent self._running = 0 self._queued = [] def _run(self, r): + """ + Check if we should start another test because we are below maximum + concurrency. + + This function is called every time a test finishes running. + + @param r: the return value of a previous test. + """ self._running -= 1 if self._running < self.maxconcurrent and self._queued: workunit, d = self._queued.pop(0) @@ -38,6 +50,7 @@ class Worker(object): actuald = test.startTest(asset).addBoth(self._run) if isinstance(r, failure.Failure): + # XXX probably we should be doing something to retry test running r.trap() if self._running == 0 and not self._queued: @@ -46,6 +59,15 @@ class Worker(object): return r def push(self, workunit): + """ + Add a test to the test queue and run it if we are not maxed out on + concurrency. + + @param workunit: a tuple containing the (asset, test, idx), where asset + is the line of the asset(s) we are working on, test + is an instantiated test and idx is the index we are + currently at. + """ if self._running < self.maxconcurrent: asset, test, idx = workunit self._running += 1 @@ -83,6 +105,11 @@ class WorkGenerator(object): return self def skip(self, start): + """ + Skip the first x number of lines of the asset. + + @param start: int how many items we should skip. + """ for j in xrange(0, start-1): for i in xrange(0, self.size): self.assetGenerator.next()