codex-storage
/
deluge
mirror of https://github.com/codex-storage/deluge.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[Base] Fix Component docs

This commit is contained in:
bendikro 2016-04-24 15:46:20 +02:00
parent 5e493f2d3f
commit d1acd964a5
1 changed files with 74 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

143
deluge/component.py
View File

@ -34,8 +34,8 @@ class ComponentException(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`.
@ -80,6 +80,14 @@ class Component(object):
"""
def __init__(self, name, interval=1, depend=None):
"""Initialize component.
Args:
name (str): Name of component.
interval (int, optional): The interval in seconds to call the update function.
depend (list, optional): The names of components this component depends on.
"""
self._component_name = name
self._component_interval = interval
self._component_depend = depend
@ -212,10 +220,9 @@ 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
starting, stopping, pausing and shutting them down.
"""The ComponentRegistry holds a list of currently registered :class:`Component` objects.
It is used to manage the Components by starting, stopping, pausing and shutting them down.
"""
def __init__(self):
self.components = {}
@ -223,20 +230,21 @@ class ComponentRegistry(object):
self.dependents = defaultdict(list)
def register(self, obj):
"""
Registers a component object with the registry. This is done
automatically when a Component object is instantiated.
"""Register a component object with the registry.
:param obj: the Component object
:type obj: object
Note:
This is done automatically when a Component object is instantiated.
:raises ComponentAlreadyRegistered: if a component with the same name is already registered.
Args:
obj (Component): A component object to register.
Raises:
ComponentAlreadyRegistered: If a component with the same name is already registered.
"""
name = obj._component_name
if name in self.components:
raise ComponentAlreadyRegistered(
"Component already registered with name %s" % name)
raise ComponentAlreadyRegistered("Component already registered with name %s" % name)
self.components[obj._component_name] = obj
if obj._component_depend:
@ -244,12 +252,14 @@ class ComponentRegistry(object):
self.dependents[depend].append(name)
def deregister(self, obj):
"""
Deregisters a component from the registry. A stop will be
"""Deregister a component from the registry. A stop will be
issued to the component prior to deregistering it.
:param obj: the Component object
:type obj: object
Args:
obj (Component): a component object to deregister
Returns:
Deferred: a deferred object that will fire once the Component has been sucessfully deregistered
"""
if obj in self.components.values():
@ -264,17 +274,16 @@ class ComponentRegistry(object):
return succeed(None)
def start(self, names=None):
"""
Starts Components that are currently in a Stopped state and their
dependencies. If *names* is specified, will only start those
Components and their dependencies and if not it will start all
registered components.
"""Start Components, and their dependencies, that are currently in a Stopped state.
:param names: a list of Components to start
:type names: list
Note:
If no names are specified then all registered components will be started.
:returns: a Deferred object that will fire once all Components have been sucessfully started
:rtype: twisted.internet.defer.Deferred
Args:
names (list): A list of Components to start and their dependencies.
Returns:
Deferred: Fired once all Components have been successfully started.
"""
# Start all the components if names is empty
@ -300,16 +309,16 @@ class ComponentRegistry(object):
return DeferredList(deferreds)
def stop(self, names=None):
"""
Stops Components that are currently not in a Stopped state. If
*names* is specified, then it will only stop those Components,
and if not it will stop all the registered Components.
"""Stop Components that are currently not in a Stopped state.
:param names: a list of Components to start
:type names: list
Note:
If no names are specified then all registered components will be stopped.
:returns: a Deferred object that will fire once all Components have been sucessfully stopped
:rtype: twisted.internet.defer.Deferred
Args:
names (list): A list of Components to stop.
Returns:
Deferred: Fired once all Components have been successfully stopped.
"""
if not names:
@ -338,16 +347,16 @@ class ComponentRegistry(object):
return DeferredList(deferreds)
def pause(self, names=None):
"""
Pauses Components that are currently in a Started state. If
*names* is specified, then it will only pause those Components,
and if not it will pause all the registered Components.
"""Pause Components that are currently in a Started state.
:param names: a list of Components to pause
:type names: list
Note:
If no names are specified then all registered components will be paused.
:returns: a Deferred object that will fire once all Components have been sucessfully paused
:rtype: twisted.internet.defer.Deferred
Args:
names (list): A list of Components to pause.
Returns:
Deferred: Fired once all Components have been successfully paused.
"""
if not names:
@ -364,16 +373,16 @@ class ComponentRegistry(object):
return DeferredList(deferreds)
def resume(self, names=None):
"""
Resumes Components that are currently in a Paused state. If
*names* is specified, then it will only resume those Components,
and if not it will resume all the registered Components.
"""Resume Components that are currently in a Paused state.
:param names: a list of Components to resume
:type names: list
Note:
If no names are specified then all registered components will be resumed.
:returns: a Deferred object that will fire once all Components have been successfully resumed
:rtype: twisted.internet.defer.Deferred
Args:
names (list): A list of Components to to resume.
Returns:
Deferred: Fired once all Components have been successfully resumed.
"""
if not names:
@ -390,14 +399,13 @@ class ComponentRegistry(object):
return DeferredList(deferreds)
def shutdown(self):
"""
Shutdowns all Components regardless of state. This will call
: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.
"""Shutdown all Components regardless of state.
:returns: a Deferred object that will fire once all Components have been successfully shut down
:rtype: twisted.internet.defer.Deferred
This will call stop() on all 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:
Deferred: Fired once all Components have been successfully shut down.
"""
def on_stopped(result):
@ -406,10 +414,7 @@ class ComponentRegistry(object):
return self.stop(self.components.keys()).addCallback(on_stopped)
def update(self):
"""
Updates all Components that are in a Started state.
"""
"""Update all Components that are in a Started state."""
for component in self.components.items():
try:
component.update()
@ -429,16 +434,16 @@ shutdown = _ComponentRegistry.shutdown
def get(name):
"""
Return a reference to a component.
"""Return a reference to a component.
:param name: the Component name to get
:type name: string
Args:
name (str): The Component name to get.
:returns: the Component object
:rtype: object
Returns:
Component: The Component object.
:raises KeyError: if the Component does not exist
Raises:
KeyError: If the Component does not exist.
"""
return _ComponentRegistry.components[name]