Several internal improvements:

* New events:
  - ConfirmationNeededEvent is triggered when a pendable requiring
    confirmation is created.  This allows us to define an event handler for
    this event which sends the user notification.
  - SubscriptionEvent is triggered when a member is added to a mailing list.
    This lets us define an event handler which sends the welcome message.
* send_welcome_message() now takes a member parameter instead of an address,
  which lets us directly access the member's delivery mode and user display
  name (if the member has a user, which it might not in some cases).
* Use the list id in the pendable record instead of the list name for
  robustness (the latter can change but the former is permanent).
* Test more registration conditions.
* In the bin/runner command line switch handling, default `verbose` to None
  instead of False.  This makes it work better with nose's -E switch (log to
  stderr).
* In call_api(), if a POST, PUT, or PATCH method is used and data is None,
  encode the empty dictionary; seems like the behavior of urlencode() has
  changed, so this is safer.
* Fix style and pyflakes warnings.

1 files changed, 24 insertions, 0 deletions

diff --git a/src/mailman/interfaces/registrar.py b/src/mailman/interfaces/registrar.py
index 28a245d37..8a77ca8f6 100644
--- a/src/mailman/interfaces/registrar.py
+++ b/src/mailman/interfaces/registrar.py
@@ -26,6 +26,7 @@ from __future__ import absolute_import, unicode_literals
 
 __metaclass__ = type
 __all__ = [
+    'ConfirmationNeededEvent',
     'IRegistrar',
     ]
 
@@ -34,6 +35,29 @@ from zope.interface import Interface
 
 
 
+class ConfirmationNeededEvent:
+    """Triggered when an address needs confirmation.
+
+    Addresses must be verified before they can receive messages or post to
+    mailing list.  When an address is registered with Mailman, via the
+    `IRegistrar` interface, an `IPendable` is created which represents the
+    pending registration.  This pending registration is stored in the
+    database, keyed by a token.  Then this event is triggered.
+
+    There may be several ways to confirm an email address.  On some sites,
+    registration may immediately produce a verification, e.g. because it is on
+    a known intranet.  Or verification may occur via external database lookup
+    (e.g. LDAP).  On most public mailing lists, a mail-back confirmation is
+    sent to the address, and only if they reply to the mail-back, or click on
+    an embedded link, is the registered address confirmed.
+    """
+    def __init__(self, mlist, pendable, token):
+        self.mlist = mlist
+        self.pendable = pendable
+        self.token = token
+
+
+
 class IRegistrar(Interface):
     """Interface for registering and verifying email addresses and users.