Using the IListManager interface
================================

The IListManager is how you create, delete, and retrieve mailing list
objects.  The Mailman system instantiates an IListManager for you based on the
configuration variable MANAGERS_INIT_FUNCTION.  The instance is accessible
on the global config object.

    >>> from mailman.configuration import config
    >>> from mailman.interfaces import IListManager
    >>> listmgr = config.db.list_manager
    >>> IListManager.providedBy(listmgr)
    True


Creating a mailing list
-----------------------

Creating the list returns the newly created IMailList object.

    >>> from mailman.interfaces import IMailingList
    >>> mlist = listmgr.create(u'_xtest@example.com')
    >>> IMailingList.providedBy(mlist)
    True

All lists with identities have a short name, a host name, and a fully
qualified listname.  This latter is what uniquely distinguishes the mailing
list to the system.

    >>> mlist.list_name
    u'_xtest'
    >>> mlist.host_name
    u'example.com'
    >>> mlist.fqdn_listname
    u'_xtest@example.com'

If you try to create a mailing list with the same name as an existing list,
you will get an exception.

    >>> mlist_dup = listmgr.create(u'_xtest@example.com')
    Traceback (most recent call last):
    ...
    ListAlreadyExistsError: _xtest@example.com


Deleting a mailing list
-----------------------

Use the list manager to delete a mailing list.

    >>> listmgr.delete(mlist)
    >>> sorted(listmgr.names)
    []

After deleting the list, you can create it again.

    >>> mlist = listmgr.create(u'_xtest@example.com')
    >>> mlist.fqdn_listname
    u'_xtest@example.com'


Retrieving a mailing list
-------------------------

When a mailing list exists, you can ask the list manager for it and you will
always get the same object back.

    >>> mlist_2 = listmgr.get(u'_xtest@example.com')
    >>> mlist_2 is mlist
    True

If you try to get a list that doesn't existing yet, you get None.

    >>> print listmgr.get(u'_xtest_2@example.com')
    None


Iterating over all mailing lists
--------------------------------

Once you've created a bunch of mailing lists, you can use the list manager to
iterate over either the list objects, or the list names.

    >>> mlist_3 = listmgr.create(u'_xtest_3@example.com')
    >>> mlist_4 = listmgr.create(u'_xtest_4@example.com')
    >>> sorted(listmgr.names)
    [u'_xtest@example.com', u'_xtest_3@example.com', u'_xtest_4@example.com']
    >>> sorted(m.fqdn_listname for m in listmgr.mailing_lists)
    [u'_xtest@example.com', u'_xtest_3@example.com', u'_xtest_4@example.com']
