This commit was manufactured by cvs2svn to create tag 'pymilter-0_9_6'.

Sprout from master 2012-03-03 18:51:56 UTC Stuart Gathman <stuart@gathman.org> 'Release 0.9.6'
Cherrypick from bmsi 2005-05-31 18:23:49 UTC Stuart Gathman <stuart@gathman.org> 'Development changes since 0.7.2':
    sample.py
    test/big5
    test/bounce
    test/bounce1
    test/bound
    test/honey
    test/missingboundary
    test/samp1
    test/spam44
    test/spam7
    test/spam8
    test/test1
    test/test8
    test/virus1
    test/virus13
    test/virus2
    test/virus3
    test/virus4
    test/virus5
    test/virus6
    test/virus7

CREDITS

@@ -7,6 +7,9 @@ real, usable Python extension.
 
 Other contributors (in random order):
 
+
+Daniel Troeder
+  for pointing out a typo in @noreply
 arkanes@irc.freenode.net
   for suggesting a class method to compute and cache protocol masks
 habnabit@habnabit.org

Milter/__init__.py

@@ -1,10 +1,14 @@
-# Author: Stuart D. Gathman <stuart@bmsi.com>
+## @package Milter
-# Copyright 2001 Business Management Systems, Inc.
+# A thin OO wrapper for the milter module.
+#
+# Clients generally subclass Milter.Base and define callback
+# methods.
+#
+# @author Stuart D. Gathman <stuart@bmsi.com>
+# Copyright 2001,2009 Business Management Systems, Inc.
 # This code is under the GNU General Public License.  See COPYING for details.
 
-# A thin OO wrapper for the milter module
+__version__ = '0.9.5'
-
-__version__ = '0.9.2'
 
 import os
 import milter
@@ -15,8 +19,14 @@ from milter import *
 _seq_lock = thread.allocate_lock()
 _seq = 0
 
+## @fn set_flags(flags)
+# @brief Enable optional %milter actions.
+# Certain %milter actions need to be enabled before calling milter.runmilter()
+# or they throw an exception. 
+# @param flags Bit ored mask of optional actions to enable
+
 def uniqueID():
