salmon.routing module

The meat of Salmon, doing all the work that actually takes an email and makes sure that your code gets it.

The three most important parts for a programmer are the Router variable, the StateStorage base class, and the @route, @route_like, and @stateless decorators.

The salmon.routing.Router variable (it’s not a class, just named like one) is how the whole system gets to the Router. It is an instance of RoutingBase and there’s usually only one.

The salmon.routing.StateStorage is what you need to implement if you want Salmon to store the state in a different way. By default the salmon.routing.Router object just uses a default MemoryStorage to do its job. If you want to use a custom storage, then in your boot modiule you would set salmon.routing.Router.STATE_STORE to what you want to use.

Finally, when you write a state handler, it has functions that act as state functions for dealing with each state. To tell the Router what function should handle what email you use a @route decorator. To tell the Route that one function routes the same as another use @route_like. In the case where a state function should run on every matching email, just use the @stateless decorator after a @route or @route_like.

If at any time you need to debug your routing setup just use the salmon routes command.

Routing Control

To control routing there are a set of decorators that you apply to your functions.

  • @route – The main routing function that determines what addresses you are interested in.

  • @route_like – Says that this function routes like another one.

  • @stateless – Indicates this function always runs on each route encountered, and no state is maintained.

  • @nolocking – Use this if you want this handler to run parallel without any locking around Salmon internals. SUPER DANGEROUS, add @stateless as well.

  • @state_key_generator – Used on a function that knows how to make your state keys for the module, for example if module_name + message.To is needed to maintain state.

It’s best to put @route or @route_like as the first decorator, then the others after that.

The @state_key_generator is different since it’s not intended to go on a handler but instead on a simple function, so it shouldn’t be combined with the others.

salmon.routing.DEFAULT_STATE_KEY(mod, msg)[source]
class salmon.routing.MemoryStorage[source]

Bases: salmon.routing.StateStorage

The default simplified storage for the Router to hold the states. This should only be used in testing, as you’ll lose all your contacts and their states if your server shuts down. It is also horribly NOT thread safe.

clear()[source]

This should clear ALL states, it is only used in unit testing, so you can have it raise an exception if you want to make this safer.

get(key, sender)[source]

You must implement this so that it returns a single string of either the state for this combination of arguments, OR the ROUTE_FIRST_STATE setting.

key(key, sender)[source]
set(key, sender, state)[source]

Set should take the given parameters and consistently set the state for that combination such that when StateStorage.get is called it gives back the same setting.

class salmon.routing.RoutingBase[source]

Bases: object

The self is a globally accessible class that is actually more like a glorified module. It is used mostly internally by the salmon.routing decorators (route, route_like, stateless) to control the routing mechanism.

It keeps track of the registered routes, their attached functions, the order that these routes should be evaluated, any default routing captures, and uses the MemoryStorage by default to keep track of the states.

You can change the storage to another implementation by simple setting:

Router.STATE_STORE = OtherStorage()

in your settings module.

RoutingBase does locking on every write to its internal data (which usually only happens during booting and reloading while debugging), and when each handler’s state function is called. ALL threads will go through this lock, but only as each state is run, so you won’t have a situation where the chain of state functions will block all the others. This means that while your handler runs nothing will be running, but you have not guarantees about the order of each state function.

However, this can kill the performance of some kinds of state functions, so if you find the need to not have locking, then use the @nolocking decorator and the Router will NOT lock when that function is called. That means while your @nolocking state function is running at least one other thread (more if the next ones happen to be @nolocking) could also be running.

It’s your job to keep things straight if you do that.

NOTE: See @state_key_generator for a way to change what the key is to STATE_STORE for different state control options.

call_safely(func, message, kwargs)[source]

Used by self to call a function and log exceptions rather than explode and crash.

clear_routes()[source]

Clears out the routes for unit testing and reloading.

clear_states()[source]

Clears out the states for unit testing.

defaults(**captures)[source]

Updates the defaults for routing captures with the given settings.

You use this in your handlers or your settings module to set common regular expressions you’ll have in your @route decorators. This saves you typing, but also makes it easy to reconfigure later.

For example, many times you’ll have a single host=”…” regex for all your application’s routes. Put this in your settings.py file using route_defaults={‘host’: ‘…’} and you’re done.

deliver(message)[source]

The meat of the whole Salmon operation, this method takes all the arguments given, and then goes through the routing listing to figure out which state handlers should get the gear. The routing operates on a simple set of rules:

1) Match on all functions that match the given To in their registered format pattern. 2) Call all @stateless state handlers functions. 3) Call the first method that’s in the right state for the From/To.

It will log which handlers are being run, and you can use the ‘salmon route’ command to inspect and debug routing problems.

If you have an ERROR state function, then when your state blows up, it will transition to ERROR state and call your function right away. It will then stay in the ERROR state unless you return a different one.

get_state(module_name, message)[source]

Returns the state that this module is in for the given message (using its from).

in_error(func, message)[source]

Determines if the this function is in the ‘ERROR’ state, which is a special state that self puts handlers in that throw an exception.

in_state(func, message)[source]

Determines if this function is in the state for the to/from in the message. Doesn’t apply to @stateless state handlers.

load(handlers)[source]

Loads the listed handlers making them available for processing. This is safe to call multiple times and to duplicate handlers listed.

match(address)[source]

This is a generator that goes through all the routes and yields each match it finds. It expects you to give it a blah@blah.com address, NOT “Joe Blow” <blah@blah.com>.

register_route(format, func)[source]

Registers this function func into the routes mapping based on the format given. Format should be a regex string ready to be handed to re.compile.

