BlockingRouter

Added in version 0.10.0.

The BlockingRouter is the most basic and easy to use router included with RapidSMS. For this reason it is also the default router. As its name suggests, BlockingRouter handles messages synchronously (within the main HTTP thread), waiting for application and backend processing to complete before continuing. This is acceptable for many scenarios, but will be less efficient if your project needs to handle many inbound and outbound messages.

Installation

Set RAPIDSMS_ROUTER to use BlockingRouter:

RAPIDSMS_ROUTER = "rapidsms.router.blocking.BlockingRouter"

That’s it!

How it works

By default, BlockingRouter automatically adds apps and backends defined in your settings file via INSTALLED_APPS and INSTALLED_BACKENDS. If you instantiate a BlockingRouter, you can see the available apps and backends:

>>> from rapidsms.router.blocking import BlockingRouter
>>> router = BlockingRouter()
>>> router.apps
[<app: handlers>, <app: default>, <app: messagelog>]
>>> router.backends
{'message_tester': <backend: message_tester>}

In this scenario, these settings were used:

INSTALLED_APPS = [
    # trimmed to only show the relevant apps
    "rapidsms.contrib.handlers",
    "rapidsms.contrib.default",
    "rapidsms.contrib.messagelog",
]

INSTALLED_BACKENDS = {
    "message_tester": {
        "ENGINE": "rapidsms.contrib.httptester.backend.HttpTesterCacheBackend",
    },
}

Implementation

BlockingRouter is the default router, but it is also the base router for all RapidSMS routers. CeleryRouter and DatabaseRouter extend BlockingRouter and override necessary functionality. A subset of its methods are outlined below:

class rapidsms.router.blocking.BlockingRouter(*args, **kwargs)

Base RapidSMS router implementation.

add_app(module_name)

Add RapidSMS app to router. Installed apps will be notified of incoming and outgoing messages. If module_name is a Django app, the method looks in app_name.app for an AppBase subclass to use.

Parameters:

module_name – AppBase object or dotted path to RapidSMS app.

Returns:

AppBase object if found, otherwise None.

add_backend(name, module_name, config=None)

Add RapidSMS backend to router. Installed backends will be used to send outgoing messages.

Parameters:

• name – Name of backend.

• module_name – BackendBase object or dotted path to backend class.

Returns:

BackendBase object if found, otherwise a ValueError exception will be raised.

get_app(module_name)

Access installed app by name.

Parameters:

module_name – Dotted path to RapidSMS app.

Returns:

AppBase object if found, otherwise None.

incoming_phases = ('filter', 'parse', 'handle', 'default', 'cleanup')

Incoming router phases processed in the order in which they’re defined.

new_incoming_message(text, connections, class_=<class 'rapidsms.messages.incoming.IncomingMessage'>, **kwargs)

Create and return a new incoming message. Called by send. Overridable by child-routers.

Parameters:

• text – Message text

• connections – List or QuerySet of Connection objects

• class – Message class to instantiate

Returns:

IncomingMessage object.

new_outgoing_message(text, connections, class_=<class 'rapidsms.messages.outgoing.OutgoingMessage'>, **kwargs)

Create and return a new outgoing message. Called by receive. Overridable by child-routers.

Parameters:

• text – Message text

• connections – List or QuerySet of Connection objects

• class – Message class to instantiate

Returns:

OutgoingMessage object.

outgoing_phases = ('outgoing',)

Outgoing router phases processed in the order in which they’re defined.

receive_incoming(msg)

All inbound messages will be routed through receive_incoming by send. receive_incoming is typically overridden in child routers to customize incoming message handling.

Parameters:

msg – IncomingMessage object

send_outgoing(msg)

All outbound messages will be routed through send_outgoing by receive. send_outgoing is typically overridden in child routers to customize outgoing message handling.

Parameters:

msg – OutgoingMessage object

class rapidsms.router.blocking.router.BlockingRouter

is the full name for rapidsms.router.blocking.BlockingRouter.