[tor-commits] [ooni-probe/master] Improvements to docstrings in ooni.agent and ooni.ui.web

[art at torproject.org]

commit d9f3c7aaf1a4f9cc6b11b4508c36fb8b3d56114d
Author: Donald <donald213 at users.noreply.github.com>
Date:   Sun Nov 27 00:07:38 2016 +0100

    Improvements to docstrings in ooni.agent and ooni.ui.web
---
 ooni/agent/agent.py     | 14 +++++++++++++-
 ooni/agent/scheduler.py | 29 ++++++++++++++++++++++++++++-
 ooni/ui/web/web.py      | 11 ++++++++++-
 3 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/ooni/agent/agent.py b/ooni/agent/agent.py
index 01e2162..9c057e6 100644
--- a/ooni/agent/agent.py
+++ b/ooni/agent/agent.py
@@ -6,9 +6,17 @@ from ooni.ui.web.web import WebUIService
 from ooni.agent.scheduler import SchedulerService
 
 class AgentService(service.MultiService):
+    """Manage agent services."""
+
+
     def __init__(self, web_ui_port):
-        service.MultiService.__init__(self)
+        """Load configuration or made the default configuration of the service.
+
 
+        If the advanced configuration is not enabled, the page is not displayed.
+        Else, if the advanced configuration is enabled, the page is displayed."""
+
+        service.MultiService.__init__(self)
         director = Director()
 
         self.scheduler_service = SchedulerService(director)
@@ -22,7 +30,11 @@ class AgentService(service.MultiService):
 
 
     def startService(self):
+        """Run a service."""
+
         service.MultiService.startService(self)
 
     def stopService(self):
+        """Kill a service."""
+
         service.MultiService.stopService(self)
diff --git a/ooni/agent/scheduler.py b/ooni/agent/scheduler.py
index d63a6b1..41c27f1 100644
--- a/ooni/agent/scheduler.py
+++ b/ooni/agent/scheduler.py
@@ -35,6 +35,8 @@ class FileSystemlockAndMutex(object):
     different stacks (threads/fibers) within the same process without races.
     """
     def __init__(self, file_path):
+        """Allows for an Object-oriented filesystem path a representation to be fired when the lock is acquired.
+        Create a lock for event driven systems."""
         self._fs_lock = defer.DeferredFilesystemLock(file_path)
         self._mutex = defer.DeferredLock()
 
@@ -44,6 +46,7 @@ class FileSystemlockAndMutex(object):
         yield self._fs_lock.deferUntilLocked()
 
     def release(self):
+        """Release the locks of the filesystem and the event driven system."""
         self._fs_lock.unlock()
         self._mutex.release()
 
@@ -88,16 +91,25 @@ class ScheduledTask(object):
         )
 
     def cancel(self):
+        """Closes the task.
+
+        Releases all locks (releases the locks of the filesystem and the event driven system)."""
         if self._last_run_lock.locked:
             self._last_run_lock.release()
 
+
     @property
     def should_run(self):
+        """
+
+        """
         current_time = datetime.utcnow().replace(tzinfo=tz.tzutc())
         next_cycle = croniter(self.schedule, self.last_run).get_next(datetime)
         if next_cycle <= current_time:
             return True
         return False
+        #should_run = property(should_run())
+
 
     @property
     def last_run(self):
@@ -110,6 +122,9 @@ class ScheduledTask(object):
             tzinfo=tz.tzutc())
 
     def _update_last_run(self, last_run_time):
+        """Update time.
+
+        Write the curent time into a file. If the file already exists, the file is overwrited."""
         with self._last_run.open('w') as out_file:
             out_file.write(last_run_time.strftime(self._time_format))
 
@@ -409,14 +424,23 @@ class SchedulerService(service.MultiService):
             self.schedule(RunDeck(self.director, deck_id, schedule))
 
     def _task_did_not_run(self, failure, task):
+        """React in case of task absent.
+
+        TODO and Write debugging log to report this error."""
         failure.trap(DidNotRun)
         log.debug("Did not run {0}".format(task.identifier))
 
-    def _task_failed(self, failure, task):
+    def _task_failed(self, failure, task):#is this place the right one to raise error as described in the doc?
+        """React in case of task faillure during the launching.
+
+        Write debugging logs to report the error."""
         log.err("Failed to run {0}".format(task.identifier))
         log.exception(failure)
 
     def _task_success(self, result, task):
+        """React in case of successfull launching.
+
+        Writes log about debugging."""
         log.debug("Ran {0}".format(task.identifier))
 
     def _should_run(self):
@@ -453,5 +477,8 @@ class SchedulerService(service.MultiService):
         self._looping_call.start(self.interval)
 
     def stopService(self):
+        """Stop the Scheduler.
+
+        Stop the Scheduler's service and kill the graphical user interface loop."""
         service.MultiService.stopService(self)
         self._looping_call.stop()
diff --git a/ooni/ui/web/web.py b/ooni/ui/web/web.py
index f36e0a2..fe9498a 100644
--- a/ooni/ui/web/web.py
+++ b/ooni/ui/web/web.py
@@ -6,6 +6,8 @@ from ooni.ui.web.server import WebUIAPI
 from ooni.settings import config
 
 class WebUIService(service.MultiService):
+    """This multiservice contains the ooniprobe web user interface."""
+
     def __init__(self, director, scheduler, port_number=8842):
         service.MultiService.__init__(self)
 
@@ -14,6 +16,10 @@ class WebUIService(service.MultiService):
         self.port_number = port_number
 
     def startService(self):
+        """Start a web user interface.
+
+        Connects a given protocol factory to the given numeric TCP/IP port and open a page."""
+
         service.MultiService.startService(self)
 
         web_ui_api = WebUIAPI(config, self.director, self.scheduler)
@@ -21,9 +27,12 @@ class WebUIService(service.MultiService):
             self.port_number,
             server.Site(web_ui_api.app.resource()),
             interface=config.advanced.webui_address
-        )
+            )
 
     def stopService(self):
+        """Close the web page.
+
+        Close the service, verify that the connection is really finished. If the program is still listenning, the program kill the connection."""
         service.MultiService.stopService(self)
         if self._port:
             self._port.stopListening()