[Checkins] SVN: Sandbox/trollfot/grokcore.messages/src/grokcore/messages/README.txt Add some tests containing API description and description on what's

[Uli Fouquet]

Log message for revision 109528:
  Add some tests containing API description and description on what's
  going on during startup.
  

Changed:
  U   Sandbox/trollfot/grokcore.messages/src/grokcore/messages/README.txt

-=-
Modified: Sandbox/trollfot/grokcore.messages/src/grokcore/messages/README.txt
===================================================================
--- Sandbox/trollfot/grokcore.messages/src/grokcore/messages/README.txt	2010-03-01 01:59:48 UTC (rev 109527)
+++ Sandbox/trollfot/grokcore.messages/src/grokcore/messages/README.txt	2010-03-01 02:00:29 UTC (rev 109528)
@@ -1,5 +1,233 @@
-=================
 grokcore.messages
-=================
+*****************
 
-TODO.
+This package provides integration of `z3c.flashmessage`_ for a grok
+setup. This means taking care of:
+
+* Registering a global message receiver with the component
+  architechture.
+
+* Registering by default a global session-based message source named
+  ``session``.
+
+* Optionally (if including ``ram.zcml``) registering a global RAM
+  stored message source named ``ram``.
+
+* Providing components to make use of global message receivers and
+  sources.
+
+For details about what kind of messages we are talking about here,
+please see the `z3c.flashmessage`_ documentation.
+
+.. contents::
+
+
+Setting up ``grokcore.messages``
+================================
+
+When being grokked, ``grokcore.message`` registers
+
+* a global session message source named ``session``
+
+* a global message receiver.
+
+Grokking of this package happens when the local ``configure.zcml`` is
+executed. In standard Grok-based packages this often happens
+automatically.
+
+One can, of course, also grok the package manually:
+
+  >>> import grokcore.component as grok
+  >>> grok.testing.grok('grokcore.messages')
+
+This setups a global message receiver:
+
+  >>> from z3c.flashmessage.interfaces import IMessageReceiver
+  >>> from zope.component import getUtility
+  >>> getUtility(IMessageReceiver)
+  <z3c.flashmessage.receiver.GlobalMessageReceiver object at 0x...>
+
+It also setups a session-based message source named ``session``:
+
+  >>> from z3c.flashmessage.interfaces import IMessageSource
+  >>> getUtility(IMessageSource, name=u'session')
+  <z3c.flashmessage.sources.SessionMessageSource object at 0x...>
+
+We provide also a RAM-stored message source that can be enabled by
+including ``ram.zcml`` and is not registered by default:
+
+  >>> getUtility(IMessageSource, name=u'ram')
+  Traceback (most recent call last):
+  ...
+  ComponentLookupError: (<InterfaceClass ...IMessageSource>, u'ram')
+
+You can enable this source by including ``ram.zcml`` from
+``grokcore.messages`` in your ZCML setup like this::
+
+  <configure xmlns="http://namespaces.zope.org/zope">
+    <include package="grokcore.messages" file="ram.zcml" />
+  </configure>
+
+or, of course, by registering a RAMMessageSource manually:
+
+  >>> from zope.component import provideUtility
+  >>> from z3c.flashmessage.sources import RAMMessageSource
+  >>> ram_source = RAMMessageSource()
+  >>> provideUtility(ram_source, name=u'ram')
+ 
+Now we can get the RAM source:
+
+  >>> getUtility(IMessageSource, name=u'ram')
+  <z3c.flashmessage.sources.RAMMessageSource object at 0x...>
+
+Components (API)
+================
+
+``grokcore.messages`` provides some extra-components and functions
+beside the usual components from ``z3c.flashmessage``.
+
+UniqueMessageSource
+-------------------
+
+A ``UniqueMessageSource`` is a message source that holds exactly zero
+or one message. Note that messages are not stored persistent in a
+``UniqueMessageSource`` instance and will be lost after restarting
+your Zope instance.
+
+It is a baseclass, which means that you have to derive from it to
+register an instance as global utility upon your software being
+grokked (see examples below).
+
+It provides the methods required by the IMessageSource interface:
+
+  >>> from z3c.flashmessage.interfaces import IMessageSource
+  >>> from grokcore.messages import UniqueMessageSource
+  >>> IMessageSource.implementedBy(UniqueMessageSource)
+  True
+
+Methods:
+
+  **UniqueMessageSource.send(message, type)**
+    Send a message ``message`` of type ``type``.
+
+  **UniqueMessageSource.list(type=None)**
+    Returns a generator object listing the message if one is stored.
+
+  **UniqueMessageSource.delete(message)**
+    Delete the message stored from source, if ``message`` is this
+    message.
+
+Convenience functions
+---------------------
+
+``grokcore.messages`` provides a couple of convenience functions to
+feed sources or get data from them.
+
+**grokcore.messages.send(message[, type='message'])**
+
+  Send ``message`` to the session based source (named 'session').
+
+  Returns ``True`` if the message could be sent
+  successfully. Otherwise ``False`` is returned:
+
+    >>> import grokcore.messages
+    >>> grokcore.messages.send('Meet at dawn!')
+    True
+
+**grokcore.messages.get_from_source([name=''])**
+
+  Get a list of messages stored at message source registered under
+  name ``name`` or ``None``.
+
+  This action never deletes messages from the queried source.
+
+    >>> import grokcore.messages
+    >>> grokcore.messages.get_from_source('session')
+    <generator object at 0x...>
+
+    >>> grokcore.messages.get_from_source('not-existing') is None
+    True
+
+**grokcore.messages.receive([name=''])**
+
+  Receive the messages collected by the receiver registered under name
+  ``name``.
+
+  >>> import grokcore.messages
+  >>> msgs = list(grokcore.messages.receive())
+  >>> msgs
+  [<z3c.flashmessage.message.Message object at 0x...>]
+
+  >>> msgs[0].message
+  'Meet at dawn!'
+
+  Please note, that this action might delete messages from the sources
+  they have been sent to as by 'receiving' messages you indicate that
+  the messages have been processed.
+
+  The session source for instance is now empty:
+
+  >>> list(grokcore.messages.get_from_source('session'))
+  []
+
+  Receiving again will give no results:
+
+  >>> list(grokcore.messages.receive())
+  []
+
+
+Examples
+========
+
+Creating a ``UniqueMessageSource``:
+
+  >>> from grokcore.messages import UniqueMessageSource
+  >>> class MyUniqueMessageSource(UniqueMessageSource):
+  ...   grok.name('uniq_source')
+  
+After being grokked, the source is automatically registered:
+
+  >>> grok.testing.grok_component('MyUniqueMessageSource',
+  ...                             MyUniqueMessageSource) 
+  True
+
+  >>> source = getUtility(IMessageSource, name='uniq_source')
+  >>> source
+  <MyUniqueMessageSource object at 0x...>
+
+
+We can list the message stored in the source:
+
+  >>> source.list()
+  <generator object at 0x...>
+
+  >>> list(source.list())
+  []
+
+  >>> source.send(message='Hello!', type='message')
+  >>> list(source.list())
+  [<z3c.flashmessage.message.PersistentMessage object at 0x...>]
+
+  >>> print list(source.list())[0].message
+  Hello!
+
+When we send another message, the old one will be silenty discarded:
+
+  >>> source.send(message='Hello again!', type='message')
+  >>> len(list(source.list()))
+  1
+
+  >>> print list(source.list())[0].message
+  Hello again!
+
+We can delete the message:
+
+  >>> msg = list(source.list())[0]
+  >>> source.delete(msg)
+  >>> len(list(source.list()))
+  0
+
+Examples for the convenience functions can be found above.
+
+
+.. _z3c.flashmessage: http://pypi.python.org/pypi/z3c.flashmessage