pymilter  1.0.5
Namespaces | Classes | Functions | Variables
Milter Namespace Reference

A thin OO wrapper for the milter module. More...

Namespaces

 dns
 Provide a higher level interface to pydns.
 
 dsn
 Support DSNs and CallBackValidations (CBV).
 
 pyip6
 
 sgmllib
 
 test
 A test framework for milters.
 
 testctx
 A test framework for milters that replaces milterContext rather than Milter.Base.
 
 utils
 Miscellaneous functions.
 

Classes

class  Base
 A do "nothing" Milter base class representing an SMTP connection. More...
 
class  DisabledAction
 Disabled action exception. More...
 
class  Milter
 A logging but otherwise do nothing Milter base class. More...
 

Functions

def uniqueID ()
 
def decode_mask (bits, names)
 
def enable_protocols (klass, mask)
 Class decorator to enable optional protocol steps. More...
 
def rejected_recipients (klass)
 Milter rejected recipients. More...
 
def header_leading_space (klass)
 Milter leading space on headers. More...
 
def nocallback (func)
 Function decorator to disable callback methods. More...
 
def noreply (func)
 Function decorator to disable callback reply. More...
 
def decode (strategy)
 Function decorator to set decoding error strategy. More...
 
def symlist (*syms)
 Function decorator to set macros used in a callback. More...
 
def negotiate_callback (ctx, opts)
 Connect context to connection instance and return enabled callbacks.
 
def connect_callback (ctx, hostname, family, hostaddr, nr_mask=P_NR_CONN)
 Connect context if needed and invoke connect method.
 
def close_callback (ctx)
 Disconnect milterContext and call close method.
 
def dictfromlist (args)
 Convert ESMTP parameters with values to a keyword dictionary. More...
 
def param2dict (str)
 Convert ESMTP parm list to keyword dictionary. More...
 
def envcallback (c, args)
 
def runmilter (name, socketname, timeout=0, rmsock=True)
 Run the milter. More...
 

Variables

string __version__ = '1.0.5'
 
 _seq_lock = thread.allocate_lock()
 
int _seq = 0
 
dictionary OPTIONAL_CALLBACKS
 
dictionary MACRO_CALLBACKS
 
 R = re.compile(r'%+')
 
 factory = Milter
 The milter connection factory This factory method is called for each connection to create the python object that tracks the connection. More...
 
 __all__ = globals().copy()
 

Detailed Description

A thin OO wrapper for the milter module.

Clients generally subclass Milter.Base and define callback methods.

Author
Stuart D. Gathman stuar.nosp@m.t@bm.nosp@m.si.co.nosp@m.m Copyright 2001,2009 Business Management Systems, Inc. This code is under the GNU General Public License. See COPYING for details.

Function Documentation

◆ decode()

def Milter.decode (   strategy)

Function decorator to set decoding error strategy.

Current RFCs define UTF-8 as the standard encoding for SMTP envelope and header fields. By default, Milter.Base decodes envelope and header values with errors='surrogateescape'. Applications can recover the original bytes with

 b = s.encode(errors='surrogateescape')
 

This preserves information, but can lead to unexpected exceptions as you cannot, e.g. print strings with surrogates. Illegal bytes occur quite often in real life, so there must be a way to deal with them. This decorator can change the error strategy to

  • bytes - original bytes are passed unmodified
  • strict - pass bytes if illegal bytes are present, string otherwise
  • ignore - illegal bytes are removed
  • replace - illegal bytes are replaced with a unicode error symbol

◆ dictfromlist()

def Milter.dictfromlist (   args)

Convert ESMTP parameters with values to a keyword dictionary.

Deprecated:
You probably want Milter.param2dict instead.

◆ enable_protocols()

def Milter.enable_protocols (   klass,
  mask 
)

Class decorator to enable optional protocol steps.

P_SKIP is enabled by default when supported, but applications may wish to enable P_HDR_LEADSPC to send and receive the leading space of header continuation lines unchanged, and/or P_RCPT_REJ to have recipients detected as invalid by the MTA passed to the envcrpt callback.

Applications may want to check whether the protocol is actually supported by the MTA in use. Base._protocol is a bitmask of protocol options negotiated. So, for instance, if self._protocol & Milter.P_RCPT_REJ is true, then that feature was successfully negotiated with the MTA and the application will see recipients the MTA has flagged as invalid.

Sample use:

 class myMilter(Milter.Base):
   def envrcpt(self,to,*params):
     return Milter.CONTINUE
 myMilter = Milter.enable_protocols(myMilter,Milter.P_RCPT_REJ)
 
Since
0.9.3
Parameters
klassthe milter application class to modify
maska bitmask of protocol steps to enable
Returns
the modified milter class

Referenced by header_leading_space(), and rejected_recipients().

◆ envcallback()