-  """Return a sequence number unique to this process.
+  """Return a unique sequence number (incremented on each call).
   """
   global _seq
   _seq_lock.acquire()
@@ -24,6 +34,7 @@ def uniqueID():
   _seq_lock.release()
   return seqno
 
+## @private
 OPTIONAL_CALLBACKS = {
   'connect':(P_NR_CONN,P_NOCONNECT),
   'hello':(P_NR_HELO,P_NOHELO),
@@ -36,6 +47,90 @@ OPTIONAL_CALLBACKS = {
   'header':(P_NR_HDR,P_NOHDRS)
 }
 
+## @private
+def decode_mask(bits,names):
+  t = [ (s,getattr(milter,s)) for s in names]
+  nms = [s for s,m in t if bits & m]
+  for s,m in t: bits &= ~m
+  if bits: nms += hex(bits)
+  return nms
+
+## 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 <code>self._protocol & Milter.P_RCPT_REJ</code>
+# 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:
+# <pre>
+# class myMilter(Milter.Base):
+#   def envrcpt(self,to,*params):
+#     return Milter.CONTINUE
+# myMilter = Milter.enable_protocols(myMilter,Milter.P_RCPT_REJ)
+# </pre>
+# @since 0.9.3
+# @param klass the %milter application class to modify
+# @param mask a bitmask of protocol steps to enable
+# @return the modified %milter class
+def enable_protocols(klass,mask):
+  klass._protocol_mask = klass.protocol_mask() & ~mask
+  return 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:
+# <pre>
+# @@Milter.rejected_recipients
+# class myMilter(Milter.Base):
+#   def envrcpt(self,to,*params):
+#     return Milter.CONTINUE
+# </pre>
+# @since 0.9.5
+# @param klass the %milter application class to modify
+# @return the modified %milter class
+def rejected_recipients(klass):
+  return enable_protocols(klass,P_RCPT_REJ)
+
+## Milter leading space on headers. A class decorator that calls
+# enable_protocols() with the P_HEAD_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:
+# <pre>
+# @@Milter.header_leading_space
+# class myMilter(Milter.Base):
+#   def header(self,hname,value):
+#     return Milter.CONTINUE
+# </pre>
+# @since 0.9.5
+# @param klass the %milter application class to modify
+# @return the modified %milter class
+def header_leading_space(klass):
+  return enable_protocols(klass,P_HEAD_LEADSPC)
+
+## 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
 def nocallback(func):
   try:
     func.milter_protocol = OPTIONAL_CALLBACKS[func.__name__][1]
@@ -44,10 +139,17 @@ def nocallback(func):
       '@nocallback applied to non-optional method: '+func.__name__)
   return 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
 def noreply(func):
   try:
     nr_mask = OPTIONAL_CALLBACKS[func.__name__][0]
-  except KeyErro:
+  except KeyError:
     raise ValueError(
       '@noreply applied to non-optional method: '+func.__name__)
   def wrapper(self,*args):
@@ -57,51 +159,173 @@ def noreply(func):
   wrapper.milter_protocol = nr_mask
   return wrapper
 
+## Disabled action exception.
+# set_flags() can tell the MTA that this application will not use certain
+# features (such as CHGFROM).  This can also be negotiated for each
+# connection in the negotiate callback.  If the application then calls
+# the feature anyway via an instance method, this exception is
+# thrown.
+# @since 0.9.2
 class DisabledAction(RuntimeError):
   pass
 
-# A do nothing Milter base class from which python milters should derive
+## A do "nothing" Milter base class representing an SMTP connection.
-# unless they are using the milter C module directly.
+#
+# Python milters should derive from this class
+# unless they are using the low level milter module directly.  
+#
+# Most of the methods are either "actions" or "callbacks".  Callbacks
+# are invoked by the MTA at certain points in the SMTP protocol.  For
+# instance when the HELO command is seen, the MTA calls the helo
+# callback before returning a response code.  All callbacks must
+# return one of these constants: CONTINUE, TEMPFAIL, REJECT, ACCEPT,
+# DISCARD, SKIP.  The NOREPLY response is supplied automatically by
+# the @@noreply decorator if negotiation with the MTA is successful.
+# @@noreply and @@nocallback methods should return CONTINUE for two reasons:
+# the MTA may not support negotiation, and the class may be running in a test
+# harness.
+# 
+# Optional callbacks are disabled with the @@nocallback decorator, and
+# automatically reenabled when overridden.  Disabled callbacks should
+# still return CONTINUE for testing and MTAs that do not support
+# negotiation.  
 
+# Each SMTP connection to the MTA calls the factory method you provide to
+# create an instance derived from this class.  This is typically the
+# constructor for a class derived from Base.  The _setctx() method attaches
+# the instance to the low level milter.milterContext object.  When the SMTP
+# connection terminates, the close callback is called, the low level connection
+# object is destroyed, and this normally causes instances of this class to be
+# garbage collected as well.  The close() method should release any global
+# resources held by instances.
+# @since 0.9.2
 class Base(object):
-  "The core class interface to the milter module."
+  "The core class interface to the %milter module."
 
+  ## Attach this Milter to the low level milter.milterContext object.
   def _setctx(self,ctx):
+    ## The low level @ref milter.milterContext object.
     self._ctx = ctx
+    ## A bitmask of actions this connection has negotiated to use.
+    # By default, all actions are enabled.  High throughput milters
+    # may want to disable unused actions to increase efficiency.
+    # Some optional actions may be disabled by calling milter.set_flags(), or
+    # by overriding the negotiate callback.  The bits include:
+    # <code>ADDHDRS,CHGBODY,MODBODY,ADDRCPT,ADDRCPT_PAR,DELRCPT
+    #  CHGHDRS,QUARANTINE,CHGFROM,SETSMLIST</code>.
+    # The <code>Milter.CURR_ACTS</code> bitmask is all actions
+    # known when the milter module was compiled.
+    # Application code can also inspect this field to determine
+    # which actions are available.  This is especially useful in
+    # generic library code designed to work in multiple milters.
+    # @since 0.9.2
+    #
     self._actions = CURR_ACTS         # all actions enabled by default
+    ## A bitmask of protocol options this connection has negotiated.
+    # An application may inspect this
+    # variable to determine which protocol steps are supported.  Options
+    # of interest to applications: the SKIP result code is allowed
+    # only if the P_SKIP bit is set, rejected recipients are passed to the
+    # %milter application only if the P_RCPT_REJ bit is set, and
+    # header values are sent and received with leading spaces (in the
+    # continuation lines) intact if the P_HDR_LEADSPC bit is set (so
+    # that the application can customize indenting).  
+    #
+    # The P_N* bits should be negotiated via the @@noreply and @@nocallback
+    # method decorators, and P_RCPT_REJ, P_HDR_LEADSPC should
+    # be enabled using the enable_protocols class decorator.
+    #
+    # The bits include: <code>
+    # P_RCPT_REJ P_NR_CONN P_NR_HELO P_NR_MAIL P_NR_RCPT P_NR_DATA P_NR_UNKN
+    # P_NR_EOH P_NR_BODY P_NR_HDR P_NOCONNECT P_NOHELO P_NOMAIL P_NORCPT
+    # P_NODATA P_NOUNKNOWN P_NOEOH P_NOBODY P_NOHDRS P_HDR_LEADSPC P_SKIP
+    # </code> (all under the Milter namespace).
+    # @since 0.9.2
     self._protocol = 0                # no protocol options by default
     if ctx:
       ctx.setpriv(self)
+
+  ## Defined by subclasses to write log messages.
   def log(self,*msg): pass
+  ## Called for each connection to the MTA.
+  # The <code>hostname</code> provided by the local MTA is either
+  # the PTR name or the IP in the form "[1.2.3.4]" if no PTR is available.
+  # The format of hostaddr depends on the socket family:
+  # <dl>
+  # <dt><code>socket.AF_INET</code>
+  # <dd>A tuple of (IP as string in dotted quad form, integer port)
+  # <dt><code>socket.AF_INET6</code>
+  # <dd>A tuple of (IP as a string in standard representation,
+  # integer port, integer flow info, integer scope id)
+  # <dt><code>socket.AF_UNIX</code>
+  # <dd>A string with the socketname
+  # </dl>
+  # @param hostname the PTR name or bracketed IP of the SMTP client
+  # @param family <code>socket.AF_INET</code>, <code>socket.AF_INET6</code>,
+  #     or <code>socket.AF_UNIX</code>
+  # @param hostaddr a tuple or string with peer IP or socketname
   @nocallback
   def connect(self,hostname,family,hostaddr): return CONTINUE
+  ## Called when the SMTP client says HELO.
+  # Returning REJECT prevents progress until a valid HELO is provided;
+  # this almost always results in terminating the connection.
   @nocallback
   def hello(self,hostname): return CONTINUE
+  ## Called when the SMTP client says MAIL FROM.
+  # Returning REJECT rejects the message, but not the connection.
   @nocallback
   def envfrom(self,f,*str): return CONTINUE
+  ## Called when the SMTP client says RCPT TO.
+  # Returning REJECT rejects the current recipient, not the entire message.
   @nocallback
   def envrcpt(self,to,*str): return CONTINUE
+  ## Called when the SMTP client says DATA.
+  # Returning REJECT rejects the message without wasting bandwidth
+  # on the unwanted message.
+  # @since 0.9.2
   @nocallback
   def data(self): return CONTINUE
+  ## Called for each header field in the message body.
   @nocallback
   def header(self,field,value): return CONTINUE
+  ## Called at the blank line that terminates the header fields.
   @nocallback
   def eoh(self): return CONTINUE
+  ## Called to supply the body of the message to the Milter by chunks.
+  # @param blk a block of message bytes
   @nocallback
-  def body(self,unused): return CONTINUE
+  def body(self,blk): return CONTINUE
+  ## Called when the SMTP client issues an unknown command.
+  # @param cmd the unknown command
+  # @since 0.9.2
   @nocallback
   def unknown(self,cmd): return CONTINUE
+  ## Called at the end of the message body.
+  # Most of the message manipulation actions can only take place from
+  # the eom callback.
   def eom(self): return CONTINUE
+  ## Called when the connection is abnormally terminated.
+  # The close callback is still called also.
   def abort(self): return CONTINUE
+  ## Called when the connection is closed.
   def close(self): return CONTINUE
 
-  # Return mask of SMFIP_N.. protocol option bits to clear for this class
+  ## Return mask of SMFIP_N* protocol option bits to clear for this class
+  # The @@nocallback and @@noreply decorators set the
+  # <code>milter_protocol</code> function attribute to the protocol mask bit to
+  # pass to libmilter, causing that callback or its reply to be skipped.
+  # Overriding a method creates a new function object, so that 
+  # <code>milter_protocol</code> defaults to 0.
+  # Libmilter passes the protocol bits that the current MTA knows
+  # how to skip.  We clear the ones we don't want to skip.
+  # The negation is somewhat mind bending, but it is simple.
+  # @since 0.9.2
   @classmethod
   def protocol_mask(klass):
     try:
       return klass._protocol_mask
     except AttributeError:
-      p = 0
+      p = P_RCPT_REJ | P_HDR_LEADSPC    # turn these new features off by default
       for func,(nr,nc) in OPTIONAL_CALLBACKS.items():
         func = getattr(klass,func)
         ca = getattr(func,'milter_protocol',0)
@@ -110,13 +334,25 @@ class Base(object):
       klass._protocol_mask = p
       return p
     
+  ## Negotiate milter protocol options.  Called by the
+  # <a href="https://www.milter.org/developers/api/xxfi_negotiate">
+  # xffi_negotiate</a> callback.  This is an advanced callback,
+  # do not override unless you know what you are doing.  Most
+  # negotiation can be done simply by using the supplied 
+  # class and function decorators.
+  # Options are passed as 
+  # a list of 4 32-bit ints which can be modified and are passed
+  # back to libmilter on return.
   # Default negotiation sets P_NO* and P_NR* for callbacks
-  # marked @nocallback and @noreply respectively
+  # marked @@nocallback and @@noreply respectively, leaves all
+  # actions enabled, and enables Milter.SKIP.  The @@enable_protocols
+  # class decorator can customize which protocol steps are implemented.
+  # @param opts a modifiable list of 4 ints with negotiated options
+  # @since 0.9.2
   def negotiate(self,opts):
     try:
       self._actions,p,f1,f2 = opts
-      opts[1] = self._protocol = \
+      opts[1] = self._protocol = p & ~self.protocol_mask()
-              p & ~self.protocol_mask() & ~P_RCPT_REJ & ~P_HDR_LEADSPC
       opts[2] = 0
       opts[3] = 0
       #self.log("Negotiated:",opts)
@@ -126,15 +362,37 @@ class Base(object):
     return CONTINUE
 
   # Milter methods which can be invoked from most callbacks
+
+  ## Return the value of an MTA macro.  Sendmail macro names
+  # are either single chars (e.g. "j") or multiple chars enclosed
+  # in braces (e.g. "{auth_type}").  Macro names are MTA dependent.
+  # See <a href="https://www.milter.org/developers/api/smfi_getsymval">
+  # smfi_getsymval</a> for default sendmail macros.
+  # @param sym the macro name
   def getsymval(self,sym):
     return self._ctx.getsymval(sym)
 
-  # If sendmail does not support setmlreply, then only the
+  ## Set the SMTP reply code and message.
-  # first msg line is used.
+  # If the MTA does not support setmlreply, then only the
+  # first msg line is used.  Any '%' in a message line
+  # must be doubled, or libmilter will silently ignore the setreply.
+  # Beginning with 0.9.6, we test for that case and throw ValueError to avoid
+  # head scratching.  What will <i>really</i> irritate you, however,
+  # is that if you carefully double any '%', your message will be
+  # sent - but with the '%' still doubled!
   def setreply(self,rcode,xcode=None,msg=None,*ml):
+    for m in (msg,)+ml:
+      if 1 in [len(s)&1 for s in R.findall(m)]:
+        raise ValueError("'%' must be doubled: "+m)
     return self._ctx.setreply(rcode,xcode,msg,*ml)
 
-  # may only be called from negotiate callback
+  ## Tell the MTA which macro names will be used.
+  # The <code>Milter.SETSMLIST</code> action flag must be set.
+  #
+  # May only be called from negotiate callback.
+  # @since 0.9.2
+  # @param stage the protocol stage to set to macro list for
+  # @param macros a string with a space delimited list of macros
   def setsmlist(self,stage,macros):
     if not self._actions & SETSMLIST: raise DisabledAction("SETSMLIST")
     if type(macros) in (list,tuple):
@@ -142,45 +400,127 @@ class Base(object):
     return self._ctx.setsmlist(stage,macros)
 
   # Milter methods which can only be called from eom callback.
+
+  ## Add a mail header field.
+  # Calls <a href="https://www.milter.org/developers/api/smfi_addheader">
+  # smfi_addheader</a>.  
+  # The <code>Milter.ADDHDRS</code> action flag must be set.
+  #
+  # May be called from eom callback only.
+  # @param field        the header field name
+  # @param value        the header field value
+  # @param idx header field index from the top of the message to insert at
+  # @throws DisabledAction if ADDHDRS is not enabled
   def addheader(self,field,value,idx=-1):
     if not self._actions & ADDHDRS: raise DisabledAction("ADDHDRS")
     return self._ctx.addheader(field,value,idx)
 
+  ## Change the value of a mail header field.
+  # Calls <a href="https://www.milter.org/developers/api/smfi_chgheader">
+  # smfi_chgheader</a>.  
+  # The <code>Milter.CHGHDRS</code> action flag must be set.
+  #
+  # May be called from eom callback only.
+  # @param field the name of the field to change
+  # @param idx index of the field to change when there are multiple instances
+  # @param value the new value of the field
+  # @throws DisabledAction if CHGHDRS is not enabled
   def chgheader(self,field,idx,value):
     if not self._actions & CHGHDRS: raise DisabledAction("CHGHDRS")
     return self._ctx.chgheader(field,idx,value)
 
+  ## Add a recipient to the message.  
+  # Calls <a href="https://www.milter.org/developers/api/smfi_addrcpt">
+  # smfi_addrcpt</a>.  
+  # If no corresponding mail header is added, this is like a Bcc.
+  # The syntax of the recipient is the same as used in the SMTP
+  # RCPT TO command (and as delivered to the envrcpt callback), for example
+  # "self.addrcpt('<foo@example.com>')".  
+  # The <code>Milter.ADDRCPT</code> action flag must be set.
+  # If the optional <code>params</code> argument is used, then
+  # the <code>Milter.ADDRCPT_PAR</code> action flag must be set.
+  #
+  # May be called from eom callback only.
+  # @param rcpt the message recipient 
+  # @param params an optional list of ESMTP parameters
+  # @throws DisabledAction if ADDRCPT or ADDRCPT_PAR is not enabled 
   def addrcpt(self,rcpt,params=None):
     if not self._actions & ADDRCPT: raise DisabledAction("ADDRCPT")
+    if params and not self._actions & ADDRCPT_PAR:
+        raise DisabledAction("ADDRCPT_PAR")
     return self._ctx.addrcpt(rcpt,params)
-
+  ## Delete a recipient from the message.
+  # Calls <a href="https://www.milter.org/developers/api/smfi_delrcpt">
+  # smfi_delrcpt</a>.  
+  # The recipient should match one passed to the envrcpt callback.
+  # The <code>Milter.DELRCPT</code> action flag must be set.
+  #
+  # May be called from eom callback only.
+  # @param rcpt the message recipient to delete
+  # @throws DisabledAction if DELRCPT is not enabled
   def delrcpt(self,rcpt):
     if not self._actions & DELRCPT: raise DisabledAction("DELRCPT")
     return self._ctx.delrcpt(rcpt)
 
+  ## Replace the message body.
+  # Calls <a href="https://www.milter.org/developers/api/smfi_replacebody">
+  # smfi_replacebody</a>.  
+  # The entire message body must be replaced.  
+  # Call repeatedly with blocks of data until the entire body is transferred.
+  # The <code>Milter.MODBODY</code> action flag must be set.
+  #
+  # May be called from eom callback only.
+  # @param body a chunk of body data
+  # @throws DisabledAction if MODBODY is not enabled
   def replacebody(self,body):
     if not self._actions & MODBODY: raise DisabledAction("MODBODY")
     return self._ctx.replacebody(body)
 
+  ## Change the SMTP envelope sender address.
+  # Calls <a href="https://www.milter.org/developers/api/smfi_chgfrom">
+  # smfi_chgfrom</a>.  
+  # The syntax of the sender is that same as used in the SMTP
+  # MAIL FROM command (and as delivered to the envfrom callback),
+  # for example <code>self.chgfrom('<bar@example.com>')</code>.
+  # The <code>Milter.CHGFROM</code> action flag must be set.
+  #
+  # May be called from eom callback only.
+  # @since 0.9.1
+  # @param sender the new sender address
+  # @param params an optional list of ESMTP parameters
+  # @throws DisabledAction if CHGFROM is not enabled
   def chgfrom(self,sender,params=None):
     if not self._actions & CHGFROM: raise DisabledAction("CHGFROM")
     return self._ctx.chgfrom(sender,params)
 
+  ## Quarantine the message.
+  # Calls <a href="https://www.milter.org/developers/api/smfi_quarantine">
+  # smfi_quarantine</a>.  
   # When quarantined, a message goes into the mailq as if to be delivered,
   # but delivery is deferred until the message is unquarantined.
+  # The <code>Milter.QUARANTINE</code> action flag must be set.
+  #
+  # May be called from eom callback only.
+  # @param reason a string describing the reason for quarantine
+  # @throws DisabledAction if QUARANTINE is not enabled
   def quarantine(self,reason):
     if not self._actions & QUARANTINE: raise DisabledAction("QUARANTINE")
     return self._ctx.quarantine(reason)
 
+  ## Tell the MTA to wait a bit longer.
+  # Calls <a href="https://www.milter.org/developers/api/smfi_progress">
+  # smfi_progress</a>.  
+  # Resets timeouts in the MTA that detect a "hung" milter.
   def progress(self):
     return self._ctx.progress()
   
-# A logging but otherwise do nothing Milter base class included
+## A logging but otherwise do nothing Milter base class.
-# for compatibility with previous versions of pymilter.
+# This is included for compatibility with previous versions of pymilter.
-
+# The logging callbacks are marked @@noreply.
 class Milter(Base):
   "A simple class interface to the milter module."
 
+  ## Provide simple logging to sys.stdout
   def log(self,*msg):
     print 'Milter:',
     for i in msg: print i,
@@ -240,13 +580,25 @@ class Milter(Base):
     self.log("close")
     return CONTINUE
 
+## 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.
 factory = Milter
 
+## @private
+# @brief Connect context to connection instance and return enabled callbacks.
 def negotiate_callback(ctx,opts):
   m = factory()
   m._setctx(ctx)
   return m.negotiate(opts)
 
+## @private
+# @brief Connect context if needed and invoke connect method.
 def connect_callback(ctx,hostname,family,hostaddr,nr_mask=P_NR_CONN):
   m = ctx.getpriv()
   if not m:     
@@ -256,6 +608,8 @@ def connect_callback(ctx,hostname,family,hostaddr,nr_mask=P_NR_CONN):
     m._setctx(ctx)
   return m.connect(hostname,family,hostaddr)
 
+## @private
+# @brief Disconnect milterContext and call close method.
 def close_callback(ctx):
   m = ctx.getpriv()
   if not m: return CONTINUE
@@ -265,8 +619,10 @@ def close_callback(ctx):
     m._setctx(None)	# release milterContext
   return rc
 
+## Convert ESMTP parameters with values to a keyword dictionary.
+# @deprecated You probably want Milter.param2dict instead.
 def dictfromlist(args):
-  "Convert ESMTP parm list to keyword dictionary."
+  "Convert ESMTP parms with values to keyword dictionary."
   kw = {}
   for s in args:
     pos = s.find('=')
@@ -274,6 +630,18 @@ def dictfromlist(args):
       kw[s[:pos].upper()] = s[pos+1:]
   return kw
 
+## Convert ESMTP parm list to keyword dictionary.
+# Params with no value are set to None in the dictionary.
+# @since 0.9.3
+# @param str list of param strings of the form "NAME" or "NAME=VALUE"
+# @return a dictionary of ESMTP param names and values
+def param2dict(str): 
+  "Convert ESMTP parm list to keyword dictionary."
+  pairs = [x.split('=',1) for x in str]
+  for e in pairs:
+    if len(e) < 2: e.append(None)
+  return dict([(k.upper(),v) for k,v in pairs])
+  
 def 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
@@ -288,6 +656,11 @@ def envcallback(c,args):
       pargs.append(s)
   return c(*pargs,**kw)
 
+## Run the %milter.
+# @param name the name of the %milter known to the MTA
+# @param socketname the socket to be passed to milter.setconn()
+# @param timeout the time in secs the MTA should wait for a response before 
+#	considering this %milter dead
 def runmilter(name,socketname,timeout = 0):
   # This bit is here on the assumption that you will be starting this filter
   # before sendmail.  If sendmail is not running and the socket already exists,
@@ -330,11 +703,15 @@ def runmilter(name,socketname,timeout = 0):
 
   milter.setconn(socketname)
   if timeout > 0: milter.settimeout(timeout)
+  # disable negotiate callback if runtime version < (1,0,1)
+  ncb = negotiate_callback
+  if milter.getversion() < (1,0,1):
+    ncb = None
   # The name *must* match the X line in sendmail.cf (supposedly)
   milter.register(name,
         data=lambda ctx: ctx.getpriv().data(),
         unknown=lambda ctx,cmd: ctx.getpriv().unknown(cmd),
-        negotiate=negotiate_callback
+        negotiate=ncb
   )
   start_seq = _seq
   try:
@@ -348,3 +725,7 @@ __all__ = globals().copy()
 for priv in ('os','milter','thread','factory','_seq','_seq_lock','__version__'):
   del __all__[priv]
 __all__ = __all__.keys()
+
+## @example milter-template.py
+## @example milter-nomix.py
+#

Milter/dns.py

@@ -1,12 +1,22 @@
-# provide a higher level interface to pydns
+## @package Milter.dns
+# Provide a higher level interface to pydns.
 
 import DNS
 from DNS import DNSError
 
 MAX_CNAME = 10
 
+## Lookup DNS records by label and RR type.
+# The response can include records of other types that the DNS
+# server thinks we might need.
+# @param name the DNS label to lookup
+# @param qtype the name of the DNS RR type to lookup
+# @return a list of ((name,type),data) tuples
 def DNSLookup(name, qtype):
     try:
+	# To be thread safe, we create a fresh DnsRequest with
+	# each call.  It would be more efficient to reuse
+	# a req object stored in a Session.
         req = DNS.DnsRequest(name, qtype=qtype)
         resp = req.req()
         #resp.show()
@@ -24,25 +34,28 @@ class Session(object):
   def __init__(self):
     self.cache = {}
 
+  ## Additional DNS RRs we can safely cache.
   # We have to be careful which additional DNS RRs we cache.  For
   # instance, PTR records are controlled by the connecting IP, and they
   # could poison our local cache with bogus A and MX records.  
+  # Each entry is a tuple of (query_type,rr_type).  So for instance,
+  # the entry ('MX','A') says it is safe (for milter purposes) to cache
+  # any 'A' RRs found in an 'MX' query.
+  SAFE2CACHE = frozenset((
+    ('MX','MX'), ('MX','A'),
+    ('CNAME','CNAME'), ('CNAME','A'),
+    ('A','A'),
+    ('AAAA','AAAA'),
+    ('PTR','PTR'),
+    ('NS','NS'), ('NS','A'),
+    ('TXT','TXT'),
+    ('SPF','SPF')
+  ))
 
-  SAFE2CACHE = {
+  ## Cached DNS lookup.
-    ('MX','A'): None,
+  # @param name the DNS label to query
-    ('MX','MX'): None,
+  # @param qtype the query type, e.g. 'A'
-    ('CNAME','A'): None,
+  # @param cnames tracks CNAMES already followed in recursive calls
-    ('CNAME','CNAME'): None,
-    ('A','A'): None,
-    ('AAAA','AAAA'): None,
-    ('PTR','PTR'): None,
-    ('NS','NS'): None,
-    ('NS','A'): None,
-    ('TXT','TXT'): None,
-    ('SPF','SPF'): None
-  }
-
-
   def dns(self, name, qtype, cnames=None):
     """DNS query.
 

