Package: grokcore.message
grokcore.messageThis package provides integration ofz3c.flashmessagefor 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 namedsession.Optionally (if includingram.zcml) registering a global RAM
stored message source namedram.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 thez3c.flashmessagedocumentation.Contentsgrokcore.messageSetting upgrokcore.messageComponents (API)UniqueMessageSourceConvenience functionsExamplesCHANGES4.0 (2023-08-28)3.0.1 (2018-01-17)3.0.0 (2018-01-15)0.4.3 (2016-02-15)0.4.2 (2010-10-25)0.4.1 (2010-10-25)0.4 (2010-10-25)0.3 (2010-03-05)0.2 (2010-03-03)0.1 (2010-03-03)Setting upgrokcore.messageWhen being grokked,grokcore.messageregistersa global session message source namedsessiona global message receiver.Grokking of this package happens when the localconfigure.zcmlis
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.message')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 namedsession:>>> 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
includingram.zcmland is not registered by default:>>> getUtility(IMessageSource, name=u'ram')
Traceback (most recent call last):
...
zope.interface.interfaces.ComponentLookupError: (<InterfaceClass z3c.flashmessage.interfaces.IMessageSource>, 'ram')You can enable this source by includingram.zcmlfromgrokcore.messagein your ZCML setup like this:<configure xmlns="http://namespaces.zope.org/zope">
  <include package="grokcore.message" 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.messageprovides some extra-components and functions
beside the usual components fromz3c.flashmessage.UniqueMessageSourceAUniqueMessageSourceis a message source that holds exactly zero
or one message. Note that messages are not stored persistent in aUniqueMessageSourceinstance 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).Methods:UniqueMessageSource.send(message[, type=u’message’])Send a messagemessageof typetype.UniqueMessageSource.list(type=None)Returns a generator object listing the message if one is stored.UniqueMessageSource.delete(message)Delete the message stored from source, ifmessageis this
message.Convenience functionsgrokcore.messageprovides a couple of convenience functions to
feed sources or get data from them.grokcore.message.send(message[, type=’message’[, name=’session’]])Sendmessageto the message sourcename.ReturnsTrueif the message could be sent
successfully. OtherwiseFalseis returned:>>> import grokcore.message
>>> grokcore.message.send('Meet at dawn!')
True>>> grokcore.message.send('Meat a fawn!', name='doesnotexist')
Falsegrokcore.message.get_from_source([name=’’])Get a list of messages stored at message source registered under
namenameorNone.This action never deletes messages from the queried source.>>> import grokcore.message
>>> grokcore.message.get_from_source('session')
<generator object ...>>>> grokcore.message.get_from_source('not-existing') is None
Truegrokcore.message.receive([name=’’])Receive the messages collected by the receiver registered under namename.>>> import grokcore.message
>>> msgs = list(grokcore.message.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.message.get_from_source('session'))
[]Receiving again will give no results:>>> list(grokcore.message.receive())
[]ExamplesCreating aUniqueMessageSource:>>> from grokcore.message import UniqueMessageSource
>>> class MyUniqueMessageSource(UniqueMessageSource):
...   grok.name('uniq_source')After being grokked, the source is automatically registered:>>> grok.testing.grok_component(
...     'MyUniqueMessageSource', MyUniqueMessageSource,
...     dotted_name='grokcore.message.tests')
True>>> source = getUtility(IMessageSource, name='uniq_source')
>>> source
<...MyUniqueMessageSource object at 0x...>It provides the methods required by the IMessageSource interface:>>> from z3c.flashmessage.interfaces import IMessageSource
>>> from zope.interface import verify>>> verify.verifyClass(IMessageSource, MyUniqueMessageSource)
TrueWe can list the message stored in the source:>>> source.list()
<generator object ...>>>> 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()))
0Examples for the convenience functions can be found above.CHANGES4.0 (2023-08-28)Drop support for Python 2.7, 3.4, 3.5, 3.6.Add support for Python 3.7, 3.8, 3.9, 3.10, 3.11.3.0.1 (2018-01-17)Replace the use ofgrok.implements()with the@grok.implementer()directive throughout.3.0.0 (2018-01-15)Python 3 compatibility.0.4.3 (2016-02-15)Update tests.0.4.2 (2010-10-25)Tests fixed by explicitely registering the IClientIdManager and
ISessionDataContainer utilities. The ftesting.zcml was re-introduced for this.0.4.1 (2010-10-25)Remove ftesting.zcml that was not necessary anymore.0.4 (2010-10-25)Make surezope.sessionis configured, as this package claims to provide
for a session based flash message machinery.Made package comply to zope.org repository policy.0.3 (2010-03-05)UniqueMessageSourcenow implements theIMessageSourceinterface completely, i.e. thetypeparameter is now optional
when usingUniqueMessageSource.send().0.2 (2010-03-03)The utility functionsendnow takes anameargument,
allowing the choice of the target message source.0.1 (2010-03-03)Factored out from former versions ofgrokui.admin,grokandmegrok.layoutrespectively.