diff --git a/docs/topics/api.rst b/docs/topics/api.rst index e59fe9a58..f3a03bb74 100644 --- a/docs/topics/api.rst +++ b/docs/topics/api.rst @@ -358,54 +358,10 @@ SpiderLoader API Signals API =========== -.. module:: scrapy.signalmanager - :synopsis: The signal manager - -.. class:: SignalManager - - .. method:: connect(receiver, signal) - - Connect a receiver function to a signal. - - The signal can be any object, although Scrapy comes with some - predefined signals that are documented in the :ref:`topics-signals` - section. - - :param receiver: the function to be connected - :type receiver: callable - - :param signal: the signal to connect to - :type signal: object - - .. method:: send_catch_log(signal, \*\*kwargs) - - Send a signal, catch exceptions and log them. - - The keyword arguments are passed to the signal handlers (connected - through the :meth:`connect` method). - - .. method:: send_catch_log_deferred(signal, \*\*kwargs) - - Like :meth:`send_catch_log` but supports returning `deferreds`_ from - signal handlers. - - Returns a `deferred`_ that gets fired once all signal handlers - deferreds were fired. Send a signal, catch exceptions and log them. - - The keyword arguments are passed to the signal handlers (connected - through the :meth:`connect` method). - - .. method:: disconnect(receiver, signal) - - Disconnect a receiver function from a signal. This has the opposite - effect of the :meth:`connect` method, and the arguments are the same. - - .. method:: disconnect_all(signal) - - Disconnect all receivers from the given signal. - - :param signal: the signal to disconnect from - :type signal: object +.. automodule:: scrapy.signalmanager + :synopsis: The signal manager + :members: + :undoc-members: .. _topics-api-stats: diff --git a/scrapy/signalmanager.py b/scrapy/signalmanager.py index 4a3e3d92d..90a14bd63 100644 --- a/scrapy/signalmanager.py +++ b/scrapy/signalmanager.py @@ -1,27 +1,71 @@ +from __future__ import absolute_import from scrapy.xlib.pydispatch import dispatcher -from scrapy.utils import signal +from scrapy.utils import signal as _signal + class SignalManager(object): def __init__(self, sender=dispatcher.Anonymous): self.sender = sender - def connect(self, *a, **kw): - kw.setdefault('sender', self.sender) - return dispatcher.connect(*a, **kw) + def connect(self, receiver, signal, **kwargs): + """ + Connect a receiver function to a signal. - def disconnect(self, *a, **kw): - kw.setdefault('sender', self.sender) - return dispatcher.disconnect(*a, **kw) + The signal can be any object, although Scrapy comes with some + predefined signals that are documented in the :ref:`topics-signals` + section. - def send_catch_log(self, *a, **kw): - kw.setdefault('sender', self.sender) - return signal.send_catch_log(*a, **kw) + :param receiver: the function to be connected + :type receiver: callable - def send_catch_log_deferred(self, *a, **kw): - kw.setdefault('sender', self.sender) - return signal.send_catch_log_deferred(*a, **kw) + :param signal: the signal to connect to + :type signal: object + """ + kwargs.setdefault('sender', self.sender) + return dispatcher.connect(receiver, signal, **kwargs) - def disconnect_all(self, *a, **kw): - kw.setdefault('sender', self.sender) - return signal.disconnect_all(*a, **kw) + def disconnect(self, receiver, signal, **kwargs): + """ + Disconnect a receiver function from a signal. This has the + opposite effect of the :meth:`connect` method, and the arguments + are the same. + """ + kwargs.setdefault('sender', self.sender) + return dispatcher.disconnect(receiver, signal, **kwargs) + + def send_catch_log(self, signal, **kwargs): + """ + Send a signal, catch exceptions and log them. + + The keyword arguments are passed to the signal handlers (connected + through the :meth:`connect` method). + """ + kwargs.setdefault('sender', self.sender) + return _signal.send_catch_log(signal, **kwargs) + + def send_catch_log_deferred(self, signal, **kwargs): + """ + Like :meth:`send_catch_log` but supports returning `deferred`_ from + signal handlers. + + Returns a `deferred`_ that gets fired once all signal handlers + deferreds were fired. Send a signal, catch exceptions and log them. + + The keyword arguments are passed to the signal handlers (connected + through the :meth:`connect` method). + + .. _deferreds: http://twistedmatrix.com/documents/current/core/howto/defer.html + """ + kwargs.setdefault('sender', self.sender) + return _signal.send_catch_log_deferred(signal, **kwargs) + + def disconnect_all(self, signal, **kwargs): + """ + Disconnect all receivers from the given signal. + + :param signal: the signal to disconnect from + :type signal: object + """ + kwargs.setdefault('sender', self.sender) + return _signal.disconnect_all(signal, **kwargs)