Milter/dsn.py

@@ -5,6 +5,21 @@
 # Send DSNs, do call back verification,
 # and generate DSN messages from a template
 # $Log$
+# Revision 1.21  2011/03/03 05:11:58  customdesigned
+# Release 0.9.4
+#
+# Revision 1.20  2010/10/11 00:29:47  customdesigned
+# Handle multiple recipients.  For CBV or auto whitelist of multiple emails.
+#
+# Revision 1.19  2009/07/02 19:41:12  customdesigned
+# Handle @ in localpart.
+#
+# Revision 1.18  2009/06/10 18:01:59  customdesigned
+# Doxygen updates
+#
+# Revision 1.17  2009/05/20 20:08:44  customdesigned
+# Support non-DSN CBV (non-empty MAIL FROM)
+#
 # Revision 1.16  2007/09/25 01:24:59  customdesigned
 # Allow arbitrary object, not just spf.query like, to provide data for create_msg
 #
@@ -26,7 +41,31 @@
 # Revision 1.10  2006/05/24 20:56:35  customdesigned
 # Remove default templates.  Scrub test.
 #
-
+## @package Milter.dsn
+# Support DSNs and CallBackValidations (CBV).
+#
+# A Delivery Status Notification (bounce) is sent to the envelope
+# sender (original MAIL FROM) with a null MAIL FROM (<>) to notify the
+# original sender # of delays or problems with delivery.  A Callback Validation
+# starts the DSN process, but stops before issuing the DATA command.  The
+# purpose is to check whether the envelope recipient is accepted (and is
+# therefore a valid email).  The null MAIL FROM tells the remote
+# MTA to never reply according to RFC2821 (but some braindead MTAs
+# reply anyway, of course).
+#
+# Milters should cache CBV results and should avoid sending DSNs
+# unless the sender is authenticated somehow (e.g. SPF Pass).  However,
+# when email is quarantined, and is not known to be a forgery, sending a DSN 
+# is better than silently disappearing, and a DSN is better than sending
+# a normal message as notification - because MAIL FROM signing schemes
+# can reject bounces of forged emails.   Whatever you do, don't copy those
+# assinine commercial filters that send a normal message to notify you
+# that some virus is forging your email.
+#
+# <b>DSNs should *only* be sent to MAIL FROM addresses.</b>  Never send
+# a DSN or use a null MAIL FROM with an email address obtained from
+# anywhere else.
+#
 import smtplib
 import socket
 from email.Message import Message
