gidgethub.routing — A router for webhook events

New in version 2.3.

When a single web service is used to perform multiple actions based on a single webhook event, it is easier to do those multiple steps in some sort of routing mechanism to make sure the right objects are called is provided. This module is meant to provide such a router for gidgethub.sansio.Event instances. This allows for individual async functions to be written per event type to help keep logic separated and focused instead of having to differentiate between different events manually in user code.

class gidgethub.routing.Router(*other_routers)

An object to route a gidgethub.sansio.Event instance to appropriate registered asynchronous callbacks.

The initializer for this class takes an arbitrary number of other routers to help build a single router from sub-routers. Typically this is used when each semantic set of features has a router and are then used to construct a server-wide router.

Each callback registered with this class is expected to be awaitable and to accept at least a single Event instance:

async def callback(event, *args, **kwargs):
    ...
add(func, event_type, **data_detail)

Add an asynchronous callback for an event.

The event_type argument corresponds to the gidgethub.sansio.Event.event attribute of the event that the callback is interested in. The arbitrary keyword arguments is used as a key/value pair to compare against what is provided in gidgethub.sansio.Event.data. Only 0 or 1 keyword-only arguments may be provided, otherwise TypeError is raised.

For example, to register a callback for any opened issues, you would call:

async def callback(event):
    ...

router.add(callback, "issues", action="opened")
@register(event_type, **data_detail)

A decorator that calls add() on the decorated function.

router = gidgethub.routing.Router()

@router.register("issues", action="opened")
async def callback(event):
    ...
fetch(event)

Return a frozenset of asynchronous callbacks registered to the router that the event would be called on. The event argument corresponds to gidgethub.sansio.Event.

New in version 5.0.0.

async dispatch(event, *args, **kwargs)

Call the appropriate asynchronous callbacks for the event. The provided event and any other arguments will be passed down to the callback unmodified.

Changed in version 2.4: Added *args and **kwargs.

Changed in version 5.0.0: Execution order is non-deterministic.