API

asyncframes module

class asyncframes.all_(*awaitables)

Bases: asyncframes.Awaitable

An awaitable that blocks the awaiting frame until all passed awaitables have woken up.

Parameters:awaitables (Awaitable[]) – A list of all awaitables to await.
class asyncframes.animate(seconds, callback, interval=0.0)

Bases: asyncframes.Event

An awaitable event used for periodically calling a callback function for the specified amount of time.

Parameters:
  • seconds (float) – The duration of the animation.
  • callback (Callable[float, None]) – The function to be called on every iteration. The first parameter of callback indicates animation progress between 0 and 1.
  • interval (float, optional) – Defaults to 0.0. The minimum time in seconds between two consecutive calls of the callback.
class asyncframes.any_(*awaitables)

Bases: asyncframes.Awaitable

An awaitable that blocks the awaiting frame until any of the passed awaitables wakes up.

Parameters:awaitables (Awaitable[]) – A list of all awaitables to await.
class asyncframes.Awaitable(name, singleshot, lifebound)

Bases: collections.abc.Awaitable

An awaitable frame or event.

Every node in the frame hierarchy is a subclass of Awaitable. An awaitable has a __name__, a parent awaitable (None, if the awaitable is the main frame), a list of child awaitables and a result, that gets set when the awaitable finishes.

Parameters:name (str) – The name of the awaitable.
remove()

Remove this awaitable from the frame hierarchy.

Returns:An awaitable event.

The remove event returns True once the awaitable has been removed or False if the request was either canceled, or the awaitable had already been removed before.

Return type:Event
removed

Boolean property, indicating whether this awaitable has been removed from the frame hierarchy.

class asyncframes.AbstractEventLoop

Bases: object

Abstract base class of event loops.

postevent(eventsource, event, delay=0)
run(frame, *frameargs, num_threads=0, **framekwargs)
static sendevent(eventsource, event, process_counter=None, blocking=False)
class asyncframes.Event(name, singleshot=False, lifebound=False)

Bases: asyncframes.Awaitable

An awaitable event.

Instantiate or overload this class to implement new events. Each type of event should be emitted by exactly one event class. For example, key-up and key-down events should be implemented by two separate events. Events represent leave nodes in the frame hierarchy.

Parameters:
  • name (str) – The name of the event.
  • singleshot (bool, optional) – Defaults to False. If True, removes the event after it has been woken.
post(args=None, delay=0)

Enqueue an event in the event loop.

Parameters:
  • args (optional) – Defaults to None. Event arguments, for example, the progress value on a progress-update event.
  • delay (float, optional) – Defaults to 0. The time in seconds to wait before posting the event.
send(args=None)

Dispatch and immediately process an event.

Parameters:args (optional) – Defaults to None. Event arguments, for example, the progress value on a progress-update event.
asyncframes.find_parent(parenttype)

Find parent frame of given type.

Recursively search the frame hierarchy for the closest ancestor of the given type.

Parameters:parenttype (type) – The frame class type to search for.
Returns:The closest ancestor of type parenttype or None if none was found.
Return type:Frame
class asyncframes.Frame(startup_behaviour=<FrameStartupBehaviour.delayed: 1>, thread_idx=None)

Bases: asyncframes.Awaitable

An object within the frame hierarchy.

This class represents the default frame class. All other frame classes have to be derived from Frame.

A frame is an instance of a frame class. Use the nested Factory class to create frames.

The factory class is created by decorating a function or coroutine with @FRAME, where FRAME is the frame class.

Example:

class MyFrameClass(Frame):
    pass

@MyFrameClass
async def my_frame_factory():
    pass

assert(type(my_frame_factory) == MyFrameClass.Factory)
my_frame = my_frame_factory()
assert(type(my_frame) == MyFrameClass)
Parameters:
  • startup_behaviour (FrameStartupBehaviour, optional) – Defaults to FrameStartupBehaviour.delayed. Controls whether the frame is started immediately or queued on the eventloop.
  • thread_idx (int, optional) – Defaults to None. If set, forces the scheduler to affiliate this frame with the given thread.
