Welcome to Adsorption’s documentation!

Introduction

Adsorption is a lightweight loose coupling library for Python. It has no dependencies and can be used with any sort of framework for loose coupling of components within an application. It was written with web applications in mind, but makes no assumptions about where or how it will be used.

Usage

Start with declaring a container for your events. This should ideally be a singleton for your entire application, so declare it somewhere that it can be imported from across your app:

>>> from adsorb import Adsorber
>>> events = Adsorber()

Declare a listener for an event. Events in Adsorption do not need to be declared. They exist as long as they have at least one caller or listener:

>>> @events.listener('event1')
... def listener(event):
...     print 'Listener received context', repr(event.context)
...     return "processed"

>>> @events.listener('event1')
... def listener2(event):
...     return "also-processed"

Raise an event from anywhere. Event listeners are called and all responses are collected before execution resumes with the caller. The order in which listeners are called is not defined. Listeners are not expected to be order-aware:

>>> e = events.raiseEvent('event1', 'some-context')
Listener received context 'some-context'
>>> sorted(e.results.items())
[('__main__.listener', 'processed'), ('__main__.listener2', 'also-processed')]

If a listener raises an exception, the exception is captured in Event.exceptions. Future versions may add support to call listeners in parallel threads.

API Documentation

Package adsorb

class adsorb.adsorb.Adsorber[source]

Container for events and listeners. Typically used as a singleton instance for the entire application.

addListener(eventname, listenerid, listener)[source]

Add a listener to the named event. Listeners are passed an instance of Event as the sole parameter. The return value from the listener is collected in the event object’s results attribute.

listener(eventname)[source]

Decorator for event listeners to automate the call to addListener(). Usage:

@adsorb_instance.listener("event-name")
def your_listener(event):
    ...
    
@adsorb_instance.listener(("event1", event2")):
def your_listener(event):
    ...

A listenerid for the listener is automatically constructed from the module and function names. This decorator can only be used with module top-level functions. For class methods and nested functions, call addListener() at run-time.

raiseEvent(eventname, context, **kw)[source]

Raise an event. All listeners are called and their return values or exceptions are collected before execution resumes with the caller. Caller must provide a mandatory context and optional named attributes as data for the event.

removeEvent(eventname, confirm=False)[source]

Remove all listeners on an event.

removeListener(eventname, listenerid)[source]

Remove a listener on an event.

class adsorb.adsorb.Event(adsorber, name, context, **kw)[source]

Collects responses to the event. Attributes:

  • name: Name of the event
  • context: Context for event, provided by caller
  • data: Additional data provided by caller
  • results: Dictionary of results from each listener
  • exceptions: Dictionary of (exception, value) from failed listeners

Event objects are automatically created by Adsorber.raiseEvent() and passed as the sole parameter to each listener.

call()[source]

Call all listeners for this event and collect their output.

Table Of Contents

This Page