commit 22720e383093c0d30fd1b6ca44794d3b29031f91 Author: Arturo Filastò arturo@filasto.net Date: Wed Dec 14 13:11:42 2016 +0000

Cleanup of docs from @donald213 --- ooni/agent/agent.py | 15 ++++----------- ooni/agent/scheduler.py | 49 +++++++++++++++++++++++-------------------------- ooni/ui/web/web.py | 7 ------- 3 files changed, 27 insertions(+), 44 deletions(-)

diff --git a/ooni/agent/agent.py b/ooni/agent/agent.py index 9c057e6..20b9332 100644 --- a/ooni/agent/agent.py +++ b/ooni/agent/agent.py @@ -6,16 +6,13 @@ from ooni.ui.web.web import WebUIService from ooni.agent.scheduler import SchedulerService

class AgentService(service.MultiService): - """Manage agent services.""" + """Manage all services related to the ooniprobe-agent daemon."""

def __init__(self, web_ui_port): - """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.""" - + """ + If the advanced->disabled_webui is set to true then we will not start the WebUI. + """ service.MultiService.__init__(self) director = Director()

@@ -30,11 +27,7 @@ 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 41c27f1..4bf058a 100644 --- a/ooni/agent/scheduler.py +++ b/ooni/agent/scheduler.py @@ -35,8 +35,10 @@ 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.""" + """ + Args: + file_path: is the location of where the filesystem based lockfile should be written to. + """ self._fs_lock = defer.DeferredFilesystemLock(file_path) self._mutex = defer.DeferredLock()

@@ -46,7 +48,7 @@ class FileSystemlockAndMutex(object): yield self._fs_lock.deferUntilLocked()

def release(self): - """Release the locks of the filesystem and the event driven system.""" + """Release the filesystem based and in memory locks.""" self._fs_lock.unlock() self._mutex.release()

@@ -91,24 +93,21 @@ class ScheduledTask(object): )

def cancel(self): - """Closes the task. - - Releases all locks (releases the locks of the filesystem and the event driven system).""" + """ + Cancel a currently running task. + If it is locked, then release the lock. + """ 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 @@ -122,9 +121,10 @@ 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.""" + """ + Update the time at which this task ran successfully last, by running + to a file. + """ with self._last_run.open('w') as out_file: out_file.write(last_run_time.strftime(self._time_format))

@@ -424,23 +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.""" + """ + Fired when a tasks did not run. This is not an error. + """ failure.trap(DidNotRun) log.debug("Did not run {0}".format(task.identifier))

- 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.""" + def _task_failed(self, failure, task): + """ + Fired when a task failed to run due to an 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.""" + """ + Fired when a task has successfully run. + """ log.debug("Ran {0}".format(task.identifier))

def _should_run(self): @@ -477,8 +477,5 @@ 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 fe9498a..081022a 100644 --- a/ooni/ui/web/web.py +++ b/ooni/ui/web/web.py @@ -16,10 +16,6 @@ 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) @@ -30,9 +26,6 @@ class WebUIService(service.MultiService): )

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()