mailman/docs/lifecycle.txt

   1 Application level list lifecycle
   2 --------------------------------
   3
   4 The low-level way to create and delete a mailing list is to use the
   5 IListManager interface.  This interface simply adds or removes the appropriate
   6 database entries to record the list's creation.
   7
   8 There is a higher level interface for creating and deleting mailing lists
   9 which performs additional tasks such as:
  10
  11  * validating the list's posting address (which also serves as the list's
  12    fully qualified name);
  13  * ensuring that the list's domain is registered;
  14  * applying all matching styles to the new list;
  15  * creating and assigning list owners;
  16  * notifying watchers of list creation;
  17  * creating ancillary artifacts (such as the list's on-disk directory)
  18
  19     >>> from mailman.app.lifecycle import create_list
  20
  21
  22 Posting address validation
  23 --------------------------
  24
  25 If you try to use the higher-level interface to create a mailing list with a
  26 bogus posting address, you get an exception.
  27
  28     >>> create_list('not a valid address')
  29     Traceback (most recent call last):
  30     ...
  31     InvalidEmailAddress: 'not a valid address'
  32
  33 If the posting address is valid, but the domain has not been registered with
  34 Mailman yet, you get an exception.
  35
  36     >>> create_list('test@example.org')
  37     Traceback (most recent call last):
  38     ...
  39     BadDomainSpecificationError: example.org
  40
  41
  42 Creating a list applies its styles
  43 ----------------------------------
  44
  45 Start by registering a test style.
  46
  47     >>> from zope.interface import implements
  48     >>> from mailman.interfaces.styles import IStyle
  49     >>> class TestStyle(object):
  50     ...     implements(IStyle)
  51     ...     name = 'test'
  52     ...     priority = 10
  53     ...     def apply(self, mailing_list):
  54     ...         # Just does something very simple.
  55     ...         mailing_list.msg_footer = u'test footer'
  56     ...     def match(self, mailing_list, styles):
  57     ...         # Applies to any test list
  58     ...         if 'test' in mailing_list.fqdn_listname:
  59     ...             styles.append(self)
  60
  61     >>> from mailman.core.styles import style_manager
  62     >>> style_manager.register(TestStyle())
  63
  64 Using the higher level interface for creating a list, applies all matching
  65 list styles.
  66
  67     >>> mlist_1 = create_list(u'test_1@example.com')
  68     >>> mlist_1.fqdn_listname
  69     u'test_1@example.com'
  70     >>> mlist_1.msg_footer
  71     u'test footer'
  72
  73
  74 Creating a list with owners
  75 ---------------------------
  76
  77 You can also specify a list of owner email addresses.  If these addresses are
  78 not yet known, they will be registered, and new users will be linked to them.
  79 However the addresses are not verified.
  80
  81     >>> owners = [u'aperson@example.com', u'bperson@example.com',
  82     ...           u'cperson@example.com', u'dperson@example.com']
  83     >>> mlist_2 = create_list(u'test_2@example.com', owners)
  84     >>> mlist_2.fqdn_listname
  85     u'test_2@example.com'
  86     >>> mlist_2.msg_footer
  87     u'test footer'
  88     >>> sorted(addr.address for addr in mlist_2.owners.addresses)
  89     [u'aperson@example.com', u'bperson@example.com',
  90      u'cperson@example.com', u'dperson@example.com']
  91
  92 None of the owner addresses are verified.
  93
  94     >>> any(addr.verified_on is not None for addr in mlist_2.owners.addresses)
  95     False
  96
  97 However, all addresses are linked to users.
  98
  99     >>> # The owners have no names yet
 100     >>> len(list(mlist_2.owners.users))
 101     4
 102
 103 If you create a mailing list with owner addresses that are already known to
 104 the system, they won't be created again.
 105
 106     >>> usermgr = config.db.user_manager
 107     >>> user_a = usermgr.get_user(u'aperson@example.com')
 108     >>> user_b = usermgr.get_user(u'bperson@example.com')
 109     >>> user_c = usermgr.get_user(u'cperson@example.com')
 110     >>> user_d = usermgr.get_user(u'dperson@example.com')
 111     >>> user_a.real_name = u'Anne Person'
 112     >>> user_b.real_name = u'Bart Person'
 113     >>> user_c.real_name = u'Caty Person'
 114     >>> user_d.real_name = u'Dirk Person'
 115
 116     >>> mlist_3 = create_list(u'test_3@example.com', owners)
 117     >>> sorted(user.real_name for user in mlist_3.owners.users)
 118     [u'Anne Person', u'Bart Person', u'Caty Person', u'Dirk Person']
 119
 120
 121 Removing a list
 122 ---------------
 123
 124 Removing a mailing list deletes the list, all its subscribers, and any related
 125 artifacts.
 126
 127     >>> from mailman import Utils
 128     >>> from mailman.app.lifecycle import remove_list
 129     >>> remove_list(mlist_2.fqdn_listname, mlist_2, True)
 130     >>> Utils.list_exists(u'test_2@example.com')
 131     False
 132
 133 We should now be able to completely recreate the mailing list.
 134
 135     >>> mlist_2a = create_list(u'test_2@example.com', owners)
 136     >>> sorted(addr.address for addr in mlist_2a.owners.addresses)
 137     [u'aperson@example.com', u'bperson@example.com',
 138      u'cperson@example.com', u'dperson@example.com']