1 files changed, 113 insertions, 0 deletions
diff --git a/src/mailman/docs/messagestore.txt b/src/mailman/docs/messagestore.txt
new file mode 100644
index 000000000..6e04568c5
--- /dev/null
+++ b/src/mailman/docs/messagestore.txt
@@ -0,0 +1,113 @@
+The message store
+=================
+
+The message store is a collection of messages keyed off of Message-ID and
+X-Message-ID-Hash headers.  Either of these values can be combined with the
+message's List-Archive header to create a globally unique URI to the message
+object in the internet facing interface of the message store.  The
+X-Message-ID-Hash is the Base32 SHA1 hash of the Message-ID.
+
+    >>> store = config.db.message_store
+
+If you try to add a message to the store which is missing the Message-ID
+header, you will get an exception.
+
+    >>> msg = message_from_string("""\
+    ... Subject: An important message
+    ...
+    ... This message is very important.
+    ... """)
+    >>> store.add(msg)
+    Traceback (most recent call last):
+    ...
+    ValueError: Exactly one Message-ID header required
+
+However, if the message has a Message-ID header, it can be stored.
+
+    >>> msg['Message-ID'] = '<87myycy5eh.fsf@uwakimon.sk.tsukuba.ac.jp>'
+    >>> store.add(msg)
+    'AGDWSNXXKCWEILKKNYTBOHRDQGOX3Y35'
+    >>> print msg.as_string()
+    Subject: An important message
+    Message-ID: <87myycy5eh.fsf@uwakimon.sk.tsukuba.ac.jp>
+    X-Message-ID-Hash: AGDWSNXXKCWEILKKNYTBOHRDQGOX3Y35
+    <BLANKLINE>
+    This message is very important.
+    <BLANKLINE>
+
+
+Finding messages
+----------------
+
+There are several ways to find a message given either the Message-ID or
+X-Message-ID-Hash headers.  In either case, if no matching message is found,
+None is returned.
+
+    >>> print store.get_message_by_id(u'nothing')
+    None
+    >>> print store.get_message_by_hash(u'nothing')
+    None
+
+Given an existing Message-ID, the message can be found.
+
+    >>> message = store.get_message_by_id(msg['message-id'])
+    >>> print message.as_string()
+    Subject: An important message
+    Message-ID: <87myycy5eh.fsf@uwakimon.sk.tsukuba.ac.jp>
+    X-Message-ID-Hash: AGDWSNXXKCWEILKKNYTBOHRDQGOX3Y35
+    <BLANKLINE>
+    This message is very important.
+    <BLANKLINE>
+
+Similarly, we can find messages by the X-Message-ID-Hash:
+
+    >>> message = store.get_message_by_hash(msg['x-message-id-hash'])
+    >>> print message.as_string()
+    Subject: An important message
+    Message-ID: <87myycy5eh.fsf@uwakimon.sk.tsukuba.ac.jp>
+    X-Message-ID-Hash: AGDWSNXXKCWEILKKNYTBOHRDQGOX3Y35
+    <BLANKLINE>
+    This message is very important.
+    <BLANKLINE>
+
+
+Iterating over all messages
+---------------------------
+
+The message store provides a means to iterate over all the messages it
+contains.
+
+    >>> messages = list(store.messages)
+    >>> len(messages)
+    1
+    >>> print messages[0].as_string()
+    Subject: An important message
+    Message-ID: <87myycy5eh.fsf@uwakimon.sk.tsukuba.ac.jp>
+    X-Message-ID-Hash: AGDWSNXXKCWEILKKNYTBOHRDQGOX3Y35
+    <BLANKLINE>
+    This message is very important.
+    <BLANKLINE>
+
+
+Deleting messages from the store
+--------------------------------
+
+You delete a message from the storage service by providing the Message-ID for
+the message you want to delete.  If you try to delete a Message-ID that isn't
+in the store, you get an exception.
+
+    >>> store.delete_message(u'nothing')
+    Traceback (most recent call last):
+    ...
+    LookupError: nothing
+
+But if you delete an existing message, it really gets deleted.
+
+    >>> message_id = message['message-id']
+    >>> store.delete_message(message_id)
+    >>> list(store.messages)
+    []
+    >>> print store.get_message_by_id(message_id)
+    None
+    >>> print store.get_message_by_hash(message['x-message-id-hash'])
+    None