src/mailman/app/docs/lifecycle.rst

   1 =================================
   2 Application level list life cycle
   3 =================================
   4
   5 The low-level way to create and delete a mailing list is to use the
   6 ``IListManager`` interface.  This interface simply adds or removes the
   7 appropriate database entries to record the list's creation.
   8
   9 There is a higher level interface for creating and deleting mailing lists
  10 which performs additional tasks such as:
  11
  12  * validating the list's posting address (which also serves as the list's
  13    fully qualified name);
  14  * ensuring that the list's domain is registered;
  15  * :ref:`applying a list style <list-creation-styles>` to the new list;
  16  * creating and assigning list owners;
  17  * notifying watchers of list creation;
  18  * creating ancillary artifacts (such as the list's on-disk directory)
  19
  20
  21 Creating a list with owners
  22 ===========================
  23
  24 You can also specify a list of owner email addresses.  If these addresses are
  25 not yet known, they will be registered, and new users will be linked to them.
  26 ::
  27
  28     >>> owners = [
  29     ...     'aperson@example.com',
  30     ...     'bperson@example.com',
  31     ...     'cperson@example.com',
  32     ...     'dperson@example.com',
  33     ...     ]
  34
  35     >>> from mailman.app.lifecycle import create_list
  36     >>> ant = create_list('ant@example.com', owners)
  37     >>> from mailman.testing.documentation import dump_list
  38     >>> dump_list(address.email for address in ant.owners.addresses)
  39     aperson@example.com
  40     bperson@example.com
  41     cperson@example.com
  42     dperson@example.com
  43
  44 None of the owner addresses are verified.
  45
  46     >>> any(address.verified_on is not None
  47     ...     for address in ant.owners.addresses)
  48     False
  49
  50 However, all addresses are linked to users.
  51
  52     >>> from mailman.interfaces.usermanager import IUserManager
  53     >>> from zope.component import getUtility
  54     >>> user_manager = getUtility(IUserManager)
  55     >>> for address in owners:
  56     ...     user = user_manager.get_user(address)
  57     ...     print(int(user.user_id.int), list(user.addresses)[0])
  58     1 aperson@example.com
  59     2 bperson@example.com
  60     3 cperson@example.com
  61     4 dperson@example.com
  62
  63 If you create a mailing list with owner addresses that are already known to
  64 the system, they won't be created again.
  65
  66     >>> bee = create_list('bee@example.com', owners)
  67     >>> from operator import attrgetter
  68     >>> for user in sorted(bee.owners.users, key=attrgetter('user_id')):
  69     ...     print(int(user.user_id.int), list(user.addresses)[0])
  70     1 aperson@example.com
  71     2 bperson@example.com
  72     3 cperson@example.com
  73     4 dperson@example.com
  74
  75
  76 Deleting a list
  77 ===============
  78
  79 Removing a mailing list deletes the list, all its subscribers, and any related
  80 artifacts.
  81 ::
  82
  83     >>> from mailman.app.lifecycle import remove_list
  84     >>> remove_list(bee)
  85
  86     >>> from mailman.interfaces.listmanager import IListManager
  87     >>> print(getUtility(IListManager).get('bee@example.com'))
  88     None
  89
  90 We should now be able to completely recreate the mailing list.
  91
  92     >>> buzz = create_list('bee@example.com', owners)
  93     >>> dump_list(address.email for address in bee.owners.addresses)
  94     aperson@example.com
  95     bperson@example.com
  96     cperson@example.com
  97     dperson@example.com