[tor-commits] [ooni-probe/master] Write some docstrings and minor refactor
art at torproject.org
art at torproject.org
Tue Jul 10 15:30:00 UTC 2012
commit 3f9714d942656c552ad71e8172c83d55016a8c73
Author: Arturo Filastò <art at 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()
More information about the tor-commits
mailing list