commit d9f3c7aaf1a4f9cc6b11b4508c36fb8b3d56114d Author: Donald <donald213@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()