def Milter.envcallback (   c,
  args 
)
Call function c with ESMTP parms converted to keyword parameters.
Can be used in the envfrom and/or envrcpt callbacks to process
ESMTP parameters as python keyword parameters.

◆ header_leading_space()

def Milter.header_leading_space (   klass)

Milter leading space on headers.

A class decorator that calls enable_protocols() with the P_HDR_LEADSPC flag. By default, header continuation lines are collected and joined before getting sent to a milter. Headers modified or added by the milter are folded by the MTA as necessary according to its own standards. With this flag, header continuation lines are preserved with their newlines and leading space. In addition, header folding done by the milter is preserved as well. Use like this with python-2.6 and later:

 @Milter.header_leading_space
 class myMilter(Milter.Base):
   def header(self,hname,value):
     return Milter.CONTINUE
 
Since
0.9.5
Parameters
klassthe milter application class to modify
Returns
the modified milter class

References enable_protocols().

◆ nocallback()

def Milter.nocallback (   func)

Function decorator to disable callback methods.

If the MTA supports it, tells the MTA not to invoke this callback, increasing efficiency. All the callbacks (except negotiate) are disabled in Milter.Base, and overriding them reenables the callback. An application may need to use @nocallback when it extends another milter and wants to disable a callback again. The disabled method should still return Milter.CONTINUE, in case the MTA does not support protocol negotiation, and for when called from a test harness.

Since
0.9.2

◆ noreply()

def Milter.noreply (   func)

Function decorator to disable callback reply.

If the MTA supports it, tells the MTA not to wait for a reply from this callback, and assume CONTINUE. The method should still return CONTINUE in case the MTA does not support protocol negotiation. The decorator arranges to change the return code to NOREPLY when supported by the MTA.

Since
0.9.2

◆ param2dict()

def Milter.param2dict (   str)

Convert ESMTP parm list to keyword dictionary.

Params with no value are set to None in the dictionary.

Since
0.9.3
Parameters
strlist of param strings of the form "NAME" or "NAME=VALUE"
Returns
a dictionary of ESMTP param names and values

◆ rejected_recipients()

def Milter.rejected_recipients (   klass)

Milter rejected recipients.

A class decorator that calls enable_protocols() with the P_RCPT_REJ flag. By default, the MTA does not pass recipients that it knows are invalid on to the milter. This decorator enables a milter app to see all recipients if supported by the MTA. Use like this with python-2.6 and later:

 @Milter.rejected_recipients
 class myMilter(Milter.Base):
   def envrcpt(self,to,*params):
     return Milter.CONTINUE
 
Since
0.9.5
Parameters
klassthe milter application class to modify
Returns
the modified milter class

References enable_protocols().

◆ runmilter()

def Milter.runmilter (   name,
  socketname,
  timeout = 0,
  rmsock = True 
)

Run the milter.

Parameters
namethe name of the milter known to the MTA
socketnamethe socket to be passed to milter.setconn()
timeoutthe time in secs the MTA should wait for a response before considering this milter dead

References milter.getversion(), milter.main(), milter.opensocket(), milter.register(), milter.setconn(), and milter.settimeout().

◆ symlist()

def Milter.symlist ( syms)

Function decorator to set macros used in a callback.

By default, the MTA sends all macros defined for a callback. If some or all of these are unused, the bandwidth can be saved by listing the ones that are used.

Since
1.0.2

◆ uniqueID()

def Milter.uniqueID ( )
Return a unique sequence number (incremented on each call).

Variable Documentation

◆ factory

Milter.factory = Milter

The milter connection factory This factory method is called for each connection to create the python object that tracks the connection.

It should return an object derived from Milter.Base.

Note that since python is dynamic, this variable can be changed while the milter is running: for instance, to a new subclass based on a change in configuration.

Referenced by connect_callback(), and negotiate_callback().

◆ MACRO_CALLBACKS

dictionary Milter.MACRO_CALLBACKS
Initial value:
1 = {
2  'connect': M_CONNECT,
3  'hello': M_HELO, 'envfrom': M_ENVFROM, 'envrcpt': M_ENVRCPT,
4  'data': M_DATA, 'eom': M_EOM, 'eoh': M_EOH
5 }

◆ OPTIONAL_CALLBACKS

dictionary Milter.OPTIONAL_CALLBACKS
private
Initial value:
1 = {
2  'connect':(P_NR_CONN,P_NOCONNECT),
3  'hello':(P_NR_HELO,P_NOHELO),
4  'envfrom':(P_NR_MAIL,P_NOMAIL),
5  'envrcpt':(P_NR_RCPT,P_NORCPT),
6  'data':(P_NR_DATA,P_NODATA),
7  'unknown':(P_NR_UNKN,P_NOUNKNOWN),
8  'eoh':(P_NR_EOH,P_NOEOH),
9  'body':(P_NR_BODY,P_NOBODY),
10  'header':(P_NR_HDR,P_NOHDRS)
11 }