m4us.core.coroutines

Provides support for using regular Python coroutines.

Members

coroutine(lazy=True)

Decorator factory to automatically activate Python coroutines.

Before a Python coroutine can be used, it needs to be activated by sending None as it's first message. This decorator does this automatically.

Coroutines are presumptively lazy. This decorator can flag the given coroutine as not lazy by making it adaptable to the INotLazy marker interface.

This decorator also registers the function as providing ICoroutineFactory and registers all interfaces implemented by the function as being provided by the coroutine that the function returns.

Parameters:lazy (bool) -- Specifies whether or not the coroutine is lazy. Returns:A wrapper function that will activate and return the coroutine when called. Return type:types.FunctionType

Warning

When using this decorator with the zope.interface.implementer and/or zope.interface.provider decorators, make sure this decorator is the outer-most one. Otherwise interface declarations will get lost.

filter_(function)

Decorator to turn an ordinary function into a proper coroutine.

This decorator returns a factory function that when called, just calls filter_from_callable() and returns the result.

Any additional arguments passed the to factory function are passed on to filter_from_callable().

The factory function is also registered as providing ICoroutineFactory.

Parameters:

function (types.FunctionType) -- The function to turn into a coroutine. It must accept at least one argument.

Returns:

A filter coroutine factory function.

Return type:

m4us.core.interfaces.ICoroutineFactory

Raises:

• exceptions.TypeError -- If the given function is not a function.
• exceptions.ValueError -- If the given function does not accept at least one positional argument.

Seealso :

filter_from_callable() for the specifics.

filter_from_callable(callable_, *args, **kwargs)

Turn an ordinary callable (function, etc.) into a proper coroutine.

This is a convenience coroutine that turns ordinary callables (functions, etc.) into proper coroutines. The callable is passed inbox messages and it's return value is emited on outbox.

The given callable must accept at least a single positional argument, the incomming inbox message, and return whatever should be the outbox message to emit. Any additional arguments passed to this function will be passed to the callable each time it is called.

Any control or non-inbox messages sent in will be ignored and not passed to the callable. Additionally, by default, if the callable returns None, the None will be emitted on outbox as the message. This behaviour can be changed by passing suppress_none=True as a keyword argument. When suppress_none is True, if the callable returns None, only a plain None will be yielded. This means that no message will be passed on to any other coroutine. Non-None messages will still be emitted on the outbox outbox, however.

Parameters:

• callable_ (collections.Callable) -- The callable to which to pass messages.
• suppress_none (bool) -- Indicate whether or not None should be emitted on the outbox outbox. (Default: True)
• args (collections.Sequence) -- Any additional positional arguments to pass to the callable.
• kwargs (collections.Mapping) -- Any additional keyword arguments to pass to the callable.

Returns:

A filter coroutine

Return type:

types.GeneratorType

Raises exceptions.TypeError:  

If the given callable is not actually a callable.

Implements :

m4us.core.interfaces.ICoroutine

Provides :

m4us.core.interfaces.ICoroutineFactory

init()

Initialize coroutine interface support.

This function must be called before any other part of m4us is used. It sets up global interface and adapter registrations neccessary for the proper functioning of m4us. It has been made an explicit function in order to avoid import-time side-effects, which is considered bad practice.

It is recommended that this function be called either at import time or as the first call in a program's main function.

null_sink()

Swallow all messages except IShutdown.

This coroutine can serve as an end point in a series of connected coroutines. All messages sent to it, except IShutdown messages are ignored and not re-emitted.

The coroutine will shutdown on any IShutdown message, forwarding it on before quitting.

Returns:A null sink coroutine Return type:types.GeneratorType Implements :m4us.core.interfaces.ICoroutine Provides :m4us.core.interfaces.ICoroutineFactory

producer(generator_factory)

Decorator that turns a generator function into a producer coroutine.

This decorator returns a factory function that when called, just calls the generator function and passes the result to producer_from_iterable(), returning the result.

Any additional arguments passed the to factory function are passed on to to the generator factory.

The factory function is also registered as providing ICoroutineFactory.

Parameters:generator_factory (types.FunctionType) -- The generator function to turn into a producer. Returns:A producer coroutine factory function. Return type:m4us.core.interfaces.ICoroutineFactory Raises exceptions.TypeError:  If the given generator factory is not a callable.

Note

Technically this decorator will work with any function that returns an iterable. A generator function is not strictly required, though that is the expected typical use case.

Seealso :producer_from_iterable() for the specifics.

producer_from_iterable(iterable)

Return a producer coroutine that iterates over an iterable.

This is a convenience coroutine that emits outbox messages that are the results of iterating over an iterable. When all the iterable results have been emitted, an IProducerFinished messages is emitted. Then the producer terminates.

Parameters:iterable (collections.Iterable) -- The iterable object over which to iterate. Returns:A non-lazy producer coroutine Return type:types.GeneratorType Raises exceptions.TypeError:  If the given object is not an iterable or it does not produce a valid iterator. Implements :m4us.core.interfaces.ICoroutine Provides :m4us.core.interfaces.ICoroutineFactory

sample_coroutine()

Pass all messages through.

This coroutine is meant to provide a canonical example of what a coroutine used with this project looks like.

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 IShutdown message, forwarding it on before quitting.

The full code for this coroutine is:

@coroutine()
def sample_coroutine():
    """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)

Returns:A pass-through coroutine Return type:types.GeneratorType Implements :m4us.core.interfaces.ICoroutine Provides :m4us.core.interfaces.ICoroutineFactory

Note

Producers and filters need a minimum of 2 yield statements as the output of the first one is always thrown away. The output of the second one is the first message delivered. On the other hand, the first yield will be the one that gets the first incoming message.

sink(function)

Decorator to turn an ordinary function into a sink coroutine.

This decorator returns a factory function that when called, just calls sink_from_callable() and returns the result.

Any additional arguments passed the to factory function are passed on to sink_from_callable().

The factory function is also registered as providing ICoroutineFactory.

Parameters:

function (types.FunctionType) -- The function to turn into a sink coroutine. It must accept at least one argument.

Returns:

A sink coroutine factory function.

Return type:

m4us.core.interfaces.ICoroutineFactory

Raises:

• exceptions.TypeError -- If the given function is not a function.
• exceptions.ValueError -- If the given function does not accept at least one positional argument.

See also

sink_from_callable() for the specifics.

sink_from_callable(callable_, *args, **kwargs)

Turn an ordinary callable (function, etc.) into a sink coroutine.

This is a convenience function that turns ordinary callables (functions, etc.) into sink coroutines. The callable is passed inbox messages and it's return value suppressed, unless it is an IShutdown message.

The given callable must accept at least a single positional argument, the incomming inbox message, and return nothing. It may return an IShutdown message, however, if appropriate, but it should not normally be necessary. Any additional arguments passed to this function will be passed to the callable each time it is called.

Any control or non-inbox messages sent in will be ignored and not passed to the callable.

Parameters:

• callable_ (collections.Callable) -- The callable to which to pass messages.
• args (collections.Sequence) -- Any additional positional arguments to pass to the callable.
• kwargs (collections.Mapping) -- Any additional keyword arguments to pass to the callable.

Returns:

A sink coroutine

Return type:

types.GeneratorType

Raises exceptions.TypeError:  

If the given callable is not actually a callable.

Implements :

m4us.core.interfaces.ICoroutine

Provides :

m4us.core.interfaces.ICoroutineFactory