[tor-commits] [ooni-probe/master] Edit readme

[art at torproject.org]

commit 5b682fc5b140136560c36b78b573b4a5b3245f84
Author: Arturo Filastò <hellais at torproject.org>
Date:   Mon Apr 30 18:36:16 2012 +0200

    Edit readme
---
 README          |   17 +++++++++++++++--
 plugoo/tests.py |   16 +++++++++++++---
 2 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/README b/README
index 476aa40..75262bf 100644
--- a/README
+++ b/README
@@ -3,8 +3,21 @@ ooni-probe - Open Observatory of Network Interference
 "The Net interprets censorship as damage and routes around it."
                 - John Gilmore; TIME magazine (6 December 1993)
 
-The goal of ooni-probe is to collect data about censorship around
-the world.
+OONI, the Open Observatory of Network Interference, is a global observation
+network which aims is to collect high quality data using open methodologies,
+using Free and Open Source Software (FL/OSS) to share observations and data
+about the various types, methods, and amounts of network tampering in the world.
+
+With the belief that unfettered access to information is a intrinsic human right,
+OONI seeks to observe levels of surveillance, censorship, and network discrimination
+in order for people worldwide to have a clearer understanding of the ways in
+which their access to information is filtered.
+
+The end goal of OONI is to collect data which can show an accurate
+topology of network interference and censorship. Through this topology, it will be
+possible to see what the internet looks like from nearly any location, including
+what sites are censored, or have been tampered with, and by whom. We're calling
+it filternet.
 
 OONI uses open methodologies and the data will be provided in raw
 format to allow any researcher to indipendently draw their conclusions
diff --git a/plugoo/tests.py b/plugoo/tests.py
index fc1d033..9a9f1de 100644
--- a/plugoo/tests.py
+++ b/plugoo/tests.py
@@ -111,13 +111,15 @@ class Test:
         else:
             self.logger.error("No Assets! Dying!")
 
-class WorkUnit:
+class WorkUnit(object):
     """
     This is an object responsible for completing WorkUnits it will
     return its result in a deferred.
 
     The execution of a unit of work should be Atomic.
 
+    Reporting to the OONI-net happens on completion of a Unit of Work.
+
     @Node node: This represents the node associated with the Work Unit
     @Asset asset: This is the asset associated with the Work Unit
     @Test test: This represents the Test to be with the specified assets
@@ -151,6 +153,11 @@ class ITest(Interface):
     This interface represents an OONI test. It fires a deferred on completion.
     """
 
+    shortName = Attribute("""A short user facing description for this test""")
+    description = Attribute("""A string containing a longer description for the test""")
+
+    requirements = Attribtue("""What is required to run this this test, for example raw socket access or UDP or TCP""")
+
     deferred = Attribute("""This will be fired on test completion""")
     node = Attribute("""This represents the node that will run the test""")
     arguments = Attribute("""These are the arguments to be passed to the test for it's execution""")
@@ -160,9 +167,12 @@ class ITest(Interface):
         Launches the Test with the specified arguments on a node.
         """
 
-class WorkGenerator:
+class WorkGenerator(object):
     """
     Factory responsible for creating units of work.
+
+    This shall be run on the machine running OONI-cli. The returned WorkUnits
+    can either be run locally or on a remote OONI Node or Network Node.
     """
     node = LocalNode
     size = 10
@@ -230,7 +240,7 @@ class HTTPRequestTest(HTTPClient):
             self.censorship = False
             return response
 
-class TwistedTestFactory:
+class TwistedTestFactory(object):
 
     test = TwistedTest