@@ -34,12 +73,25 @@ import Milter
 import time
 import dns
 
+## Send DSN.
+# Try the published MX names in order, rejecting obviously bogus entries
+# (like <code>localhost</code>).
+# @param mailfrom the original sender we are notifying or validating
+# @param receiver the HELO name of the MTA we are sending the DSN on behalf of.
+#	Be sure to send from an IP that matches the HELO.
+# @param msg the DSN message in RFC2822 format, or None for CBV.
+# @param timeout total seconds to wait for a response from an MX
+# @param session Milter.dns.Session object from current incoming mail
+#	session to reuse its cache, or None to create a fresh one.
+# @param ourfrom set to a valid email to send a normal notification from, or
+#	to validate emails not obtained from MAIL FROM.
+# @return None on success or (status_code,msg) on failure.
 def send_dsn(mailfrom,receiver,msg=None,timeout=600,session=None,ourfrom=''):
   """Send DSN.  If msg is None, do callback verification.
      Mailfrom is original sender we are sending DSN or CBV to.
      Receiver is the MTA sending the DSN.
      Return None for success or (code,msg) for failure."""
-  user,domain = mailfrom.split('@')
+  user,domain = mailfrom.rsplit('@',1)
   if not session: session = dns.Session()
   try:
     mxlist = session.dns(domain,'MX')
@@ -73,13 +125,23 @@ def send_dsn(mailfrom,receiver,msg=None,timeout=600,session=None,ourfrom=''):
 	code,resp = smtp.docmd('MAIL FROM: <%s>'%ourfrom)
 	if code != 250:
 	  raise smtplib.SMTPSenderRefused(code, resp, '<%s>'%ourfrom)
-	code,resp = smtp.rcpt(mailfrom)
+        if isinstance(mailfrom,basestring):
+          mailfrom = [mailfrom]
+        badrcpts = {}
+        for rcpt in mailfrom:
+          code,resp = smtp.rcpt(rcpt)
           if code not in (250,251):
-	  return (code,resp)		# permanent error
+            badrcpts[rcpt] = (code,resp)# permanent error
 	smtp.quit()
+        if len(badrcpts) == 1:
+          return badrcpts.values()[0]	# permanent error
+        if badrcpts:
+          return badrcpts
       return None			# success
     except smtplib.SMTPRecipientsRefused,x:
-      return x.recipients[mailfrom]	# permanent error
+      if len(x.recipients) == 1:
+        return x.recipients.values()[0]	# permanent error
+      return x.recipients
     except smtplib.SMTPSenderRefused,x:
       return x.args[:2]			# does not accept DSN
     except smtplib.SMTPDataError,x:
@@ -90,7 +152,7 @@ def send_dsn(mailfrom,receiver,msg=None,timeout=600,session=None,ourfrom=''):
       pass		# MX didn't accept connections, try next one
     except socket.timeout:
       pass		# MX too slow, try next one
-    smtp.close()
+    if hasattr(smtp,'sock'): smtp.close()
     if time.time() > toolate:
       return (450,'No MX response within %f minutes'%(timeout/60.0))
   return (450,'No MX servers available')	# temp error

Milter/dynip.py

@@ -48,9 +48,10 @@ def is_dynip(host,addr):
   True
   """
   if host.startswith('[') and host.endswith(']'):
-    return True
+    return True                                 # no ptr
   if addr:
     if host.find(addr) >= 0: return True
+    if addr.find(':') >= 0: return False        # IP6
     a = addr.split('.')
     ia = map(int,a)
     h = host

Milter/greylist.py

@@ -50,7 +50,7 @@ class Greylist(object):
           # expired
           log.debug('Expired greylist: %s',key)
           r = Record()
-        elif now < r.firstseen + self.greylist_time:
+        elif now < r.firstseen + self.greylist_time + 5:
           # still greylisted
           log.debug('Early greylist: %s',key)
           #r = Record()

Milter/pyip6.py

@@ -0,0 +1,117 @@
+"""Pure Python IP6 parsing and formatting
+
+Copyright (c) 2006 Stuart Gathman <stuart@bmsi.com>
+
+This module is free software, and you may redistribute it and/or modify
+it under the same terms as Python itself, so long as this copyright message
+and disclaimer are retained in their original form.
+"""
+import struct
+#from spf import RE_IP4 
+import re
+PAT_IP4 = r'\.'.join([r'(?:\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])']*4)
+RE_IP4 = re.compile(PAT_IP4+'$')
+
+def inet_ntop(s):
+  """
+  Convert ip6 address to standard hex notation.
+
+  Examples:
+
+  >>> inet_ntop(struct.pack("!HHHHHHHH",0,0,0,0,0,0xFFFF,0x0102,0x0304))
+  '::FFFF:1.2.3.4'
+
+  >>> inet_ntop(struct.pack("!HHHHHHHH",0x1234,0x5678,0,0,0,0,0x0102,0x0304))
+  '1234:5678::102:304'
+
+  >>> inet_ntop(struct.pack("!HHHHHHHH",0,0,0,0x1234,0x5678,0,0x0102,0x0304))
+  '::1234:5678:0:102:304'
+
+  >>> inet_ntop(struct.pack("!HHHHHHHH",0x1234,0x5678,0,0x0102,0x0304,0,0,0))
+  '1234:5678:0:102:304::'
+
+  >>> inet_ntop(struct.pack("!HHHHHHHH",0,0,0,0,0,0,0,0))
+  '::'
+  """
+  # convert to 8 words
+  a = struct.unpack("!HHHHHHHH",s)
+  n = (0,0,0,0,0,0,0,0)	# null ip6
+  if a == n: return '::'
+  # check for ip4 mapped
+  if a[:5] == (0,0,0,0,0) and a[5] in (0,0xFFFF):
+    ip4 = '.'.join([str(i) for i in struct.unpack("!BBBB",s[12:])])
+    if a[5]:
+      return "::FFFF:" + ip4
+    return "::" + ip4
+  # find index of longest sequence of 0
+  for l in (7,6,5,4,3,2,1):
+    e = n[:l]
+    for i in range(9-l):
+      if a[i:i+l] == e:
+	if i == 0:
+	  return ':'+':%x'*(8-l) % a[l:]
+	if i == 8 - l:
+	  return '%x:'*(8-l) % a[:-l] + ':'
+	return '%x:'*i % a[:i] + ':%x'*(8-l-i) % a[i+l:]
+  return "%x:%x:%x:%x:%x:%x:%x:%x" % a
+
+def inet_pton(p):
+  """
+  Convert ip6 standard hex notation to ip6 address.
+
+  Examples:
+
+  >>> struct.unpack('!HHHHHHHH',inet_pton('::'))
+  (0, 0, 0, 0, 0, 0, 0, 0)
+
+  >>> struct.unpack('!HHHHHHHH',inet_pton('::1234'))
+  (0, 0, 0, 0, 0, 0, 0, 4660)
+
+  >>> struct.unpack('!HHHHHHHH',inet_pton('1234::'))
+  (4660, 0, 0, 0, 0, 0, 0, 0)
+
+  >>> struct.unpack('!HHHHHHHH',inet_pton('1234::5678'))
+  (4660, 0, 0, 0, 0, 0, 0, 22136)
+
+  >>> struct.unpack('!HHHHHHHH',inet_pton('::FFFF:1.2.3.4'))
+  (0, 0, 0, 0, 0, 65535, 258, 772)
+
+  >>> struct.unpack('!HHHHHHHH',inet_pton('1.2.3.4'))
+  (0, 0, 0, 0, 0, 65535, 258, 772)
+
+  >>> try: inet_pton('::1.2.3.4.5')
+  ... except ValueError,x: print x
+  ::1.2.3.4.5
+  """
+  if p == '::':
+    return '\0'*16
+  s = p
+  m = RE_IP4.search(s)
+  try:
+      if m:
+	  pos = m.start()
+	  ip4 = [int(i) for i in s[pos:].split('.')]
+	  if not pos:
+	      return struct.pack('!QLBBBB',0,65535,*ip4)
+	  s = s[:pos]+'%x%02x:%x%02x'%tuple(ip4)
+      a = s.split('::')
+      if len(a) == 2:
+	l,r = a
+	if not l:
+	  r = r.split(':')
+	  return struct.pack('!HHHHHHHH',
+	    *[0]*(8-len(r)) + [int(s,16) for s in r])
+	if not r:
+	  l = l.split(':')
+	  return struct.pack('!HHHHHHHH',
+	    *[int(s,16) for s in l] + [0]*(8-len(l)))
+	l = l.split(':')
+	r = r.split(':')
+	return struct.pack('!HHHHHHHH',
+	    *[int(s,16) for s in l] + [0]*(8-len(l)-len(r))
+	    + [int(s,16) for s in r])
+      if len(a) == 1:
+	return struct.pack('!HHHHHHHH',
+	    *[int(s,16) for s in a[0].split(':')])
+  except ValueError: pass
+  raise ValueError,p

Milter/utils.py

@@ -1,3 +1,7 @@
+## @package Milter.utils
+# Miscellaneous functions.
+#
+
 import re
 import struct
 import socket
@@ -7,17 +11,53 @@ from email.Header import decode_header
 #import email.Utils
 import rfc822
 
-ip4re = re.compile(r'^[0-9]*\.[0-9]*\.[0-9]*\.[0-9]*$')
+PAT_IP4 = r'\.'.join([r'(?:\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])']*4)
+ip4re = re.compile(PAT_IP4+'$')
+ip6re = re.compile(                 '(?:%(hex4)s:){6}%(ls32)s$'
+                   '|::(?:%(hex4)s:){5}%(ls32)s$'
+                  '|(?:%(hex4)s)?::(?:%(hex4)s:){4}%(ls32)s$'
+    '|(?:(?:%(hex4)s:){0,1}%(hex4)s)?::(?:%(hex4)s:){3}%(ls32)s$'
+    '|(?:(?:%(hex4)s:){0,2}%(hex4)s)?::(?:%(hex4)s:){2}%(ls32)s$'
+    '|(?:(?:%(hex4)s:){0,3}%(hex4)s)?::%(hex4)s:%(ls32)s$'
+    '|(?:(?:%(hex4)s:){0,4}%(hex4)s)?::%(ls32)s$'
+    '|(?:(?:%(hex4)s:){0,5}%(hex4)s)?::%(hex4)s$'
+    '|(?:(?:%(hex4)s:){0,6}%(hex4)s)?::$'
+  % {
+    'ls32': r'(?:[0-9a-f]{1,4}:[0-9a-f]{1,4}|%s)'%PAT_IP4,
+    'hex4': r'[0-9a-f]{1,4}'
+    }, re.IGNORECASE)
 
 # from spf.py
-def addr2bin(str):
+def addr2bin(s):
-  "Convert a string IPv4 address into an unsigned integer."
+  """Convert a string IPv4 address into an unsigned integer."""
-  return struct.unpack("!L", socket.inet_aton(str))[0]
+  if s.find(':') >= 0:
+    try:
+      return bin2long6(inet_pton(s))
+    except:
+      raise socket.error("Invalid IP6 address: "+s)
+  try:
+    return struct.unpack("!L", socket.inet_aton(s))[0]
+  except socket.error:
+    raise socket.error("Invalid IP4 address: "+s)
+
+def bin2long6(s):
+    """Convert binary IP6 address into an unsigned Python long integer."""
+    h, l = struct.unpack("!QQ", s)
+    return h << 64 | l
+
+if hasattr(socket,'has_ipv6') and socket.has_ipv6:
+    def inet_ntop(s):
+        return socket.inet_ntop(socket.AF_INET6,s)
+    def inet_pton(s):
+        return socket.inet_pton(socket.AF_INET6,s)
+else:
+    from pyip6 import inet_ntop, inet_pton
 
 MASK = 0xFFFFFFFFL
+MASK6 = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFL
 
-def cidr(i,n):
+def cidr(i,n,mask=MASK):
-  return ~(MASK >> n) & MASK & i
+  return ~(mask >> n) & mask & i
 
 def iniplist(ipaddr,iplist):
   """Return whether ip is in cidr list
