1 files changed, 88 insertions, 0 deletions
diff --git a/src/mailman/docs/listmanager.txt b/src/mailman/docs/listmanager.txt
new file mode 100644
index 000000000..830f6d962
--- /dev/null
+++ b/src/mailman/docs/listmanager.txt
@@ -0,0 +1,88 @@
+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.interfaces.listmanager 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.mailinglist 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']