Home       Trees       Indices       Help   
Lamson Mail Server
Package lamson :: Module routing :: Class RoutingBase
[hide private]
[frames] | no frames]

Class RoutingBase

source code


The self is a globally accessible class that is actually more like a
glorified module.  It is used mostly internally by the lamson.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:

    self.STATE_STORE = OtherStorage()

In a config/settings.py file.

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.
Instance Methods [hide private]
 
__init__(self)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature		 source code
 
register_route(self, format, func)
Registers this function func into the routes mapping based on the format given.		 source code
 
match(self, address)
This is a generator that goes through all the routes and yields each match it finds.		 source code
 
defaults(self, **captures)
Updates the defaults for routing captures with the given settings.		 source code
 
get_state(self, module_name, message)
Returns the state that this module is in for the given message (using its from).		 source code
 
in_state(self, func, message)
Determines if this function is in the state for the to/from in the message.		 source code
 
in_error(self, func, message)
Determines if the this function is in the 'ERROR' state, which is a special state that self puts handlers in that throw an exception.		 source code
 
state_key(self, module_name, message)
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.		 source code
 
set_state(self, module_name, message, state)
Sets the state of the given module (a string) according to the message to the requested state (a string).		 source code
 
_collect_matches(self, message, route_to) source code
 
_enqueue_undeliverable(self, message) source code
 
deliver(self, message)
The meat of the whole Lamson 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.		 source code
 
call_safely(self, func, message, kwargs)
Used by self to call a function and log exceptions rather than explode and crash.		 source code
 
clear_states(self)
Clears out the states for unit testing.		 source code
 
clear_routes(self)
Clears out the routes for unit testing and reloading.		 source code
 
load(self, handlers)
Loads the listed handlers making them available for processing.		 source code
 
reload(self)
Performs a reload of all the handlers and clears out all routes, but doesn't touch the internal state.		 source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self)
(Constructor)

source code 

x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Overrides: object.__init__
(inherited documentation)

register_route(self, format, func)

source code 

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.

match(self, address)

source code 

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>.

defaults(self, **captures)

source code 

Updates the defaults for routing captures with the given settings.

You use this in your handlers or your config/settings.py 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.

get_state(self, module_name, message)

source code 

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

in_state(self, func, message)

source code 

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

in_error(self, func, message)

source code 

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

state_key(self, module_name, message)

source code 

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.

set_state(self, module_name, message, state)

source code 

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.

_collect_matches(self, message, route_to)

source code 

_enqueue_undeliverable(self, message)

source code 

deliver(self, message)

source code  

The meat of the whole Lamson 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 'lamson 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.

call_safely(self, func, message, kwargs)

source code 

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

clear_states(self)

source code 

Clears out the states for unit testing.

clear_routes(self)

source code 

Clears out the routes for unit testing and reloading.

load(self, handlers)

source code 

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

reload(self)

source code 

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


   Home       Trees       Indices       Help   
Lamson Mail Server
Generated by Epydoc 3.0.1 on Wed Jul 7 07:32:52 2010 http://epydoc.sourceforge.net