m4us.core.coroutines — Message For You Sir! v0.2.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Message For You Sir! v0.2.1 documentation »
- API Documentation »

# `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: | `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 (`FunctionType`) -- The function to turn into a coroutine. It must accept at least one argument.
  Returns: | A filter coroutine factory function.
  Return type: | `ICoroutineFactory`
  Raises: | TypeError -- If the given function is not a function. 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_ (Any callable object) -- 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 -- Any additional positional arguments to pass to the callable. **kwargs -- Any additional keyword arguments to pass to the callable.
  Returns: | A filter coroutine
  Return type: | `GeneratorType`
  Raises TypeError:
  | If the given callable is not actually a callable.
  Implements : | `ICoroutine`
  Provides : | `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: | `GeneratorType`
  Implements : | `ICoroutine`
  Provides : | `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 -- The generator function to turn into a producer.
  Returns: | A producer coroutine factory function.
  Return type: | `ICoroutineFactory`
  Raises 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 (Any iterable) -- The iterable object over which to iterate.
  Returns: | A non-lazy producer coroutine
  Return type: | `GeneratorType`
  Raises TypeError:
  | If the given object is not an iterable or it does not produce a valid iterator.
  Implements : | `ICoroutine`
  Provides : | `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:

       1
       2
       3
       4
       5
       6
       7
       8
       9
      10
      @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: | `GeneratorType`
  Implements : | `ICoroutine`
  Provides : | `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 (`FunctionType`) -- The function to turn into a sink coroutine. It must accept at least one argument.
  Returns: | A sink coroutine factory function.
  Return type: | `ICoroutineFactory`
  Raises: | TypeError -- If the given function is not a function. ValueError -- If the given function does not accept at least one positional argument.
  Seealso : | `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_ (Any callable object) -- The callable to which to pass messages. *args -- Any additional positional arguments to pass to the callable. **kwargs -- Any additional keyword arguments to pass to the callable.
  Returns: | A sink coroutine
  Return type: | `GeneratorType`
  Raises TypeError:
  | If the given callable is not actually a callable.
  Implements : | `ICoroutine`
  Provides : | `ICoroutineFactory`

### Navigation

- index
- modules |
- next |
- previous |
- Message For You Sir! v0.2.1 documentation »
- API Documentation »