diff --git a/deluge/component.py b/deluge/component.py index c1d5b05d7..cdeaa59ab 100644 --- a/deluge/component.py +++ b/deluge/component.py @@ -42,31 +42,43 @@ class ComponentAlreadyRegistered(Exception): class Component(object): """ - Component objects are singletons managed by the `:class:ComponentRegistry`. + Component objects are singletons managed by the :class:`ComponentRegistry`. When a new Component object is instantiated, it will be automatically - registered with the `:class:ComponentRegistry`. + registered with the :class:`ComponentRegistry`. The ComponentRegistry has the ability to start, stop, pause and shutdown the components registered with it. - Events: + **Events:** - start() - This method is called when the client has connected to a + **start()** - This method is called when the client has connected to a Deluge core. - stop() - This method is called when the client has disconnected from a + **stop()** - This method is called when the client has disconnected from a Deluge core. - update() - This method is called every 1 second by default while the - Componented is in a "Started" state. The interval can be + **update()** - This method is called every 1 second by default while the + Componented is in a *Started* state. The interval can be specified during instantiation. The update() timer can be - paused by instructing the `:class:ComponentRegistry` to pause + paused by instructing the :class:`ComponentRegistry` to pause this Component. - shutdown() - This method is called when the client is exiting. If the + **shutdown()** - This method is called when the client is exiting. If the Component is in a "Started" state when this is called, a call to stop() will be issued prior to shutdown(). + **States:** + + A Component can be in one of these 3 states. + + **Started** - The Component has been started by the :class:`ComponentRegistry` + and will have it's update timer started. + + **Stopped** - The Component has either been stopped or has yet to be started. + + **Paused** - The Component has had it's update timer stopped, but will + still be considered in a Started state. + """ def __init__(self, name, interval=1, depend=None): self._component_name = name @@ -158,7 +170,7 @@ class Component(object): class ComponentRegistry(object): """ The ComponentRegistry holds a list of currently registered - `:class:Component` objects. It is used to manage the Components by + :class:`Component` objects. It is used to manage the Components by starting, stopping, pausing and shutting them down. """ def __init__(self): @@ -172,8 +184,7 @@ class ComponentRegistry(object): :param obj: the Component object :type obj: object - :raises ComponentAlreadyRegistered: if a component with the same name - is already registered. + :raises ComponentAlreadyRegistered: if a component with the same name is already registered. """ name = obj._component_name @@ -205,15 +216,14 @@ class ComponentRegistry(object): def start(self, names=[]): """ Starts Components that are currently in a Stopped state and their - dependencies. If `:param:names` is specified, will only start those + dependencies. If *names* is specified, will only start those Components and their dependencies and if not it will start all registered components. :param names: a list of Components to start :type names: list - :returns: a Deferred object that will fire once all Components have been - sucessfully started + :returns: a Deferred object that will fire once all Components have been sucessfully started :rtype: twisted.internet.defer.Deferred """ @@ -242,30 +252,20 @@ class ComponentRegistry(object): def stop(self, names=[]): """ Stops Components that are currently not in a Stopped state. If - `:param:names` is specified, then it will only stop those Components, + *names* is specified, then it will only stop those Components, and if not it will stop all the registered Components. :param names: a list of Components to start :type names: list - :returns: a Deferred object that will fire once all Components have been - sucessfully stopped + :returns: a Deferred object that will fire once all Components have been sucessfully stopped :rtype: twisted.internet.defer.Deferred - :raises KeyError: if a component name is not registered - """ if not names: names = self.components.keys() elif isinstance(names, str): - if names in self.components: - names = [names] - else: - raise KeyError("%s is not a registered component!" % names) - - for name in names: - if name not in self.components: - raise KeyError("%s is not a registered component!" % name) + names = [names] deferreds = [] @@ -278,14 +278,13 @@ class ComponentRegistry(object): def pause(self, names=[]): """ Pauses Components that are currently in a Started state. If - `:param:names` is specified, then it will only pause those Components, + *names* is specified, then it will only pause those Components, and if not it will pause all the registered Components. :param names: a list of Components to pause :type names: list - :returns: a Deferred object that will fire once all Components have been - sucessfully paused + :returns: a Deferred object that will fire once all Components have been sucessfully paused :rtype: twisted.internet.defer.Deferred """ @@ -305,14 +304,13 @@ class ComponentRegistry(object): def resume(self, names=[]): """ Resumes Components that are currently in a Paused state. If - `:param:names` is specified, then it will only resume those Components, + *names* is specified, then it will only resume those Components, and if not it will resume all the registered Components. :param names: a list of Components to resume :type names: list - :returns: a Deferred object that will fire once all Components have been - sucessfully resumed + :returns: a Deferred object that will fire once all Components have been sucessfully resumed :rtype: twisted.internet.defer.Deferred """ @@ -332,12 +330,11 @@ class ComponentRegistry(object): def shutdown(self): """ Shutdowns all Components regardless of state. This will call - `:meth:stop` on call the components prior to shutting down. This should + :meth:`stop` on call the components prior to shutting down. This should be called when the program is exiting to ensure all Components have a chance to properly shutdown. - :returns: a Deferred object that will fire once all Components have been - sucessfully resumed + :returns: a Deferred object that will fire once all Components have been sucessfully resumed :rtype: twisted.internet.defer.Deferred """ diff --git a/tests/test_alertmanager.py b/tests/test_alertmanager.py index 8f16df21f..ae3fb1733 100644 --- a/tests/test_alertmanager.py +++ b/tests/test_alertmanager.py @@ -4,14 +4,23 @@ import common from deluge.core.alertmanager import AlertManager from deluge.core.core import Core +import deluge.component as component class AlertManagerTestCase(unittest.TestCase): def setUp(self): self.core = Core() - self.am = AlertManager() - self.am.start() + self.am = component.get("AlertManager") + component.start(["AlertManager"]) + def tearDown(self): + def on_shutdown(result): + component._ComponentRegistry.components = {} + del self.am + del self.core + + return component.shutdown().addCallback(on_shutdown) + def test_register_handler(self): def handler(alert): return