Welcome to slp_coroutine’s documentation!

Adapt normal functions, methods and other callables to asyncio using Stackless Python

Requires Stackless Python >= 3.7.6

This module provides adapters and decorators to use “normal” Python code to write tasks of an asyncio-application. This way many libraries, which do not support asyncio can be used with this framework.

In Python the difference between a normal function and a coroutine function is, that the coroutine function needs a controller, which executes the coroutine step by step, whereas the normal function executes in a single non-interruptible pass. If the coroutine needs to wait for an event (i.e. data input), its controller can run other code, until the event happens. A normal function usually has no choice but to block.

With Stackless Python it is possible to execute multiple functions in parallel on a single thread. Each execution context is called a tasklet. If a function has to wait for an event, it can - instead of blocking - switch the execution to another tasklet. This switching capability makes it possible to invoke a normal callable from a coroutine and to await coroutines from within the normal callable. This technique can be extended to (asynchronous) generators and decorators.

slp_coroutine.as_coroutinefunction(callable_)

Create a coroutine function from a normal callable.

This function is a decorator that can be used to define a coroutine function from any normal function, method or other callable.

Parameters

callable (Callable) – the callable to be decorated

Returns

a coroutine function

slp_coroutine.async_generator(generator)

Create an asynchronous generator iterator, that iterates over generator

This generator-function creates a asynchronous generator iterator, that iterates over the given generator or iterator.

Parameters

generator – a generator or iterator object

Returns

an asynchronous generator iterator

slp_coroutine.await_coroutine(coroutine)

await a coroutine

A normal function (or method or other callable) may use this function to await an awaitable object, if the function has been directly or indirectly called by new_generator_coroutine().

Parameters

coroutine (Coroutine or Generator) – the coroutine to be awaited

Returns

the value returned by coroutine

Raises

RuntimeError – if called from outside of new_generator_coroutine().

slp_coroutine.generator(asyncgen)

Create a generator-iterator, that iterates over asyncgen

This generator-function creates a generator-iterator, that iterates over the given asynchronous iterable.

The returned generator-iterator must be called from code, that is executed by new_generator_coroutine().

Parameters

asyncgen – an asynchronous iterable object

Returns

a generator iterator

Raises

RuntimeError – the generator raises RuntimeError, if called from outside of new_generator_coroutine().

slp_coroutine.new_coroutine(callable_, *args, **kwargs)

Run any Python callable as coroutine.

Same as new_generator_coroutine(), but return a coroutine created by a async def coroutine function.

slp_coroutine.new_generator_coroutine(callable_, *args, **kwargs)

Run any Python callable as generator-based coroutine.

The coroutine-function new_generator_coroutine() returns a new coroutine, that executes callable_ in a new tasklet. callable_ may await other coroutines or switch tasklets. Details:

  • If the tasklet yields (i.e. calls stackless.schedule()) the generator-coroutine returned by new_generator_coroutine() yields tasklet.tempval.

  • If the tasklet awaits another coroutine (calls await_coroutine()), the generator-coroutine returned by new_generator_coroutine() controls the awaited coroutine.

  • If you send a value or an exception to the generator-coroutine returned by new_generator_coroutine(), it passes the value or exception to the tasklet or, if the tasklet is awaiting a coroutine, to the currently awaited coroutine.

  • The returned coroutine returns the return value of callable(*args, **kwargs).

  • The returned coroutine is generator based. See types.coroutine().

Parameters

  • callable (Callable) – the callable to be executed

  • args – positional arguments for callable_

  • kwargs – keyword arguments for callable_

Returns

a generator-based coroutine that executes callable(*args, **kwargs)

class slp_coroutine.contextmanager(async_contextmanager)

A context manager, that delegates to an asynchronous context manager.

This with statement context manager delegates to an asynchronous context manager to actually manage the context.

Parameters

async_contextmanager – the asynchronous context manager to delegate to

class slp_coroutine.asynccontextmanager(contextmanager)

An asynchronous context manager, that delegates to a with statement context manager.

This asynchronous context manager delegates to a synchronous with statement context manager to actually manage the context.

Parameters

contextmanager – the context manager to delegate to

Indices and tables