Convert ToArchive tests to doctests and do a minimal amount of handler module

cleanup (really, not much was necessary).

1 files changed, 141 insertions, 0 deletions

diff --git a/Mailman/docs/archives.txt b/Mailman/docs/archives.txt
new file mode 100644
index 000000000..682ee8777
--- /dev/null
+++ b/Mailman/docs/archives.txt
@@ -0,0 +1,141 @@
+Archives
+========
+
+Updating the archives with posted messages is handled by a separate queue,
+which allows for better memory management and prevents blocking the main
+delivery processes while messages are archived.  This also allows external
+archivers to work in a separate process from the main Mailman delivery
+processes.
+
+    >>> from Mailman.Handlers.ToArchive import process
+    >>> from Mailman.Message import Message
+    >>> from Mailman.Queue.Switchboard import Switchboard
+    >>> from Mailman.configuration import config
+    >>> from Mailman.database import flush
+    >>> from email import message_from_string
+    >>> mlist = config.list_manager.create('_xtest@example.com')
+    >>> mlist.preferred_language = 'en'
+    >>> flush()
+    >>> switchboard = Switchboard(config.ARCHQUEUE_DIR)
+
+A helper function.
+
+    >>> def clear():
+    ...     for filebase in switchboard.files:
+    ...         msg, msgdata = switchboard.dequeue(filebase)
+    ...         switchboard.finish(filebase)
+
+
+The purpose of the ToArchive handler is to make a simple decision as to
+whether the message should get archived and if so, to drop the message in the
+archiving queue.  Really the most important things are to determine when a
+message should /not/ get archived.
+
+For example, no digests should ever get archived.
+
+    >>> mlist.archive = True
+    >>> flush()
+    >>> msg = message_from_string("""\
+    ... Subject: A sample message
+    ...
+    ... A message of great import.
+    ... """, Message)
+    >>> process(mlist, msg, dict(isdigest=True))
+    >>> switchboard.files
+    []
+
+If the mailing list is not configured to archive, then even regular deliveries
+won't be archived.
+
+    >>> mlist.archive = False
+    >>> flush()
+    >>> process(mlist, msg, {})
+    >>> switchboard.files
+    []
+
+There are two de-facto standards for a message to indicate that it does not
+want to be archived.  We've seen both in the wild so both are supported.  The
+X-No-Archive: header can be used to indicate that the message should not be
+archived.  Confusingly, this header's value is actually ignored.
+
+    >>> mlist.archive = True
+    >>> flush()
+    >>> msg = message_from_string("""\
+    ... Subject: A sample message
+    ... X-No-Archive: YES
+    ...
+    ... A message of great import.
+    ... """, Message)
+    >>> process(mlist, msg, dict(isdigest=True))
+    >>> switchboard.files
+    []
+
+Even a 'no' value will stop the archiving of the message.
+
+    >>> msg = message_from_string("""\
+    ... Subject: A sample message
+    ... X-No-Archive: No
+    ...
+    ... A message of great import.
+    ... """, Message)
+    >>> process(mlist, msg, dict(isdigest=True))
+    >>> switchboard.files
+    []
+
+Another header that's been observed is the X-Archive: header.  Here, the
+header's case folded value must be 'no' in order to prevent archiving.
+
+    >>> msg = message_from_string("""\
+    ... Subject: A sample message
+    ... X-Archive: No
+    ...
+    ... A message of great import.
+    ... """, Message)
+    >>> process(mlist, msg, dict(isdigest=True))
+    >>> switchboard.files
+    []
+
+But if the value is 'yes', then the message will be archived.
+
+    >>> msg = message_from_string("""\
+    ... Subject: A sample message
+    ... X-Archive: Yes
+    ...
+    ... A message of great import.
+    ... """, Message)
+    >>> process(mlist, msg, {})
+    >>> len(switchboard.files)
+    1
+    >>> filebase = switchboard.files[0]
+    >>> qmsg, qdata = switchboard.dequeue(filebase)
+    >>> switchboard.finish(filebase)
+    >>> print qmsg.as_string()
+    Subject: A sample message
+    X-Archive: Yes
+    <BLANKLINE>
+    A message of great import.
+    <BLANKLINE>
+    >>> sorted(qdata.items())
+    [('_parsemsg', False), ('received_time', ...), ('version', 3)]
+
+Without either archiving header, and all other things being the same, the
+message will get archived.
+
+    >>> msg = message_from_string("""\
+    ... Subject: A sample message
+    ...
+    ... A message of great import.
+    ... """, Message)
+    >>> process(mlist, msg, {})
+    >>> len(switchboard.files)
+    1
+    >>> filebase = switchboard.files[0]
+    >>> qmsg, qdata = switchboard.dequeue(filebase)
+    >>> switchboard.finish(filebase)
+    >>> print qmsg.as_string()
+    Subject: A sample message
+    <BLANKLINE>
+    A message of great import.
+    <BLANKLINE>
+    >>> sorted(qdata.items())
+    [('_parsemsg', False), ('received_time', ...), ('version', 3)]