slimta.lookup

This module is available in the python-slimta-lookup extension package.

slimta.lookup.policy

Provides an implementation of the QueuePolicy interface that enforces policies specified in a slimta lookup record.

Currently the following record keys are implemented:

alias
Rewrites the envelope, replacing occurrences of the looked up address with the contents of this field.
add_headers
If the contents of this field are a JSON-decodable dictionary, the keys and values are prepended to the message as new headers. Existing headers are left untouched.
class slimta.lookup.policy.LookupPolicy(lookup[, on_sender=False[, on_rcpts=True]])

Bases: slimta.policy.QueuePolicy

Instances of this class may be configured to run before a message is queued using slimta.queue.Queue.add_policy().

Parameters:
  • lookup – The slimta lookup driver, implementing the LookupBase interface.
  • on_sender (bool) – If True, the envelope sender is looked up and has policies applied.
  • on_rcpts (bool) – If True, the envelope recipients are looked up, each one applying any policies found in the record.
apply(envelope)

QueuePolicy sub-classes must override this method, which will be called by the Queue before storage.

Parameters:envelope – The Envelope object the policy execution should apply any changes to. This envelope object may be modified, though if new envelopes are returned this object is discarded.
Returns:Optionally return or generate an iterable of Envelope objects to replace the given envelope going forward. Returning None or an empty list will keep using envelope.

slimta.lookup.drivers

This package contains several implementations of the slimta lookup mechanism, which provides a simple interface to control actions and policies with external lookups. Under normal circumstances, slimta lookup drivers do not modify their backend data source.

class slimta.lookup.drivers.LookupBase([*args[, **kwargs]])

Bases: object

Inherit this class to implement a slimta lookup driver. Only the lookup() method must be overridden.

lookup([**kwargs])

The keyword arguments will be used by the lookup driver to return a dictionary-like object that will be used to affect actions or policy. For some drivers, these keywords may be used with a template to produce a lookup key. For SQL-style drivers, they might be used in a WHERE clause of a SELECT query.

Parameters:kwargs (keyword arguments) – Used by the driver to lookup records.
Returns:A dictionary if a record was found, None otherwise.
lookup_address(address[, **extra])

A convenience method where the given address is passed in as the address keyword to lookup(). If the address has domain part, it is substringed and passed in as the domain keyword a well.

Parameters:
  • address (str) – An address to lookup, either as the full address or as its domain part.
  • extra (keyword arguments) – Additional keyword arguments to pass in to lookup().
log(name, kwargs, ret)

Implementing drivers should call this method to log the lookup transaction.

Parameters:
  • name (str) – The module name, e.g. __name__.
  • kwargs (dict) – The keyword arguments given to lookup().
  • ret – The return value of the lookup, e.g. a dictionary or None.

slimta.lookup.drivers.redis

Implements slimta lookup against a redis data backend. By default, this driver expects records to be JSON-encoded string values. It can be configured to use the hash data structure instead, but it is less flexible.

class slimta.lookup.drivers.redis.RedisLookup(key_template[, host='localhost'[, port=6379[, db=0[, password=None[, socket_timeout=None[, use_hash=False]]]]]])

Bases: slimta.lookup.drivers.LookupBase

Implements the slimta lookup interface using the redis key-value storage as the backend layer.

Parameters:
  • key_template (str) – This template string is used to determine the key string to lookup. :The format() method is called with keyword arguments, given the keyword arguments passed in to lookup().
  • host – Hostname of the redis server to connect to.
  • port – Port to connect to.
  • db – Database number to create keys in.
  • password – Optional password to authenticate with.
  • socket_timeout – Timeout, in seconds, for socket operations. If the timeout is hit, socket.timeout is raised. None disables the timeout.
  • use_hash – If True, keys will be looked up as hashes with HGETALL instead of as JSON-encoded strings. Hashes do not allow for complex values in results, and cannot distinguish missing records from empty records.
lookup([**kwargs])

The keyword arguments will be used by the lookup driver to return a dictionary-like object that will be used to affect actions or policy. For some drivers, these keywords may be used with a template to produce a lookup key. For SQL-style drivers, they might be used in a WHERE clause of a SELECT query.

Parameters:kwargs (keyword arguments) – Used by the driver to lookup records.
Returns:A dictionary if a record was found, None otherwise.