@@ -27,8 +67,19 @@ def iniplist(ipaddr,iplist):
   True
   >>> iniplist('192.168.0.45',['192.168.0.*'])
   True
+  >>> iniplist('2001:610:779:0:223:6cff:fe9a:9cf3',['127.0.0.1','172.20.1.0/24','2001:610:779::/48'])
+  True
+  >>> iniplist('2G01:610:779:0:223:6cff:fe9a:9cf3',['127.0.0.1','172.20.1.0/24','2001:610:779::/48'])
+  Traceback (most recent call last):
+    ...
+  ValueError: Invalid ip syntax:2G01:610:779:0:223:6cff:fe9a:9cf3
   """
+  if ip4re.match(ipaddr):
     ipnum = addr2bin(ipaddr)
+  elif ip6re.match(ipaddr):
+    ipnum = bin2long6(inet_pton(ipaddr))
+  else:
+    raise ValueError('Invalid ip syntax:'+ipaddr)
   for pat in iplist:
     p = pat.split('/',1)
     if ip4re.match(p[0]):
@@ -38,10 +89,21 @@ def iniplist(ipaddr,iplist):
         n = 32
       if cidr(addr2bin(p[0]),n) == cidr(ipnum,n):
         return True
+    elif ip6re.match(p[0]):
+      if len(p) > 1:
+	n = int(p[1])
+      else:
+        n = 128
+      if cidr(bin2long6(inet_pton(p[0])),n,MASK6) == cidr(ipnum,n,MASK6):
+        return True
     elif fnmatchcase(ipaddr,pat):
       return True
   return False
 
+## Split email into Fullname and address.
+# This replaces <code>email.Utils.parseaddr</code> but fixes
+# some <a href="http://bugs.python.org/issue1025395">tricky test cases</a>.
+#
 def parseaddr(t):
   """Split email into Fullname and address.
 
@@ -91,13 +153,27 @@ def parse_addr(t):
   ['user@bar', 'example.com']
   >>> parse_addr('foo')
   ['foo']
+  >>> parse_addr('@mx.example.com:user@example.com')
+  ['user', 'example.com']
+  >>> parse_addr('@user@example.com')
+  ['@user', 'example.com']
   """
   if t.startswith('<') and t.endswith('>'): t = t[1:-1]
   if t.startswith('"'):
     if t.endswith('"'): return [t[1:-1]]
     pos = t.find('"@')
     if pos > 0: return [t[1:pos],t[pos+2:]]
-  return t.split('@')
+  if t.startswith('@'):
+    try: t = t.split(':',1)[1]
+    except IndexError: pass
+  return t.rsplit('@',1)
+
+## Decode headers gratuitously encoded to hide the content.
+# Spammers often encode headers to obscure the content from
+# spam filters.  This function decodes gratuitously encoded
+# headers.
+# @param val    the raw header value
+# @return the decoded value or the original raw value
 
 def parse_header(val):
   """Decode headers gratuitously encoded to hide the content.
@@ -109,7 +185,7 @@ def parse_header(val):
     for s,enc in h:
       if enc:
         try:
-	  u.append(unicode(s,enc))
+	  u.append(unicode(s,enc,'replace'))
 	except LookupError:
 	  u.append(unicode(s))
       else:
@@ -121,5 +197,6 @@ def parse_header(val):
       except UnicodeError: continue
   except UnicodeDecodeError: pass
   except LookupError: pass
+  except ValueError: pass
   except email.Errors.HeaderParseError: pass
   return val

README

@@ -69,8 +69,7 @@ Not-so-quick Installation
 First install Sendmail.  Make sure you read libmilter/README in the Sendmail
 source directory, and make sure you enable libmilter before you build.  The
 8.11 series had libmilter marked as FFR (For Future Release); 8.12
-officially
+officially supports libmilter, but it's still not built by default.
-supports libmilter, but it's still not built by default.
 
 Install Python, and enable threading in Modules/Setup.
 

doc/mainpage.py

@@ -0,0 +1,53 @@
+## @mainpage Writing Milters in Python
+#
+# At the lowest level, the <code>milter</code> module provides a thin wrapper
+# around the <a href="https://www.milter.org/developers/api/index"> sendmail
+# libmilter API</a>.  This API lets you register callbacks for a number of
+# events in the process of sendmail receiving a message via SMTP.  These
+# events include the initial connection from a MTA, the envelope sender and
+# recipients, the top level mail headers, and the message body.  There are
+# options to mangle all of these components of the message as it passes through
+# the milter.
+# 
+# At the next level, the <code>Milter</code> module (note the case difference)
+# provides a Python friendly object oriented wrapper for the low level API.  To
+# use the Milter module, an application registers a 'factory' to create an
+# object for each connection from a MTA to sendmail.  These connection objects
+# must provide methods corresponding to the libmilter callback events.
+# 
+# Each event method returns a code to tell sendmail whether to proceed with
+# processing the message.  This is a big advantage of milters over other mail
+# filtering systems.  Unwanted mail can be stopped in its tracks at the
+# earliest possible point.
+# 
+# The <code>Milter.Base</code> class provides default implementations for
+# event methods that do nothing, and also provides wrappers for the libmilter
+# methods to mutate the message.  It automatically negotiates with MTA
+# which protocol steps need to be processed by the milter, based on
+# which callback methods are overridden.
+#
+# The <code>Milter.Milter</code> class provides an alternate default
+# implementation that logs the main milter events, but otherwise does nothing.
+# It is provided for compatibility.
+# 
+# The <code>mime</code> module provides a wrapper for the Python email package
+# that fixes some bugs, and simplifies modifying selected parts of a MIME
+# message.
+#
+# @section threading
+#
+# The libmilter library which pymilter wraps 
+# <a href="https://www.milter.org/developers/overview#SignalHandling">handles
+# all signals</a> itself, and expects to be called from a single main thread.
+# It handles SIGTERM, SIGHUP, and SIGINT, mapping the first two to 
+# <a href="https://www.milter.org/developers/api/smfi_stop">smfi_stop</a>
+# and the last to an internal ABORT.
+#
+# If you use python threads or threading modules, then signal handling gets
+# confused.  Threads may still be useful, but you may need to provide an
+# alternate means of causing graceful shutdown.
+#
+# You may find the
+# <a href="http://docs.python.org/release/2.6.6/library/multiprocessing.html">
+# multiprocessing</a> module useful.  It can be a drop-in
+# replacement for threading as illustrated in @ref milter-template.py.

doc/milter.py

