Convert failing test_message.py to doctests bounces.txt and message.txt, which

of course now succeed.

Rename Bouncer.py's BounceMessage() method to bounce_message() and remove the
'msgdata' parameter, which wasn't being used.  Change the RejectNotice
exception class to expose .notice directly, as there's no reason for this to
be an accessor or property.

Move the coverage.py installation to the install-packages target instead of
the install-other target, so that it only gets installed once the pythonlib
directory is created.

2 files changed, 164 insertions, 0 deletions

diff --git a/Mailman/docs/bounces.txt b/Mailman/docs/bounces.txt
new file mode 100644
index 000000000..c224abcad
--- /dev/null
+++ b/Mailman/docs/bounces.txt
@@ -0,0 +1,112 @@
+Bounces
+=======
+
+An important feature of Mailman is automatic bounce process.
+
+XXX Many more converted tests go here.
+
+
+Bounces, or message rejection
+-----------------------------
+
+Mailman can also bounce messages back to the original sender.  This is
+essentially equivalent to rejecting the message with notification.  Mailing
+lists can bounce a message with an optional error message.
+
+    >>> from Mailman.configuration import config
+    >>> from Mailman.database import flush
+    >>> mlist = config.list_manager.create('_xtest@example.com')
+    >>> mlist.preferred_language = u'en'
+    >>> flush()
+
+Any message can be bounced.
+
+    >>> from email import message_from_string
+    >>> from Mailman.Message import Message
+    >>> msg = message_from_string("""\
+    ... To: _xtest@example.com
+    ... From: aperson@example.com
+    ... Subject: Something important
+    ...
+    ... I sometimes say something important.
+    ... """, Message)
+
+Bounce a message by passing in the original message, and an optional error
+message.  The bounced message ends up in the virgin queue, awaiting sending
+to the original messageauthor.
+
+    >>> from Mailman.Queue.Switchboard import Switchboard
+    >>> switchboard = Switchboard(config.VIRGINQUEUE_DIR)
+    >>> mlist.bounce_message(msg)
+    >>> len(switchboard.files)
+    1
+    >>> filebase = switchboard.files[0]
+    >>> qmsg, qmsgdata = switchboard.dequeue(filebase)
+    >>> switchboard.finish(filebase)
+    >>> print qmsg.as_string()
+    Subject: Something important
+    From: _xtest-owner@example.com
+    To: aperson@example.com
+    MIME-Version: 1.0
+    Content-Type: multipart/mixed; boundary="..."
+    Message-ID: ...
+    Date: ...
+    Precedence: bulk
+    <BLANKLINE>
+    --...
+    Content-Type: text/plain; charset="us-ascii"
+    MIME-Version: 1.0
+    Content-Transfer-Encoding: 7bit
+    <BLANKLINE>
+    [No bounce details are available]
+    --...
+    Content-Type: message/rfc822
+    MIME-Version: 1.0
+    <BLANKLINE>
+    To: _xtest@example.com
+    From: aperson@example.com
+    Subject: Something important
+    <BLANKLINE>
+    I sometimes say something important.
+    <BLANKLINE>
+    --...--
+
+An error message can be given when the message is bounced, and this will be
+included in the payload of the text/plain part.  The error message must be
+passed in as an instance of a RejectMessage exception.
+
+    >>> from Mailman.Errors import RejectMessage
+    >>> error = RejectMessage("This wasn't very important after all.")
+    >>> mlist.bounce_message(msg, error)
+    >>> len(switchboard.files)
+    1
+    >>> filebase = switchboard.files[0]
+    >>> qmsg, qmsgdata = switchboard.dequeue(filebase)
+    >>> switchboard.finish(filebase)
+    >>> print qmsg.as_string()
+    Subject: Something important
+    From: _xtest-owner@example.com
+    To: aperson@example.com
+    MIME-Version: 1.0
+    Content-Type: multipart/mixed; boundary="..."
+    Message-ID: ...
+    Date: ...
+    Precedence: bulk
+    <BLANKLINE>
+    --...
+    Content-Type: text/plain; charset="us-ascii"
+    MIME-Version: 1.0
+    Content-Transfer-Encoding: 7bit
+    <BLANKLINE>
+    This wasn't very important after all.
+    --...
+    Content-Type: message/rfc822
+    MIME-Version: 1.0
+    <BLANKLINE>
+    To: _xtest@example.com
+    From: aperson@example.com
+    Subject: Something important
+    <BLANKLINE>
+    I sometimes say something important.
+    <BLANKLINE>
+    --...--
diff --git a/Mailman/docs/message.txt b/Mailman/docs/message.txt
new file mode 100644
index 000000000..9cca6ea96
--- /dev/null
+++ b/Mailman/docs/message.txt
@@ -0,0 +1,52 @@
+Messages
+========
+
+Mailman has its own Message classes, derived from the standard
+email.message.Message class, but providing additional useful methods.
+
+
+User notifications
+------------------
+
+When Mailman needs to send a message to a user, it creates a UserNotification
+instance, and then calls the .send() method on this object.  This method
+requires a mailing list instance.
+
+    >>> from Mailman.configuration import config
+    >>> from Mailman.database import flush
+    >>> mlist = config.list_manager.create('_xtest@example.com')
+    >>> mlist.preferred_language = u'en'
+    >>> flush()
+
+The UserNotification constructor takes the recipient address, the sender
+address, an optional subject, optional body text, and optional language.
+
+    >>> from Mailman.Message import UserNotification
+    >>> msg = UserNotification(
+    ...     'aperson@example.com',
+    ...     '_xtest@example.com',
+    ...     'Something you need to know',
+    ...     'I needed to tell you this.')
+    >>> msg.send(mlist)
+
+The message will end up in the virgin queue.
+
+    >>> from Mailman.Queue.Switchboard import Switchboard
+    >>> switchboard = Switchboard(config.VIRGINQUEUE_DIR)
+    >>> len(switchboard.files)
+    1
+    >>> filebase = switchboard.files[0]
+    >>> qmsg, qmsgdata = switchboard.dequeue(filebase)
+    >>> switchboard.finish(filebase)
+    >>> print qmsg.as_string()
+    MIME-Version: 1.0
+    Content-Type: text/plain; charset="us-ascii"
+    Content-Transfer-Encoding: 7bit
+    Subject: Something you need to know
+    From: _xtest@example.com
+    To: aperson@example.com
+    Message-ID: ...
+    Date: ...
+    Precedence: bulk
+    <BLANKLINE>
+    I needed to tell you this.