slimta.lookup.drivers.dbapi2

Implements slimta lookup against a DB API 2.0 database interface. This driver should be flexible enough to support any implementing database.

Any database used with this driver should use gevent sockets (or monkey-patching) to ensure good performance.

This module also provides a SQLite convenience class.

class slimta.lookup.drivers.dbapi2.DBAPI2Lookup(conn_ctxmgr, query[, query_param_order=None[, result_order=None[, conn=None]]])

Bases: slimta.lookup.drivers.LookupBase

Implements the slimta lookup interface using the generic DB API 2.0 specification.

Parameters:
  • conn_ctxmgr – A context manager that, given no arguments, produces an open database connection, and cleans it up afterwards. This allows flexibility in how connections are managed or pooled.
  • query (str) – The query string used to lookup records in the database.
  • query_param_order (list) – If query uses positional parameters, this must be a list of keywords from the lookup() to translate from keywords to positional arguments.
  • result_order – Most database implementations return rows as a sequence instead of a mapping. In this case, this argument must be given to translate the sequence into a dictionary, TypeError may be raised in the lookup() method otherwise.
  • conn – If conn_ctxmgr is None, a simple one is generated that simply returns the value of this argument. Useful for databases that have a single, persistent connection object.
lookup([**kwargs])

The keyword arguments will be used by the lookup driver to return a dictionary-like object that will be used to affect actions or policy. For some drivers, these keywords may be used with a template to produce a lookup key. For SQL-style drivers, they might be used in a WHERE clause of a SELECT query.

Parameters:kwargs (keyword arguments) – Used by the driver to lookup records.
Returns:A dictionary if a record was found, None otherwise.
class slimta.lookup.drivers.dbapi2.SQLite3Lookup(database, query)

Bases: slimta.lookup.drivers.dbapi2.DBAPI2Lookup

Implements the slimta lookup interface using the sqlite3 module. The connection object is created immediately and kept open for all calls to lookup().

Parameters:
  • database (str) – The database filename, as given in sqlite3.connect().
  • query (str) – The query string used to lookup records in the database. This query must use named-style placeholders (e.g. col = :keyword.

slimta.lookup.drivers.dict

Implements slimta lookup against a standard Python dictionary-like object. This object should be given pre-populated in the constructor, or be a proxy to a persistent backend like shelve.

class slimta.lookup.drivers.dict.DictLookup(backend, key_template)

Bases: slimta.lookup.drivers.LookupBase

Instantiate this class with a Python dictionary-like object and it may be used as a slimta lookup interface.

Parameters:
  • backend (collections.Mapping) – The backend dictionary-like object that will be queried for data lookups. The values in this mapping must also be dictionary-like objects.
  • key_template (str) – This template string is used to determine the key string to lookup. The str.format() method is called with keyword arguments, given the keyword arguments passed in to lookup().
lookup([**kwargs])

The keyword arguments will be used by the lookup driver to return a dictionary-like object that will be used to affect actions or policy. For some drivers, these keywords may be used with a template to produce a lookup key. For SQL-style drivers, they might be used in a WHERE clause of a SELECT query.

Parameters:kwargs (keyword arguments) – Used by the driver to lookup records.
Returns:A dictionary if a record was found, None otherwise.

slimta.lookup.drivers.regex

Implements slimta lookup against a series of regular expressions.

class slimta.lookup.drivers.regex.RegexLookup(str_template)

Bases: slimta.lookup.drivers.LookupBase

Instantiate this class without any mappings. This object may be used as a slimta lookup interface.

Parameters:str_template (str) – This template string is used to determine the string to match against the regular expressions. The str.format() method is called with keyword arguments, given the keyword arguments passed in to lookup().
add_regex(pattern, value)

Adds a regular expression with the associated value.

Parameters:
  • pattern (str or re.RegexObject) – Pattern to check the lookup string against.
  • value – The value to return on successful lookup.
lookup([**kwargs])

The keyword arguments will be used by the lookup driver to return a dictionary-like object that will be used to affect actions or policy. For some drivers, these keywords may be used with a template to produce a lookup key. For SQL-style drivers, they might be used in a WHERE clause of a SELECT query.

Parameters:kwargs (keyword arguments) – Used by the driver to lookup records.
Returns:A dictionary if a record was found, None otherwise.