API Reference

PubMarine is a simple PubSub framework for Python3’s asyncio.

Authors: Toshio Kuratomi <toshio@fedoraproject.org

Exceptions

class pubmarine.PubMarineError

Base of all errors specific to PubMarine

class pubmarine.EventNotFoundError

Raised when an event is not handled by this PubPen

PubPen Context Object

class pubmarine.PubPen(loop: asyncio.events.AbstractEventLoop, event_list: List[str] = None)

A PubPen object coordinates subscription and publication.

Use PubPen.subscribe() to register callbacks to be invoked when an event is published.

Use PubPen.publish() to publish an event, invoking the callbacks.

Callbacks will be queued to be executed by the asyncio event loop that is passed into the PubPen when it is instantiated.

Note

Most programs should create one PubPen instance and then share it between all of the objects that wish to communicate with each other.

emit(event: str, *args, **kwargs) → None

Publish an event

Parameters:event – String name of an event to publish

Other args and keyword args are passed to the callback function.

Deprecated: Use publish() instead

publish(event: str, *args, **kwargs) → None

Publish an event

Parameters:event – String name of an event to publish

Other args and keyword args are passed to the callback function.

subscribe(event: str, callback: Union[Callable[[...], Any], method]) → int

Subscribe a callback to an event

Parameters:event – String name of an event to subscribe to Callback:The function to call when the event is published. This can be any python callable.

Use functools.partial() to call the callback with any other arguments.

Note

The callback is registered with the event each time this method is called. The callback is called each time it has been registered when the event is published. For example:

>>> import asyncio
>>> import pubmarine
>>> pubpen = pubmarine.PubPen(asyncio.get_event_loop)
>>> def message():
...     print('message called')
>>> pubpen.subscribe('test', message)
>>> pubpen.subscribe('test', message)
>>> pubpen.publish('test')
message called
message called

If the caller wants the callback to only be called once, it is the caller’s responsibility to only subscribe the callback once.

unsubscribe(sub_id: int) → None

Unsubscribe from an event.

Parameters:sub_id – The subscription id returned from subscribe.