Source code for m4us.core.components

# -*- coding: utf-8 -*-

#---Header---------------------------------------------------------------------

# This file is part of Message For You Sir (m4us).
# Copyright © 2009-2012 Krys Lawrence
#
# Message For You Sir is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
# the Free Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Message For You Sir is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License
# for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with Message For You Sir.  If not, see <http://www.gnu.org/licenses/>.


"""Provides various kinds of `Component` classes.

`Components` are `coroutines` with context.  That is, they are classes that
implement :class:`~m4us.core.interfaces.ICoroutine`, but can also store and
access instance attributes.

"""


#---Imports--------------------------------------------------------------------

#---  Standard library imports
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from __future__ import unicode_literals
## pylint: disable=W0622, W0611
from future_builtins import ascii, filter, hex, map, oct, zip  ## NOQA
## pylint: enable=W0622, W0611

#---  Third-party imports
## pylint: disable=F0401
from zope import interface
## pylint: enable=F0401
# This is imported directly for the sample coroutine
## pylint: disable=F0401
from zope.interface import provider
## pylint: enable=F0401

#---  Project imports
from m4us.core import interfaces
# These are imported directly for the sample coroutine
from m4us.core.utils import is_shutdown
from m4us.core.interfaces import ICoroutineFactory


#---Globals--------------------------------------------------------------------


#---Functions------------------------------------------------------------------


#---Classes--------------------------------------------------------------------

@interface.implementer(interfaces.ICoroutine)
@interface.provider(interfaces.ICoroutineFactory)
[docs]class Component(object): """Base class for `components`. `Components` act like `coroutines` but can store and retrieve context via instance attributes. This corresponds in concept to Kamaelia_'s :class:`!Component` class. `Components` have an internal `coroutine` defined in the :meth:`_main` method, which sub-classes should implement. :param collections.Mapping kwargs: Any keyword arguments given at instantiation are automatically set as instance attributes for convenience. :implements: :class:`m4us.core.interfaces.ICoroutine` :provides: :class:`m4us.core.interfaces.ICoroutineFactory` .. _Kamaelia: http://www.kamaelia.org/ .. automethod:: _main """ def __init__(self, **kwargs): """See class docstring for this method's documentation.""" self.__dict__.update(kwargs) self._coroutine = self._main() self._coroutine.send(None)
[docs] def _main(self): """The `component`'s `coroutine`. Sub-classes are expected to override this method. It should be a `coroutine` which will automatically be activated upon instantiation. This `coroutine` should work just like regular `coroutines`, but has access to ``self`` and any context that the instance contains. """ raise NotImplementedError( 'Sub-classes must implement the _main() method.')
[docs] def send(self, message): """Send the `message` to the `component`. This method just passes the `message` on to the internal `coroutine` defined in :meth:`_main`, returning any resulting `message`. .. seealso:: The :class:`~m4us.core.interfaces.ICoroutine` `interface` for details about this method. """ return self._coroutine.send(message)
[docs] def throw(self, exception): """Send the exception to the `component`. This method just passes the exception on to the internal `coroutine` defined in :meth:`_main`, returning any resulting `message` or raising the uncaught exception. .. seealso:: The :class:`~m4us.core.interfaces.ICoroutine` `interface` for details about this method. """ return self._coroutine.throw(exception)
[docs] def close(self): """Terminate the `component`. This method just calls :meth:`!close` on the `component`'s internal `coroutine` defined in :meth:`_main`. .. seealso:: The :class:`~m4us.core.interfaces.ICoroutine` `interface` for details about this method. """ self._coroutine.close() # [[start SampleComponent]]
@provider(ICoroutineFactory)
[docs]class SampleComponent(Component): """Component that passes all messages through.""" def _main(self): """Pass all messages through.""" inbox, message = (yield) while True: if is_shutdown(inbox, message): yield 'signal', message break ## Your code goes here. inbox, message = (yield 'outbox', message) # [[end SampleComponent]] # The docstring for SampleComponent is set like this so that it can include # it's own source code in the docs. The literalinclude directive won't # work completely correctly if the docstring is inline. Also note that # class docstrings cannot be changed after the class definition is # complete. __doc__ = """`Component` that passes all `messages` through. This `component` is meant to provide a canonical example of what a `component` used with this project looks like. Like :func:`~m4us.core.coroutines.sample_coroutine`, any `messages` sent to it on any `inbox` will be sent back out on it's ``outbox`` `outbox`. It is also well behaved in that it will shutdown on any :class:`~m4us.core.interfaces.IShutdown` `message`, forwarding it on before quitting. The full code for this `component` is: .. literalinclude:: ../../../../m4us/core/components.py :linenos: :start-after: # [[start SampleComponent]] :end-before: # [[end SampleComponent]] :implements: :class:`m4us.core.interfaces.ICoroutine` :provides: :class:`m4us.core.interfaces.ICoroutineFactory` .. seealso:: The :func:`~m4us.core.coroutines.sample_coroutine` `coroutine` for details on why the :meth:`!_main` method is written the way it is. """ #---Module initialization------------------------------------------------------ #---Late Imports--------------------------------------------------------------- #---Late Globals--------------------------------------------------------------- #---Late Functions------------------------------------------------------------- #---Late Classes--------------------------------------------------------------- #---Late Module initialization-------------------------------------------------