@@ -0,0 +1,167 @@
+# Document miltermodule for Doxygen
+#
+
+## @package milter
+#
+# A thin wrapper around libmilter.
+#
+
+## Hold context for a milter connection.
+# Each connection to sendmail creates a new <code>SMFICTX</code> struct within
+# libmilter.  The milter module in turn creates a milterContext
+# tied to the <code>SMFICTX</code> struct via <code>smfi_setpriv</code>
+# to hold a PyThreadState and a user defined Python object for the connection.
+# 
+# Most application interaction with libmilter takes places via 
+# the milterContext object for the connection.  It is passed to
+# callback functions as the first parameter.
+#
+# The <code>Milter</code> module creates a python class for each connection,
+# and converts function callbacks to instance method invocations.
+#
+class milterContext(object):
+  ## Calls <a href="https://www.milter.org/developers/api/smfi_getsymval">smfi_getsymval</a>.
+  def getsymval(self,sym): pass
+  ## Calls <a href="https://www.milter.org/developers/api/smfi_setreply">
+  # smfi_setreply</a> or
+  # <a href="https://www.milter.org/developers/api/smfi_setmlreply">
+  # smfi_setmlreply</a>.
+  # @param rcode SMTP response code
+  # @param xcode extended SMTP response code
+  # @param msg one or more message lines.  If the MTA does not support 
+  #     multiline messages, only the first is used.
+  def setreply(self,rcode,xcode,*msg): pass
+  ## Calls <a href="https://www.milter.org/developers/api/smfi_addheader">smfi_addheader</a>.
+  def addheader(self,name,value,idx=-1): pass
+  ## Calls <a href="https://www.milter.org/developers/api/smfi_chgheader">smfi_chgheader</a>.
+  def chgheader(self,name,idx,value): pass
+  ## Calls <a href="https://www.milter.org/developers/api/smfi_addrcpt">smfi_addrcpt</a>.
+  def addrcpt(self,rcpt,params=None): pass
+  ## Calls <a href="https://www.milter.org/developers/api/smfi_delrcpt">smfi_delrcpt</a>.
+  def delrcpt(self,rcpt): pass
+  ## Calls <a href="https://www.milter.org/developers/api/smfi_replacebody">smfi_replacebody</a>.
+  def replacebody(self,data): pass
+  ## Attach a Python object to this connection context.
+  # @return the old value or None
+  def setpriv(self,priv): pass
+  ## Return the Python object attached to this connection context.
+  def getpriv(self): pass
+  ## Calls <a href="https://www.milter.org/developers/api/smfi_quarantine">smfi_quarantine</a>.
+  def quarantine(self,reason): pass
+  ## Calls <a href="https://www.milter.org/developers/api/smfi_progress">smfi_progress</a>.
+  def progress(self): pass
+  ## Calls <a href="https://www.milter.org/developers/api/smfi_chgfrom">smfi_chgfrom</a>.
+  def chgfrom(self,sender,param=None): pass
+  ## Tell the MTA which macro values we are interested in for a given stage.
+  # Of interest only when you need to squeeze a few more bytes of bandwidth.
+  def setsmlist(self,stage,macrolist): pass
+
+class error(Exception): pass
+
+## Enable optional milter actions.
+# Certain milter actions need to be enabled before calling main()
+# or they throw an exception.  Pymilter enables them all by
+# default (since 0.9.2), but you may wish to disable unneeded
+# actions as an optimization.
+# @param flags Bit or mask of optional actions to enable
+def set_flags(flags): pass
+
+def set_connect_callback(cb): pass
+def set_helo_callback(cb): pass
+def set_envfrom_callback(cb): pass
+def set_envrcpt_callback(cb): pass
+def set_header_callback(cb): pass
+def set_eoh_callback(cb): pass
+def set_body_callback(cb): pass
+def set_abort_callback(cb): pass
+def set_close_callback(cb): pass
+
+## Sets the return code for untrapped Python exceptions during a callback.
+# Must be one of TEMPFAIL,REJECT,CONTINUE
+def set_exception_policy(code): pass
+
+## Register python milter with libmilter.
+# The name we pass is used to identify the milter in the MTA configuration.
+# Callback functions must be set using the set_*_callback() functions before
+# registering the milter.
+# Three additional callbacks are specified as keyword parameters.  These
+# were added by recent versions of libmilter.  The keyword parameters is
+# a nicer way to do it, I think, since it makes clear that you have to do
+# it before registering.  I may move all the callbacks 
+# in the future (perhaps keeping the set functions for compatibility).
+# @param name the milter name by which the MTA finds us
+# @param negotiate the
+#       <a href="https://www.milter.org/developers/api/xxfi_negotiate">
+#       xxfi_negotiate</a> callback, called to negotiate supported
+#       actions, callbacks, and protocol steps.
+# @param unknown the
+#       <a href="https://www.milter.org/developers/api/xxfi_unknown">
+#       xxfi_unknown</a> callback, called when for SMTP commands
+#       not recognized by the MTA. (Extend SMTP in your milter!)
+# @param data the
+#       <a href="https://www.milter.org/developers/api/xxfi_data">
+#       xxfi_data</a> callback, called when the DATA
+#       SMTP command is received.
+def register(name,negotiate=None,unknown=None,data=None): pass
+def opensocket(rmsock): pass
+
+## Transfer control to libmilter.
+# Calls <a href="https://www.milter.org/developers/api/smfi_main">
+#   smfi_main</a>.
+def main(): pass
+
+## Set the libmilter debugging level.
+# <a href="https://www.milter.org/developers/api/smfi_setdbg">smfi_setdbg</a>
+# sets the milter library's internal debugging level to a new level
+# so that code details may be traced. A level of zero turns off debugging. The
+# greater (more positive) the level the more detailed the debugging. Six is the
+# current, highest, useful value.  Must be called before calling main().
+def setdbg(lev): pass
+
+## Set timeout for MTA communication.
+# Calls <a href="https://www.milter.org/developers/api/smfi_settimeout">
+# smfi_settimeout</a>.  Must be called before calling main().
+def settimeout(secs): pass
+
+## Set socket backlog.
+# Calls <a href="https://www.milter.org/developers/api/smfi_setbacklog">
+# smfi_setbacklog</a>.  Must be called before calling main().
+def setbacklog(n): pass
+
+## Set the socket used to communicate with the MTA.
+# The MTA can communicate with the milter by means of a
+# unix, inet, or inet6 socket. By default, a unix domain socket
+# is used.  It must not exist,
+# and sendmail will throw warnings if, eg, the file is under a
+# group or world writable directory.
+# <pre>
+# setconn('unix:/var/run/pythonfilter')
+# setconn('inet:8800') 			# listen on ANY interface
+# setconn('inet:7871@@publichost')	# listen on a specific interface
+# setconn('inet6:8020')
+# </pre>
+def setconn(s): pass
+
+## Stop the milter gracefully.
+def stop(): pass
+
+## Retrieve diagnostic info.
+# Return a tuple with diagnostic info gathered by the milter module.
+# The first two fields are counts of milterContext objects created
+# and deleted.  Additional fields may be added later.
+# @return a tuple of diagnostic data
+def getdiag(): pass
+
+## Retrieve the runtime libmilter version.
+# Return the runtime libmilter version. This can be different
+# from the compile time version when sendmail or libmilter is upgraded
+# after pymilter is compiled.
+# @return a tuple of <code>(major,minor,patchlevel)</code>
+def getversion(): pass
+
+## The compile time libmilter version.
+# Python code might need to deal with pymilter compiled 
+# against various versions of libmilter.  This module constant 
+# contains the contents of the <code>SMFI_VERSION</code> macro when
+# the milter module was compiled.
+VERSION = 0x1000001

makefile

@@ -0,0 +1,15 @@
+web:
+	doxygen
+	rsync -ravK doc/html/ spidey2.bmsi.com:/Public/pymilter
+
+VERSION=0.9.6
+CVSTAG=pymilter-0_9_6
+PKG=pymilter-$(VERSION)
+SRCTAR=$(PKG).tar.gz
+
+$(SRCTAR):
+	cvs export -r$(CVSTAG) -d $(PKG) pymilter
+	tar cvfz $(PKG).tar.gz $(PKG)
+	rm -r $(PKG)
+
+cvstar: $(SRCTAR)

milter-nomix.py

@@ -0,0 +1,79 @@
+## A very simple milter to prevent mixing of internal and external mail.  
+# Internal is defined as using one of a list of internal top level domains.
+#  This code is open-source on the same terms as Python.
+
+import Milter
+import time
+import sys
+from Milter.utils import parse_addr
+
+internal_tlds = ["corp", "personal"]
+
+## Determine if a hostname is internal or not. 
+# True if internal, False otherwise
+def is_internal(hostname):
+    components = hostname.split(".")
+    return components.pop() in internal_tlds:
+
+# Determine if internal and external hosts are mixed based on a list
+# of hostnames
+def are_mixed(hostnames):
+    hostnames_mapped = map(is_internal, hostnames)
+
+    # Num internals
+    num_internal_hosts = hostnames_mapped.count(True)
+
+    # Num externals
+    num_external_hosts = hostnames_mapped.count(False)
+
+    return num_external_hosts >= 1 and num_internal_hosts >= 1
+
+class NoMixMilter(Milter.Base):
+
+  def __init__(self):  # A new instance with each new connection.
+    self.id = Milter.uniqueID()  # Integer incremented with each call.
+
+
+  ##  def envfrom(self,f,*str):
+  @Milter.noreply
+  def envfrom(self, mailfrom, *str):
+    self.mailfrom = mailfrom
+    self.domains = []
+    t = parse_addr(mailfrom)
+    if len(t) > 1:
+      self.domains.append(t[1])
+    else:
+      self.domains.append('local')
+    self.internal = False
+    return Milter.CONTINUE
+
+  ##  def envrcpt(self, to, *str):
+  def envrcpt(self, to, *str):
+    self.R.append(to)
+    t = parse_addr(to)
+    if len(t) > 1:
+      self.domains.append(t[1])
+    else:
+      self.domains.append('local')
+
+    if are_mixed(self.domains):
+      # FIXME: log recipients collected in self.mailfrom and self.R
+      self.setreply('550','5.7.1','Mixing internal and external TLDs')
+      return Milter.REJECT
+        
+    return Milter.CONTINUE
+    
+def main():
+  socketname = "/var/run/nomixsock"
+  timeout = 600
+  # Register to have the Milter factory create instances of your class:
+  Milter.factory = NoMixMilter
+  print "%s milter startup" % time.strftime('%Y%b%d %H:%M:%S')
+  sys.stdout.flush()
+  Milter.runmilter("nomixfilter",socketname,timeout)
+  logq.put(None)
+  bt.join()
+  print "%s nomix milter shutdown" % time.strftime('%Y%b%d %H:%M:%S')
+
+if __name__ == "__main__":
+  main()

milter-template.py

@@ -11,11 +11,18 @@ import Milter
 import StringIO
 import time
 import email
+import sys
 from socket import AF_INET, AF_INET6
-from Milter import parse_addr
+from Milter.utils import parse_addr
+if True:
+  from multiprocessing import Process as Thread, Queue
+else:
+  from threading import Thread
+  from Queue import Queue
 
+logq = Queue(maxsize=4)
 
-class myMilter(Milter.Milter):
+class myMilter(Milter.Base):
 
   def __init__(self):  # A new instance with each new connection.
     self.id = Milter.uniqueID()  # Integer incremented with each call.
@@ -23,6 +30,7 @@ class myMilter(Milter.Milter):
   # each connection runs in its own thread and has its own myMilter
   # instance.  Python code must be thread safe.  This is trivial if only stuff
   # in myMilter instances is referenced.
+  @Milter.noreply
   def connect(self, IPname, family, hostaddr):
     # (self, 'ip068.subnet71.example.com', AF_INET, ('215.183.71.68', 4720) )
     # (self, 'ip6.mxout.example.com', AF_INET6,