reload()[source]

Performs a reload of all the handlers and clears out all routes, but doesn’t touch the internal state.

set_state(module_name, message, state)[source]

Sets the state of the given module (a string) according to the message to the requested state (a string). This is also how you can force another FSM to a required state.

state_key(module_name, message)[source]

Given a module_name we need to get a state key for, and a message that has information to make the key, this function calls any registered @state_key_generator and returns that as the key. If none is given then it just returns module_name as the key.

class salmon.routing.ShelveStorage(database_path)[source]

Bases: salmon.routing.MemoryStorage

Uses Python’s shelve to store the state of the Routers to disk rather than in memory like with MemoryStorage. This will get you going on a small install if you need to persist your states (most likely), but if you have a database, you’ll need to write your own StateStorage that uses your ORM or database to store. Consider this an example.

NOTE: Because of shelve limitations you can only use ASCII encoded keys.

Database path depends on the backing library use by Python’s shelve.

clear()[source]

Primarily used in the debugging/unit testing process to make sure the states are clear. In production this could be a bad thing.

get(key, sender)[source]

This will lock the internal thread lock, and then retrieve from the shelf whatever key you request. If the key is not found then it will set (atomically) to ROUTE_FIRST_STATE.

set(key, sender, state)[source]

Acquires the self.lock and then sets the requested state in the shelf.

class salmon.routing.StateStorage[source]

Bases: object

The base storage class you need to implement for a custom storage system.

clear()[source]

This should clear ALL states, it is only used in unit testing, so you can have it raise an exception if you want to make this safer.

get(key, sender)[source]

You must implement this so that it returns a single string of either the state for this combination of arguments, OR the ROUTE_FIRST_STATE setting.

set(key, sender, state)[source]

Set should take the given parameters and consistently set the state for that combination such that when StateStorage.get is called it gives back the same setting.

salmon.routing.assert_salmon_settings(func)[source]

Used to make sure that the func has been setup by a routing decorator.

salmon.routing.attach_salmon_settings(func)[source]

Use this to setup the _salmon_settings if they aren’t already there.

salmon.routing.has_salmon_settings(func)[source]
salmon.routing.nolocking(func)[source]

Normally salmon.routing.Router has a lock around each call to all handlers to prevent them from stepping on each other. It’s assumed that 95% of the time this is what you want, so it’s the default. You probably want everything to go in order and not step on other things going off from other threads in the system.

However, sometimes you know better what you are doing and this is where @nolocking comes in. Put this decorator on your state functions that you don’t care about threading issues or that you have found a need to manually tune, and it will run it without any locks.

class salmon.routing.route(format, **captures)[source]

Bases: object

The @route decorator is attached to state handlers to configure them in the Router so they handle messages for them. The way this works is, rather than just routing working on only messages being sent to a state handler, it also uses the state of the sender. It’s like having routing in a web application use both the URL and an internal state setting to determine which method to run.

However, if you’d rather than this state handler process all messages matching the @route then tag it @stateless. This will run the handler no matter what and not change the user’s state.

Sets up the pattern used for the Router configuration. The format parameter is a simple pattern of words, captures, and anything you want to ignore. The captures parameter is a mapping of the words in the format to regex that get put into the format. When the pattern is matched, the captures are handed to your state handler as keyword arguments.

For example, if you have:

@route("(list_name)-(action)@(host)",
    list_name='[a-z]+',
    action='[a-z]+', host='test\.com')
def STATE(message, list_name=None, action=None, host=None):
    pass

Then this will be translated so that list_name is replaced with [a-z]+, action with [a-z]+, and host with ‘test.com’ to produce a regex with the right format and named captures to that your state handler is called with the proper keyword parameters.

You should also use the Router.defaults() to set default things like the host so that you are not putting it into your code.

parse_format(format, captures)[source]

Does the grunt work of conversion format+captures into the regex.

setup_accounting(func)[source]

Sets up an accounting map attached to the func for routing decorators.

class salmon.routing.route_like(func)[source]

Bases: salmon.routing.route

Many times you want your state handler to just accept mail like another handler. Use this, passing in the other function. It even works across modules.

Sets up the pattern used for the Router configuration. The format parameter is a simple pattern of words, captures, and anything you want to ignore. The captures parameter is a mapping of the words in the format to regex that get put into the format. When the pattern is matched, the captures are handed to your state handler as keyword arguments.

For example, if you have:

@route("(list_name)-(action)@(host)",
    list_name='[a-z]+',
    action='[a-z]+', host='test\.com')
def STATE(message, list_name=None, action=None, host=None):
    pass

Then this will be translated so that list_name is replaced with [a-z]+, action with [a-z]+, and host with ‘test.com’ to produce a regex with the right format and named captures to that your state handler is called with the proper keyword parameters.

You should also use the Router.defaults() to set default things like the host so that you are not putting it into your code.

salmon.routing.salmon_setting(func, key)[source]

Simple way to get the salmon setting off the function, or None.

salmon.routing.state_key_generator(func)[source]

Used to indicate that a function in your handlers should be used to determine what they key is for state storage. It should be a function that takes the module_name and message being worked on and returns a string.

salmon.routing.stateless(func)[source]

This simple decorator is attached to a handler to indicate to the Router.deliver() method that it does NOT maintain state or care about it. This is how you create a handler that processes all messages matching the given format+captures in a @route.

Another way to think about a @stateless handler is that it is a pass-through handler that does its processing and then passes the results on to others.

Stateless handlers are NOT guaranteed to run before the handler with state.