DandelionNStuff/pymilter
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Copy sendmail-devel libmilter api into documention, since milter.org is gone.

Browse Source 
Conflicts:
	Milter/__init__.py
	doc/milter.py
	makefile
This commit is contained in:
Stuart Gathman
2015-06-24 03:41:38 +00:00
committed by Scott Kitterman
parent d35ed40edf
commit 74b8b1ae19
5 changed files with 67 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Milter/__init__.py
+24 -15
View File
@@ -259,7 +259,7 @@ class Base(object):
## Defined by subclasses to write log messages. ## Defined by subclasses to write log messages.
def log(self,*msg): pass def log(self,*msg): pass
## Called for each connection to the MTA. Called by the ## Called for each connection to the MTA. Called by the
# <a href="https://www.milter.org/developers/api/xxfi_connect"> # <a href="milter_api/xxfi_connect.html">
# xxfi_connect</a> callback. # xxfi_connect</a> callback.
# The <code>hostname</code> provided by the local MTA is either # 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 PTR name or the IP in the form "[1.2.3.4]" if no PTR is available.
@@ -296,7 +296,7 @@ class Base(object):
@nocallback @nocallback
def hello(self,hostname): return CONTINUE def hello(self,hostname): return CONTINUE
## Called when the SMTP client says MAIL FROM. Called by the ## Called when the SMTP client says MAIL FROM. Called by the
# <a href="https://www.milter.org/developers/api/xxfi_envfrom"> # <a href="milter_api/xxfi_envfrom.html">
# xxfi_envfrom</a> callback. # xxfi_envfrom</a> callback.
# Returning REJECT rejects the message, but not the connection. # Returning REJECT rejects the message, but not the connection.
# The sender is the "envelope" from as defined by # The sender is the "envelope" from as defined by
@@ -307,7 +307,7 @@ class Base(object):
@nocallback @nocallback
def envfrom(self,f,*str): return CONTINUE def envfrom(self,f,*str): return CONTINUE
## Called when the SMTP client says RCPT TO. Called by the ## Called when the SMTP client says RCPT TO. Called by the
# <a href="https://www.milter.org/developers/api/xxfi_envrcpt"> # <a href="milter_api/xxfi_envrcpt.html">
# xxfi_envrcpt</a> callback. # xxfi_envrcpt</a> callback.
# Returning REJECT rejects the current recipient, not the entire message. # Returning REJECT rejects the current recipient, not the entire message.
# The recipient is the "envelope" recipient as defined by # The recipient is the "envelope" recipient as defined by
@@ -373,7 +373,7 @@ class Base(object):
return p return p
## Negotiate milter protocol options. Called by the ## Negotiate milter protocol options. Called by the
# <a href="https://www.milter.org/developers/api/xxfi_negotiate"> # <a href="milter_api/xxfi_negotiate.html">
# xffi_negotiate</a> callback. This is an advanced callback, # xffi_negotiate</a> callback. This is an advanced callback,
# do not override unless you know what you are doing. Most # do not override unless you know what you are doing. Most
# negotiation can be done simply by using the supplied # negotiation can be done simply by using the supplied
@@ -404,7 +404,7 @@ class Base(object):
## Return the value of an MTA macro. Sendmail macro names ## Return the value of an MTA macro. Sendmail macro names
# are either single chars (e.g. "j") or multiple chars enclosed # are either single chars (e.g. "j") or multiple chars enclosed
# in braces (e.g. "{auth_type}"). Macro names are MTA dependent. # in braces (e.g. "{auth_type}"). Macro names are MTA dependent.
# See <a href="https://www.milter.org/developers/api/smfi_getsymval"> # See <a href="milter_api/smfi_getsymval.html">
# smfi_getsymval</a> for default sendmail macros. # smfi_getsymval</a> for default sendmail macros.
# @param sym the macro name # @param sym the macro name
def getsymval(self,sym): def getsymval(self,sym):
@@ -416,8 +416,17 @@ class Base(object):
# must be doubled, or libmilter will silently ignore the setreply. # 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 # 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, # head scratching. What will <i>really</i> irritate you, however,
# is that if you carefully double any '%', your message will be # is that if you carefully double any '%%', your message will be
# sent - but with the '%' still doubled! # sent - but with the '%%' still doubled!
# See <a href="milter_api/smfi_setreply.html">
# smfi_setreply</a> for more information.
# @param rcode The three-digit (RFC 821/2821) SMTP reply code as a string.
# rcode cannot be None, and <b>must be a valid 4XX or 5XX reply code</b>.
# @param xcode The extended (RFC 1893/2034) reply code. If xcode is None,
# no extended code is used. Otherwise, xcode must conform to RFC 1893/2034.
# @param msg The text part of the SMTP reply. If msg is None,
# an empty message is used.
# @param ml Optional additional message lines.
def setreply(self,rcode,xcode=None,msg=None,*ml): def setreply(self,rcode,xcode=None,msg=None,*ml):
for m in (msg,)+ml: for m in (msg,)+ml:
if 1 in [len(s)&1 for s in R.findall(m)]: if 1 in [len(s)&1 for s in R.findall(m)]:
@@ -440,7 +449,7 @@ class Base(object):
# Milter methods which can only be called from eom callback. # Milter methods which can only be called from eom callback.
## Add a mail header field. ## Add a mail header field.
# Calls <a href="https://www.milter.org/developers/api/smfi_addheader"> # Calls <a href="milter_api/smfi_addheader.html">
# smfi_addheader</a>. # smfi_addheader</a>.
# The <code>Milter.ADDHDRS</code> action flag must be set. # The <code>Milter.ADDHDRS</code> action flag must be set.
# #
@@ -454,7 +463,7 @@ class Base(object):
return self._ctx.addheader(field,value,idx) return self._ctx.addheader(field,value,idx)
## Change the value of a mail header field. ## Change the value of a mail header field.
# Calls <a href="https://www.milter.org/developers/api/smfi_chgheader"> # Calls <a href="milter_api/smfi_chgheader.html">
# smfi_chgheader</a>. # smfi_chgheader</a>.
# The <code>Milter.CHGHDRS</code> action flag must be set. # The <code>Milter.CHGHDRS</code> action flag must be set.
# #
@@ -468,7 +477,7 @@ class Base(object):
return self._ctx.chgheader(field,idx,value) return self._ctx.chgheader(field,idx,value)
## Add a recipient to the message. ## Add a recipient to the message.
# Calls <a href="https://www.milter.org/developers/api/smfi_addrcpt"> # Calls <a href="milter_api/smfi_addrcpt.html">
# smfi_addrcpt</a>. # smfi_addrcpt</a>.
# If no corresponding mail header is added, this is like a Bcc. # 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 # The syntax of the recipient is the same as used in the SMTP
@@ -488,7 +497,7 @@ class Base(object):
raise DisabledAction("ADDRCPT_PAR") raise DisabledAction("ADDRCPT_PAR")
return self._ctx.addrcpt(rcpt,params) return self._ctx.addrcpt(rcpt,params)
## Delete a recipient from the message. ## Delete a recipient from the message.
# Calls <a href="https://www.milter.org/developers/api/smfi_delrcpt"> # Calls <a href="milter_api/smfi_delrcpt.html">
# smfi_delrcpt</a>. # smfi_delrcpt</a>.
# The recipient should match one passed to the envrcpt callback. # The recipient should match one passed to the envrcpt callback.
# The <code>Milter.DELRCPT</code> action flag must be set. # The <code>Milter.DELRCPT</code> action flag must be set.
@@ -501,7 +510,7 @@ class Base(object):
return self._ctx.delrcpt(rcpt) return self._ctx.delrcpt(rcpt)
## Replace the message body. ## Replace the message body.
# Calls <a href="https://www.milter.org/developers/api/smfi_replacebody"> # Calls <a href="milter_api/smfi_replacebody.html">
# smfi_replacebody</a>. # smfi_replacebody</a>.
# The entire message body must be replaced. # The entire message body must be replaced.
# Call repeatedly with blocks of data until the entire body is transferred. # Call repeatedly with blocks of data until the entire body is transferred.
@@ -515,7 +524,7 @@ class Base(object):
return self._ctx.replacebody(body) return self._ctx.replacebody(body)
## Change the SMTP envelope sender address. ## Change the SMTP envelope sender address.
# Calls <a href="https://www.milter.org/developers/api/smfi_chgfrom"> # Calls <a href="milter_api/smfi_chgfrom.html">
# smfi_chgfrom</a>. # smfi_chgfrom</a>.
# The syntax of the sender is that same as used in the SMTP # The syntax of the sender is that same as used in the SMTP
# MAIL FROM command (and as delivered to the envfrom callback), # MAIL FROM command (and as delivered to the envfrom callback),
@@ -532,7 +541,7 @@ class Base(object):
return self._ctx.chgfrom(sender,params) return self._ctx.chgfrom(sender,params)
## Quarantine the message. ## Quarantine the message.
# Calls <a href="https://www.milter.org/developers/api/smfi_quarantine"> # Calls <a href="milter_api/smfi_quarantine.html">
# smfi_quarantine</a>. # smfi_quarantine</a>.
# When quarantined, a message goes into the mailq as if to be delivered, # When quarantined, a message goes into the mailq as if to be delivered,
# but delivery is deferred until the message is unquarantined. # but delivery is deferred until the message is unquarantined.
@@ -546,7 +555,7 @@ class Base(object):
return self._ctx.quarantine(reason) return self._ctx.quarantine(reason)
## Tell the MTA to wait a bit longer. ## Tell the MTA to wait a bit longer.
# Calls <a href="https://www.milter.org/developers/api/smfi_progress"> # Calls <a href="milter_api/smfi_progress.html">
# smfi_progress</a>. # smfi_progress</a>.
# Resets timeouts in the MTA that detect a "hung" milter. # Resets timeouts in the MTA that detect a "hung" milter.
def progress(self): def progress(self):
doc/mainpage.py
+3 -3
View File
@@ -1,7 +1,7 @@
## @mainpage Writing Milters in Python ## @mainpage Writing Milters in Python
# #
# At the lowest level, the <code>milter</code> module provides a thin wrapper # 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 # around the <a href="milter_api/index.html"> sendmail
# libmilter API</a>. This API lets you register callbacks for a number of # 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 in the process of sendmail receiving a message via SMTP. These
# events include the initial connection from a MTA, the envelope sender and # events include the initial connection from a MTA, the envelope sender and
@@ -37,10 +37,10 @@
# @section threading # @section threading
# #
# The libmilter library which pymilter wraps # The libmilter library which pymilter wraps
# <a href="https://www.milter.org/developers/overview#SignalHandling">handles # <a href="milter_overview#SignalHandling">handles
# all signals</a> itself, and expects to be called from a single main thread. # 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 # It handles SIGTERM, SIGHUP, and SIGINT, mapping the first two to
# <a href="https://www.milter.org/developers/api/smfi_stop">smfi_stop</a> # <a href="milter_api/smfi_stop.html">smfi_stop</a>
# and the last to an internal ABORT. # and the last to an internal ABORT.
# #
# If you use python threads or threading modules, then signal handling gets # If you use python threads or threading modules, then signal handling gets
doc/milter.py
+36 -20
View File
@@ -20,41 +20,47 @@
# and converts function callbacks to instance method invocations. # and converts function callbacks to instance method invocations.
# #
class milterContext(object): class milterContext(object):
## Calls <a href="https://www.milter.org/developers/api/smfi_getsymval">smfi_getsymval</a>. ## Calls <a href="milter_api/smfi_getsymval.html">smfi_getsymval</a>.
def getsymval(self,sym): pass def getsymval(self,sym): pass
## Calls <a href="https://www.milter.org/developers/api/smfi_setreply"> ## Calls <a href="milter_api/smfi_setreply.html">
# smfi_setreply</a> or # smfi_setreply</a> or
# <a href="https://www.milter.org/developers/api/smfi_setmlreply"> # <a href="milter_api/smfi_setmlreply.html">
# smfi_setmlreply</a>. # smfi_setmlreply</a>.
# @param rcode SMTP response code # @param rcode SMTP response code
# @param xcode extended SMTP response code # @param xcode extended SMTP response code
# @param msg one or more message lines. If the MTA does not support # @param msg one or more message lines. If the MTA does not support
# multiline messages, only the first is used. # multiline messages, only the first is used.
def setreply(self,rcode,xcode,*msg): pass def setreply(self,rcode,xcode,*msg): pass
## Calls <a href="https://www.milter.org/developers/api/smfi_addheader">smfi_addheader</a>. ## Calls <a href="milter_api/smfi_addheader.html">smfi_addheader</a>.
def addheader(self,name,value,idx=-1): pass def addheader(self,name,value,idx=-1): pass
## Calls <a href="https://www.milter.org/developers/api/smfi_chgheader">smfi_chgheader</a>. ## Calls <a href="milter_api/smfi_chgheader.html">smfi_chgheader</a>.
def chgheader(self,name,idx,value): pass def chgheader(self,name,idx,value): pass
## Calls <a href="https://www.milter.org/developers/api/smfi_addrcpt">smfi_addrcpt</a>. ## Calls <a href="milter_api/smfi_addrcpt.html">smfi_addrcpt</a>.
def addrcpt(self,rcpt,params=None): pass def addrcpt(self,rcpt,params=None): pass
## Calls <a href="https://www.milter.org/developers/api/smfi_delrcpt">smfi_delrcpt</a>. ## Calls <a href="milter_api/smfi_delrcpt.html">smfi_delrcpt</a>.
def delrcpt(self,rcpt): pass def delrcpt(self,rcpt): pass
## Calls <a href="https://www.milter.org/developers/api/smfi_replacebody">smfi_replacebody</a>. ## Calls <a href="milter_api/smfi_replacebody.html">smfi_replacebody</a>.
def replacebody(self,data): pass def replacebody(self,data): pass
## Attach a Python object to this connection context. ## Attach a Python object to this connection context.
# @return the old value or None # @return the old value or None
def setpriv(self,priv): pass def setpriv(self,priv): pass
## Return the Python object attached to this connection context. ## Return the Python object attached to this connection context.
def getpriv(self): pass def getpriv(self): pass
## Calls <a href="https://www.milter.org/developers/api/smfi_quarantine">smfi_quarantine</a>. ## Calls <a href="milter_api/smfi_quarantine.html">smfi_quarantine</a>.
def quarantine(self,reason): pass def quarantine(self,reason): pass
## Calls <a href="https://www.milter.org/developers/api/smfi_progress">smfi_progress</a>. ## Calls <a href="milter_api/smfi_progress.html">smfi_progress</a>.
def progress(self): pass def progress(self): pass
## Calls <a href="https://www.milter.org/developers/api/smfi_chgfrom">smfi_chgfrom</a>. ## Calls <a href="milter_api/smfi_chgfrom.html">smfi_chgfrom</a>.
def chgfrom(self,sender,param=None): pass def chgfrom(self,sender,param=None): pass
## Tell the MTA which macro values we are interested in for a given stage. ## 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. # Of interest only when you need to squeeze a few more bytes of bandwidth.
def setsmlist(self,stage,macrolist): pass # It may only be called from the negotiate callback.
# The protocol stages are
# M_CONNECT, M_HELO, M_ENVFROM, M_ENVRCPT, M_DATA, M_EOM, M_EOH.
# Calls <a href="milter_api/smfi_setsymlist.html">smfi_setsymlist</a>.
# @param stage protocol stage in which the macro list should be used
# @param macrolist a space separated list of macro names
def setsymlist(self,stage,macrolist): pass
class error(Exception): pass class error(Exception): pass
@@ -91,40 +97,50 @@ def set_exception_policy(code): pass
# in the future (perhaps keeping the set functions for compatibility). # in the future (perhaps keeping the set functions for compatibility).
# @param name the milter name by which the MTA finds us # @param name the milter name by which the MTA finds us
# @param negotiate the # @param negotiate the
# <a href="https://www.milter.org/developers/api/xxfi_negotiate"> # <a href="milter_api/xxfi_negotiate.html">
# xxfi_negotiate</a> callback, called to negotiate supported # xxfi_negotiate</a> callback, called to negotiate supported
# actions, callbacks, and protocol steps. # actions, callbacks, and protocol steps.
# @param unknown the # @param unknown the
# <a href="https://www.milter.org/developers/api/xxfi_unknown"> # <a href="milter_api/xxfi_unknown.html">
# xxfi_unknown</a> callback, called when for SMTP commands # xxfi_unknown</a> callback, called when for SMTP commands
# not recognized by the MTA. (Extend SMTP in your milter!) # not recognized by the MTA. (Extend SMTP in your milter!)
# @param data the # @param data the
# <a href="https://www.milter.org/developers/api/xxfi_data"> # <a href="milter_api/xxfi_data.html">
# xxfi_data</a> callback, called when the DATA # xxfi_data</a> callback, called when the DATA
# SMTP command is received. # SMTP command is received.
def register(name,negotiate=None,unknown=None,data=None): pass def register(name,negotiate=None,unknown=None,data=None): pass
## Attempt to create the socket used to communicate with the MTA.
# milter.opensocket() attempts to create the socket specified previously by a
# call to milter.setconn() which will be the interface between MTAs and the
# %milter. This allows the calling application to ensure that the socket can be
# created. If this is not called, milter.main() will do so implicitly.
# Calls <a href="milter_api/smfi_opensocket.html">
# smfi_opensocket</a>. While not documented for libmilter, my experiments
# indicate that you must call register() before calling opensocket().
# @param rmsock Try to remove an existing unix domain socket if true.
def opensocket(rmsock): pass def opensocket(rmsock): pass
## Transfer control to libmilter. ## Transfer control to libmilter.
# Calls <a href="https://www.milter.org/developers/api/smfi_main"> # Calls <a href="milter_api/smfi_main.html">
# smfi_main</a>. # smfi_main</a>.
def main(): pass def main(): pass
## Set the libmilter debugging level. ## Set the libmilter debugging level.
# <a href="https://www.milter.org/developers/api/smfi_setdbg">smfi_setdbg</a> # <a href="milter_api/smfi_setdbg.html">smfi_setdbg</a>
# sets the milter library's internal debugging level to a new level # 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 # 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 # greater (more positive) the level the more detailed the debugging. Six is the
# current, highest, useful value. Must be called before calling main(). # current, highest, useful value. Must be called before calling main().
def setdbg(lev): pass def setdbg(lev): pass
## Set timeout for MTA communication. ## Set timeout for MTA communication.
# Calls <a href="https://www.milter.org/developers/api/smfi_settimeout"> # Calls <a href="milter_api/smfi_settimeout.html">
# smfi_settimeout</a>. Must be called before calling main(). # smfi_settimeout</a>. Must be called before calling main().
def settimeout(secs): pass def settimeout(secs): pass
## Set socket backlog. ## Set socket backlog.
# Calls <a href="https://www.milter.org/developers/api/smfi_setbacklog"> # Calls <a href="milter_api/smfi_setbacklog.html">
# smfi_setbacklog</a>. Must be called before calling main(). # smfi_setbacklog</a>. Must be called before calling main().
def setbacklog(n): pass def setbacklog(n): pass
makefile
+3 -1
View File
@@ -1,6 +1,8 @@
web: web:
doxygen doxygen
rsync -ravK doc/html/ spidey2.bmsi.com:/Public/pymilter test -L doc/html/milter_api || ln -sf /usr/share/doc/sendmail-devel-* doc/html/milter_api
rsync -ravKk doc/html/ spidey2.bmsi.com:/Public/pymilter
cd doc/html; zip -r ../../doc .
VERSION=0.9.6 VERSION=0.9.6
CVSTAG=pymilter-0_9_6 CVSTAG=pymilter-0_9_6
milter-template.py
+1 -1
View File
@@ -1,6 +1,6 @@
## To roll your own milter, create a class that extends Milter. ## To roll your own milter, create a class that extends Milter.
# See the pymilter project at http://bmsi.com/python/milter.html # See the pymilter project at http://bmsi.com/python/milter.html
# based on Sendmail's milter API http://www.milter.org/milter_api/api.html # based on Sendmail's milter API
# This code is open-source on the same terms as Python. # This code is open-source on the same terms as Python.
## Milter calls methods of your class at milter events. ## Milter calls methods of your class at milter events.