diff options
Diffstat (limited to 'src/mailman/app/docs/lifecycle.rst')
| -rw-r--r-- | src/mailman/app/docs/lifecycle.rst | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/src/mailman/app/docs/lifecycle.rst b/src/mailman/app/docs/lifecycle.rst new file mode 100644 index 000000000..4a8b732e1 --- /dev/null +++ b/src/mailman/app/docs/lifecycle.rst @@ -0,0 +1,156 @@ +================================= +Application level list life cycle +================================= + +The low-level way to create and delete a mailing list is to use the +``IListManager`` interface. This interface simply adds or removes the +appropriate database entries to record the list's creation. + +There is a higher level interface for creating and deleting mailing lists +which performs additional tasks such as: + + * validating the list's posting address (which also serves as the list's + fully qualified name); + * ensuring that the list's domain is registered; + * applying all matching styles to the new list; + * creating and assigning list owners; + * notifying watchers of list creation; + * creating ancillary artifacts (such as the list's on-disk directory) + + +Posting address validation +========================== + +If you try to use the higher-level interface to create a mailing list with a +bogus posting address, you get an exception. + + >>> create_list('not a valid address') + Traceback (most recent call last): + ... + InvalidEmailAddressError: not a valid address + +If the posting address is valid, but the domain has not been registered with +Mailman yet, you get an exception. + + >>> create_list('test@example.org') + Traceback (most recent call last): + ... + BadDomainSpecificationError: example.org + + +Creating a list applies its styles +================================== + +Start by registering a test style. +:: + + >>> from zope.interface import implements + >>> from mailman.interfaces.styles import IStyle + >>> class TestStyle(object): + ... implements(IStyle) + ... name = 'test' + ... priority = 10 + ... def apply(self, mailing_list): + ... # Just does something very simple. + ... mailing_list.msg_footer = 'test footer' + ... def match(self, mailing_list, styles): + ... # Applies to any test list + ... if 'test' in mailing_list.fqdn_listname: + ... styles.append(self) + + >>> config.style_manager.register(TestStyle()) + +Using the higher level interface for creating a list, applies all matching +list styles. + + >>> mlist_1 = create_list('test_1@example.com') + >>> print mlist_1.fqdn_listname + test_1@example.com + >>> print mlist_1.msg_footer + test footer + + +Creating a list with owners +=========================== + +You can also specify a list of owner email addresses. If these addresses are +not yet known, they will be registered, and new users will be linked to them. +However the addresses are not verified. + + >>> owners = [ + ... 'aperson@example.com', + ... 'bperson@example.com', + ... 'cperson@example.com', + ... 'dperson@example.com', + ... ] + >>> mlist_2 = create_list('test_2@example.com', owners) + >>> print mlist_2.fqdn_listname + test_2@example.com + >>> print mlist_2.msg_footer + test footer + >>> dump_list(address.email for address in mlist_2.owners.addresses) + aperson@example.com + bperson@example.com + cperson@example.com + dperson@example.com + +None of the owner addresses are verified. + + >>> any(address.verified_on is not None + ... for address in mlist_2.owners.addresses) + False + +However, all addresses are linked to users. + + >>> # The owners have no names yet + >>> len(list(mlist_2.owners.users)) + 4 + +If you create a mailing list with owner addresses that are already known to +the system, they won't be created again. +:: + + >>> from mailman.interfaces.usermanager import IUserManager + >>> from zope.component import getUtility + >>> user_manager = getUtility(IUserManager) + + >>> user_a = user_manager.get_user('aperson@example.com') + >>> user_b = user_manager.get_user('bperson@example.com') + >>> user_c = user_manager.get_user('cperson@example.com') + >>> user_d = user_manager.get_user('dperson@example.com') + >>> user_a.real_name = 'Anne Person' + >>> user_b.real_name = 'Bart Person' + >>> user_c.real_name = 'Caty Person' + >>> user_d.real_name = 'Dirk Person' + + >>> mlist_3 = create_list('test_3@example.com', owners) + >>> dump_list(user.real_name for user in mlist_3.owners.users) + Anne Person + Bart Person + Caty Person + Dirk Person + + +Deleting a list +=============== + +Removing a mailing list deletes the list, all its subscribers, and any related +artifacts. +:: + + >>> from mailman.app.lifecycle import remove_list + >>> remove_list(mlist_2.fqdn_listname, mlist_2, True) + + >>> from mailman.interfaces.listmanager import IListManager + >>> from zope.component import getUtility + >>> print getUtility(IListManager).get('test_2@example.com') + None + +We should now be able to completely recreate the mailing list. + + >>> mlist_2a = create_list('test_2@example.com', owners) + >>> dump_list(address.email for address in mlist_2a.owners.addresses) + aperson@example.com + bperson@example.com + cperson@example.com + dperson@example.com |