@@ -70,28 +78,29 @@ class myMilter(Milter.Milter):
 
 
   ##  def envrcpt(self, to, *str):
-  def envrcpt(self, recipient, *str):
+  @Milter.noreply
+  def envrcpt(self, to, *str):
     rcptinfo = to,Milter.dictfromlist(str)
     self.R.append(rcptinfo)
     
     return Milter.CONTINUE
 
 
+  @Milter.noreply
   def header(self, name, hval):
     self.fp.write("%s: %s\n" % (name,hval))	# add header to buffer
     return Milter.CONTINUE
 
-
+  @Milter.noreply
   def eoh(self):
     self.fp.write("\n")				# terminate headers
     return Milter.CONTINUE
 
-
+  @Milter.noreply
   def body(self, chunk):
     self.fp.write(chunk)
     return Milter.CONTINUE
 
-
   def eom(self):
     self.fp.seek(0)
     msg = email.message_from_file(self.fp)
@@ -101,7 +110,6 @@ class myMilter(Milter.Milter):
     self.addrcpt('<%s>' % 'spy@example.com')
     return Milter.ACCEPT
 
-
   def close(self):
     # always called, even when abort is called.  Clean up
     # any external resources here.
@@ -114,15 +122,25 @@ class myMilter(Milter.Milter):
   ## === Support Functions ===
 
   def log(self,*msg):
-    print "%s [%d]" % (time.strftime('%Y%b%d %H:%M:%S'),self.id),
+    logq.put((msg,self.id,time.time()))
+
+def background():
+  while True:
+    t = logq.get()
+    if not t: break
+    msg,id,ts = t
+    print "%s [%d]" % (time.strftime('%Y%b%d %H:%M:%S',time.localtime(ts)),id),
     # 2005Oct13 02:34:11 [1] msg1 msg2 msg3 ...
     for i in msg: print i,
     print
 
-
 ## ===
     
 def main():
+  bt = Thread(target=background)
+  bt.start()
+  socketname = "/home/stuart/pythonsock"
+  timeout = 600
   # Register to have the Milter factory create instances of your class:
   Milter.factory = myMilter
   flags = Milter.CHGBODY + Milter.CHGHDRS + Milter.ADDHDRS
@@ -132,6 +150,8 @@ def main():
   print "%s milter startup" % time.strftime('%Y%b%d %H:%M:%S')
   sys.stdout.flush()
   Milter.runmilter("pythonfilter",socketname,timeout)
+  logq.put(None)
+  bt.join()
   print "%s bms milter shutdown" % time.strftime('%Y%b%d %H:%M:%S')
 
 if __name__ == "__main__":

miltermodule.c

@@ -35,6 +35,24 @@ $ python setup.py help
      libraries=["milter","smutil","resolv"]
 
  * $Log$
+ * Revision 1.28  2011/06/08 23:13:48  customdesigned
+ * Generate special exception when callback return not int.
+ *
+ * Revision 1.27  2009/07/28 21:45:54  customdesigned
+ * Add getversion() to return runtime version.
+ *
+ * Revision 1.26  2009/07/28 21:08:20  customdesigned
+ * Increment del count.
+ *
+ * Revision 1.25  2009/07/28 20:58:55  customdesigned
+ * getdiag method
+ *
+ * Revision 1.24  2009/06/09 01:54:44  customdesigned
+ * Forgot to initialize optional parameter.
+ *
+ * Revision 1.23  2009/05/29 20:44:58  customdesigned
+ * Typo SMFIP_NO constants.
+ *
  * Revision 1.22  2009/05/29 19:53:36  customdesigned
  * Typo SMFIS_ALL_OPTS
  *
@@ -256,7 +274,6 @@ $ python setup.py help
 #endif
 #endif
 
-
 /* Yes, these are static.  If you need multiple different callbacks, */
 /* it's cleaner to use multiple filters, or convert to OO method calls. */
 static PyObject *connect_callback = NULL;
@@ -269,12 +286,44 @@ static PyObject *body_callback    = NULL;
 static PyObject *eom_callback     = NULL;
 static PyObject *abort_callback   = NULL;
 static PyObject *close_callback   = NULL;
+#ifdef SMFIS_ALL_OPTS
+static PyObject *unknown_callback = NULL;
+static PyObject *data_callback    = NULL;
+static PyObject *negotiate_callback = NULL;
+#endif
+static struct MilterCallback {
+  PyObject **cbp;
+  const char *name;
+} callback_names[] = {
+      { &connect_callback,"connect" },
+      { &helo_callback,"helo" },
+      { &envfrom_callback,"envfrom" },
+      { &envrcpt_callback,"envrcpt" },
+      { &header_callback,"header" },
+      { &eoh_callback,"eoh" },
+      { &body_callback,"body" },
+      { &eom_callback,"eom" },
+      { &abort_callback,"abort" },
+      { &close_callback,"close" },
+#ifdef SMFIS_ALL_OPTS
+      { &unknown_callback,"unknown" },
+      { &data_callback,"data" },
+      { &negotiate_callback,"negotiate" },
+#endif
+      { NULL, NULL }
+    };
 
 staticforward struct smfiDesc description; /* forward declaration */
 
 static PyObject *MilterError;
 /* The interpreter instance that called milter.main */
 static PyInterpreterState *interp;
+typedef struct {
+  unsigned int contextNew;
+  unsigned int contextDel;
+} milter_Diag;
+
+static milter_Diag diag;
 
 staticforward PyTypeObject milter_ContextType;
 
@@ -313,6 +362,7 @@ _get_context(SMFICTX *ctx) {
       PyThreadState_Delete(t);
       return NULL;
     }
+    ++diag.contextNew;
     self->t = t;
     self->ctx = ctx;
     Py_INCREF(Py_None);
@@ -351,6 +401,7 @@ milter_Context_dealloc(PyObject *s) {
   }
   Py_DECREF(self->priv);
   PyObject_DEL(self);
+  ++diag.contextDel;
 }
 
 /* Throw an exception if an smfi call failed, otherwise return PyNone. */
@@ -611,9 +662,23 @@ _generic_wrapper(milter_ContextObject *self, PyObject *cb, PyObject *arglist) {
   result = PyEval_CallObject(cb, arglist);
   Py_DECREF(arglist);
   if (result == NULL) return _report_exception(self);
-  retval = PyInt_AsLong(result);
+  if (!PyInt_Check(result)) {
+    const struct MilterCallback *p;
+    const char *cbname = "milter";
+    char buf[40];
+    Py_DECREF(result);
+    for (p = callback_names; p->cbp; ++p) {
+      if (cb == *p->cbp) {
+        cbname = p->name;
+	break;
+      }
+    }
+    sprintf(buf,"The %s callback must return int",cbname);
+    PyErr_SetString(MilterError,buf);
+    return _report_exception(self);
+  }
+  retval = PyInt_AS_LONG(result);
   Py_DECREF(result);
-  if (PyErr_Occurred()) return _report_exception(self);
   _release_thread(self->t);
   return retval;
 }
@@ -802,10 +867,6 @@ milter_wrap_abort(SMFICTX *ctx) {
 }
 
 #ifdef SMFIS_ALL_OPTS
-static PyObject *unknown_callback = NULL;
-static PyObject *data_callback    = NULL;
-static PyObject *negotiate_callback = NULL;
-
 static int
 milter_wrap_unknown(SMFICTX *ctx, const char *cmd) {
    PyObject *arglist;
@@ -1063,6 +1124,30 @@ milter_stop(PyObject *self, PyObject *args) {
   return _thread_return(t,smfi_stop(), "cannot stop");
 }
 
+static char milter_getdiag__doc__[] =
+"getdiag() -> tuple\n\
+Return a tuple of diagnostic data.  The first two items are context new\n\
+count and context del count.  The rest are yet to be defined.";
+static PyObject *
+milter_getdiag(PyObject *self, PyObject *args) {
+  if (!PyArg_ParseTuple(args, ":getdiag")) return NULL;
+  return Py_BuildValue("(kk)", diag.contextNew,diag.contextDel);
+}
+
+static char milter_getversion__doc__[] =
+"getversion() -> tuple\n\
+Return runtime libmilter version as a tuple of major,minor,patchlevel.";
+static PyObject *
+milter_getversion(PyObject *self, PyObject *args) {
+  unsigned int major, minor, patch;
+  if (!PyArg_ParseTuple(args, ":getversion")) return NULL;
+  if (smfi_version(&major,&minor,&patch) != MI_SUCCESS) {
+    PyErr_SetString(MilterError, "smfi_version failed");
+    return NULL;
+  }
+  return Py_BuildValue("(kkk)", major,minor,patch);
+}
+
 static char milter_getsymval__doc__[] =
 "getsymval(String) -> String\n\
 Returns a symbol's value.  Context-dependent, and unclear from the dox.";
@@ -1188,7 +1273,7 @@ This function can only be called from the EOM callback.";
 static PyObject *
 milter_chgfrom(PyObject *self, PyObject *args) {
   char *sender;
-  char *params;
+  char *params = NULL;
   SMFICTX *ctx;
   PyThreadState *t;
   
@@ -1475,6 +1560,8 @@ static PyMethodDef milter_methods[] = {
    { "setbacklog",           milter_setbacklog,           METH_VARARGS, milter_setbacklog__doc__},
    { "setconn",              milter_setconn,              METH_VARARGS, milter_setconn__doc__},
    { "stop",                 milter_stop,                 METH_VARARGS, milter_stop__doc__},
+   { "getdiag",              milter_getdiag,              METH_VARARGS, milter_getdiag__doc__},
+   { "getversion",           milter_getversion,           METH_VARARGS, milter_getversion__doc__},
    { NULL, NULL }
 };
 

mime.py

@@ -1,4 +1,13 @@
 # $Log$
+# Revision 1.7  2009/06/13 21:15:12  customdesigned
+# Doxygen updates.
+#
+# Revision 1.6  2009/06/09 03:13:13  customdesigned
+# More doxygen docs.
+#
+# Revision 1.5  2005/07/20 14:49:43  customdesigned
+# Handle corrupt and empty ZIP files.
+#
 # Revision 1.4  2005/06/17 01:49:39  customdesigned
 # Handle zip within zip.
 #
@@ -70,8 +79,12 @@
 # with old milter code.
 #
 
-# This module provides a "defang" function to replace naughty attachments
+## @package mime
-# with a warning message.
+# This module provides a "defang" function to replace naughty attachments.
+# 
+# We also provide workarounds for bugs in the email module that comes 
+# with python.  The "bugs" fixed mostly come up only with malformed
+# messages - but that is what you have when dealing with spam.
 
 # Author: Stuart D. Gathman <stuart@bmsi.com>
 # Copyright 2001,2002,2003,2004,2005 Business Management Systems, Inc.
@@ -93,6 +106,8 @@ from email import Errors
 
 from types import ListType,StringType
 
+## Return a list of filenames in a zip file.
+# Embedded zip files are recursively expanded.
 def zipnames(txt):
   fp =  StringIO.StringIO(txt)
   zipf = zipfile.ZipFile(fp,'r')
@@ -103,6 +118,8 @@ def zipnames(txt):
       names += zipnames(zipf.read(nm))
   return names
 
+## Fix multipart handling in email.Generator.
+#
 class MimeGenerator(Generator):
     def _dispatch(self, msg):
         # Get the Content-Type: for the message, then try to dispatch to
@@ -142,21 +159,23 @@ def _unquotevalue(value):
 
 from email.Message import _parseparam
 
-# Enhance email.Message 
+## Enhance email.Message 
-# - Provide a headerchange event for integration with Milter
+#
-#   Headerchange attribute can be assigned a function to be called when
+# Tracks modifications to headers of body or any part independently.
-#   changing headers.  The signature is:
-#	headerchange(msg,name,value) -> None
-# - Track modifications to headers of body or any part independently
 
 class MimeMessage(Message):
   """Version of email.Message.Message compatible with old mime module
   """
   def __init__(self,fp=None,seekable=1):
     Message.__init__(self)
-    self.headerchange = None
     self.submsg = None
     self.modified = False
+  ## @var headerchange
+  # Provide a headerchange event for integration with Milter.
+  #   The headerchange attribute can be assigned a function to be called when
+  #   changing headers.  The signature is:
+  #   headerchange(msg,name,value) -> None
+    self.headerchange = None
 
   def get_param(self, param, failobj=None, header='content-type', unquote=True):
     val = Message.get_param(self,param,failobj,header,unquote)

pymilter.spec

@@ -1,32 +1,24 @@
-# EL 3,4,5 supported, set to 0 for Fedora
+%define __python python2.6
-%define el4 1
+%define pythonbase python26
-%define dist .el4
-%if 0%{?el3} || 0%{?el4}
-%define __python python2.4
-%endif
 
 %define libdir %{_libdir}/pymilter
 %{!?python_sitearch: %define python_sitearch %(%{__python} -c "from distutils.sysconfig import get_python_lib; print get_python_lib(1)")}
-%define pythonbase %(basename %{__python})
 
 Summary: Python interface to sendmail milter API
-Name: pymilter
+Name: %{pythonbase}-pymilter
-Version: 0.9.2
+Version: 0.9.6
-Release: 3%{dist}
+Release: 1%{dist}
-Source: http://downloads.sourceforge.net/pymilter/%{name}-%{version}.tar.gz
+Source: http://downloads.sourceforge.net/pymilter/pymilter-%{version}.tar.gz
 License: GPLv2+
 Group: Development/Libraries
 BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root
 Url: http://www.bmsi.com/python/milter.html
-Requires: %{pythonbase} >= 2.4, sendmail >= 8.13
+# python-2.6.4 gets RuntimeError: not holding the import lock
-%if 0%{?el3} || 0%{?el4}
+Requires: %{pythonbase} >= 2.6.5, sendmail >= 8.13
-# Need python2.4 specific pydns, not the version for system python
+# Need python2.6 specific pydns, not the version for system python
-Requires: pydns
+Requires: %{pythonbase}-pydns
-%else
 # Needed for callbacks, not a core function but highly useful for milters
-Requires: python-pydns
+BuildRequires: ed, %{pythonbase}-devel, sendmail-devel >= 8.13
-%endif
-BuildRequires: ed, %{pythonbase}-devel >= 2.4, sendmail-devel >= 8.13
 
 %description
 This is a python extension module to enable python scripts to
@@ -35,7 +27,7 @@ modules provide for navigating and modifying MIME parts, sending
 DSNs, and doing CBV.
 
 %prep
-%setup -q
+%setup -q -n pymilter-%{version}
 
 %build
 env CFLAGS="$RPM_OPT_FLAGS" %{__python} setup.py build
@@ -83,6 +75,25 @@ chmod a+x $RPM_BUILD_ROOT%{libdir}/start.sh
 rm -rf $RPM_BUILD_ROOT
 
 %changelog
+* Sat Feb 25 2012 Stuart Gathman <stuart@bmsi.com> 0.9.6-1
+- Raise ValueError on unescaped '%' passed to setreply
+- Grace time at end of Greylist window
+
+* Fri Aug 19 2011 Stuart Gathman <stuart@bmsi.com> 0.9.5-1
+- Print milter.error for invalid callback return type.
+  (Since stacktrace is empty, the TypeError exception is confusing.)
+- Fix milter-template.py
+- Tweak Milter.utils.addr2bin and Milter.dynip to handle IP6
+
+* Wed Mar 02 2010 Stuart Gathman <stuart@bmsi.com> 0.9.4-1
+- Handle IP6 in Milter.utils.iniplist()
+- python-2.6
+
+* Thu Jul 02 2009 Stuart Gathman <stuart@bmsi.com> 0.9.3-1
+- Handle source route in Milter.utils.parse_addr()
+- Fix default arg in chgfrom.
+- Disable negotiate callback for libmilter < 8.14.3 (1,0,1)
+
 * Tue Jun 02 2009 Stuart Gathman <stuart@bmsi.com> 0.9.2-3
 - Change result of @noreply callbacks to NOREPLY when so negotiated.
 

setup.cfg

@@ -1,5 +1,5 @@
 [bdist_rpm]
-python=python2.4
+python=python2.6
 doc_files=README NEWS TODO
 packager=Stuart D. Gathman <stuart@bmsi.com>
 release=1

setup.py

@@ -2,6 +2,9 @@ import os
 import sys
 from distutils.core import setup, Extension
 
+if sys.version < '2.6.5':
+  sys.exit('ERROR: Sorry, python 2.6.5 is required for this module.')
+
 # FIXME: on some versions of sendmail, smutil is renamed to sm.
 # On slackware and debian, leave it out entirely.  It depends
 # on how libmilter was built by the sendmail package.
@@ -9,15 +12,8 @@ from distutils.core import setup, Extension
 libs = ["milter"]
 libdirs = ["/usr/lib/libmilter"]    # needed for Debian
 
-# patch distutils if it can't cope with the "classifiers" or
-# "download_url" keywords
-if sys.version < '2.2.3':
-  from distutils.dist import DistributionMetadata
-  DistributionMetadata.classifiers = None
-  DistributionMetadata.download_url = None
-
 # NOTE: importing Milter to obtain version fails when milter.so not built
-setup(name = "pymilter", version = '0.9.2',
+setup(name = "pymilter", version = '0.9.6',
 	description="Python interface to sendmail milter API",
 	long_description="""\
 This is a python extension module to enable python scripts to

start.sh

@@ -1,13 +1,16 @@
 #!/bin/sh
 appname="$1"
 script="${2:-${appname}}"
-datadir="/var/log/milter"
+datadir="/var/lib/milter"
+logdir="/var/log/milter"
 piddir="/var/run/milter"
 libdir="/usr/lib/pymilter"
 python="python2.4"
-exec >>${datadir}/${appname}.log 2>&1
+exec >>${logdir}/${appname}.log 2>&1
 if test -s ${datadir}/${script}.py; then
-  cd ${datadir} # use version in log dir if it exists for debugging
+  cd ${datadir} # use version in data dir if it exists for debugging
+elif test -s ${logdir}/${script}.py; then
+  cd ${logdir} # use version in log dir if it exists for debugging
 else
   cd ${libdir}
 fi

testmime.py

@@ -1,4 +1,7 @@
 # $Log$
+# Revision 1.4  2005/07/20 14:49:44  customdesigned
+# Handle corrupt and empty ZIP files.
+#
 # Revision 1.3  2005/06/17 01:49:39  customdesigned
 # Handle zip within zip.
 #
@@ -26,6 +29,7 @@ import socket
 import StringIO
 import email
 import sys
+import Milter
 from email import Errors
 
 samp1_txt1 = """Dear Agent 1
@@ -146,6 +150,31 @@ class MimeTestCase(unittest.TestCase):
     # test zip within zip
     self.testDefang('ziploop',1,'stuart@bmsi.com.zip')
 
+  def _chk_name(self,name):
+    self.filename = name
+
+  def _chk_attach(self,msg):
+    "Filter attachments by content."
+    # check for bad extensions
+    mime.check_name(msg,ckname=self._chk_name,scan_zip=True)
+    # remove scripts from HTML
+    mime.check_html(msg)
+    # don't let a tricky virus slip one past us
+    msg = msg.get_submsg()
+    if isinstance(msg,email.Message.Message):
+      return mime.check_attachments(msg,self._chk_attach)
+    return Milter.CONTINUE
+
+  def testCheckAttach(self,fname="test1"):
+    # test1 contains a very long filename
+    msg = mime.message_from_file(open('test/'+fname,'r'))
+    mime.defang(msg,scan_zip=True)
+    self.failIf(msg.ismodified())
+    msg = mime.message_from_file(open('test/tmpytgcE5.fail','r'))
+    rc = mime.check_attachments(msg,self._chk_attach)
+    self.assertEquals(self.filename,"7501'S FOR TWO GOLDEN SOURCES SHIPMENTS FOR TAX & DUTY PURPOSES ONLY.PDF")
+    self.assertEquals(rc,Milter.CONTINUE)
+
   def testHTML(self,fname=""):
     result = StringIO.StringIO()
     filter = mime.HTMLScriptFilter(result)

testsample.py

@@ -7,6 +7,7 @@ import StringIO
 
 class TestMilter(sample.sampleMilter):
 
+  _protocol = 0
   def __init__(self):
     self.logfp = open("test/milter.log","a")