free

Event – An event that fires just before the frame is removed.

ready

Event – An event that fires the first time the frame is suspended (using await) or goes out of scope.

Raises:

ValueError – If thread_idx is outside the range of allocated threads.

The number of allocated threads is controlled by the num_threads parameter of AbstractEventLoop.run().

class Factory(framefunc, frameclassargs, frameclasskwargs)

Bases: object

A frame function declared in the context of a frame class.

Parameters:
  • framefunc (Callable) – The function or coroutine that describes the frame’s behaviour.
  • frameclassargs (tuple) – Positional arguments to the frame class.
  • frameclasskwargs (dict) – Keyword arguments to the frame class.
frameclass

alias of Frame

create(framefunc, *frameargs, **framekwargs)

Start the frame function with the given arguments.

Parameters:framefunc (function) – A coroutine or regular function controlling the behaviour of this frame. If framefunc is a coroutine, then the frame only exists until the coroutine exits.
class asyncframes.FrameMeta

Bases: abc.ABCMeta

class asyncframes.FrameStartupBehaviour

Bases: enum.Enum

An enumeration.

delayed = 1
immediate = 2
class asyncframes.FreeEventArgs

Bases: object

Event arguments returned by the Frame.free event.

cancel

bool – Setting this to True, cancels the event.

asyncframes.get_current_eventloop_index()

Get the thread index of the currently active event loop.

Returns:The thread index of the current event loop or None if no event loop is currently active.
Return type:int
exception asyncframes.InvalidOperationException(msg)

Bases: Exception

Raised when operations are performed out of context.

Parameters:msg (str) – Human readable string describing the exception.
class asyncframes.hold

Bases: asyncframes.Event

An awaitable event used for suspending execution indefinitely.

Frames are automatically removed when the frame coroutine finishes. If you would like the frame to remain open until it is removed, write await hold() at the end of the coroutine.

class asyncframes.PFrame(startup_behaviour=<FrameStartupBehaviour.delayed: 1>, thread_idx=None)

Bases: asyncframes.Frame

A parallel Frame that can run on any thread.

Multithreading can be enabled for any frame by changing its base class to PFrame.

The only difference between Frame and PFrame is that instances of PFrame are not restricted to run on the same thread as their parent frame.

Parameters:
  • startup_behaviour (FrameStartupBehaviour, optional) – Defaults to FrameStartupBehaviour.delayed. Controls whether the frame is started immediately or queued on the eventloop.
  • thread_idx (int, optional) – Defaults to None. If set, forces the scheduler to affiliate this frame with the given thread.
Raises:

ValueError – If thread_idx is outside the range of allocated threads.

The number of allocated threads is controlled by the num_threads parameter of AbstractEventLoop.run().

Factory

alias of PFrame.Factory

class asyncframes.Primitive(owner)

Bases: object

An object owned by a frame of the specified frame class.

A primitive has to be created within the frame function of its owner or within the frame function of any child frame of its owning frame class. If it is created within a child frame, it will still be registered with the closest parent of the owning frame class.

Parameters:

owner (class) – The owning frame class.

Raises:
  • TypeError – Raised if owner is not a frame class.
  • Exception – Raised if a primitive is created outside the frame function of its owning frame class.
remove()

Remove this primitive from its owner.

Returns:If True, this event was removed. If False the request was either canceled, or the event had already been removed before
Return type:bool
class asyncframes.sleep(seconds=0.0)

Bases: asyncframes.Event

An awaitable event used for suspending execution by the specified amount of time.

A duration of 0 seconds will resume the awaiting frame as soon as possible. This is useful to implement non-blocking loops.

Parameters:seconds (float, optional) – Defaults to 0. The duration to wait.

asyncframes.asyncio_eventloop module

class asyncframes.asyncio_eventloop.EventLoop

Bases: asyncframes.AbstractEventLoop

An implementation of AbstractEventLoop based on asyncio.

asyncframes.glib_eventloop module

asyncframes.pyqt5_eventloop module