event new docs
@@ -18,6 +18,12 @@ from moler.helpers import instance_id
class Event(ConnectionObserver):
def __init__(self, connection=None, till_occurs_times=-1, runner=None):
+ """
+
+ :param connection: connection to observe.
+ :param till_occurs_times: If -1 then infinite. If positive value match the number of times.
+ :param runner: runner to run event.
+ """
super(Event, self).__init__(connection=connection, runner=runner)
# By default events are infinite (100 years :-) so, they won't timeout since they are
# mainly designed to catch something inside event_occurred(), notify interested parties and keep going.
@@ -30,6 +36,11 @@ class Event(ConnectionObserver):
self.event_name = Event.observer_name
def __str__(self):
+ """
+ Returns description of event object.
+
+ :return: String representation of event.
+ """
return '{}(id:{})'.format(self.__class__.__name__, instance_id(self))
def start(self, timeout=None, *args, **kwargs):
@@ -42,26 +53,52 @@ class Event(ConnectionObserver):
def add_event_occurred_callback(self, callback, callback_params):
if not self.callback:
- callback = functools.partial(callback, **callback_params)
- self.callback = callback
+ partial_callback = functools.partial(callback, **callback_params)
+ self.callback = partial_callback
else:
- raise MolerException("Cannot assign already assigned 'self.callback'.")
+ raise MolerException("Cannot assign a callback '{}' to event '{}' when another callback '{}'is already "
+ "assigned".format(callback, self, self.callback))
def enable_log_occurrence(self):
+ """
+ Enables to log every occurrence of the event.
+
+ :return: None
+ """
self._log_every_occurrence = True
def disable_log_occurrence(self):
+ """
+ Disables to log every occurrence of the event.
+
+ :return: None
+ """
self._log_every_occurrence = False
def remove_event_occurred_callback(self):
+ """
+ Removes callback from the event.
+
+ :return: None
+ """
self.callback = None
def notify(self):
+ """
+ Notifies (call callback).
+
+ :return: None
+ """
self._log_occurred()
if self.callback:
self.callback()
def event_occurred(self, event_data):
+ """
+ Sets event_data as new item of occurrence ret.
+ :param event_data: data to set as value of occurrence.
+ :return: None
+ """
"""Should be used to set final result"""
if self.done():
raise ResultAlreadySet(self)
@@ -73,13 +110,31 @@ class Event(ConnectionObserver):
self.set_result(self._occurred)
self.notify()
+ def _get_module_class(self):
+ return "{}.{}".format(self.__class__.__module__, self)
+
def get_long_desc(self):
- return "Event '{}.{}'".format(self.__class__.__module__, self)
+ """
+ Returns string with description of event.
+
+ :return: String with description.
+ """
+ return "Event '{}'".format(self._get_module_class())
def get_short_desc(self):
- return "Event '{}.{}'".format(self.__class__.__module__, self)
+ """
+ Returns string with description of event.
+
+ :return: String with description.
+ """
+ return self.get_long_desc()
def get_last_occurrence(self):
+ """
+ Returns ret value from last occurrence.
+
+ :return: ret value form last occurrence or None if there is no occurrence.
+ """
if self._occurred:
return self._occurred[-1]
else:
