Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

A package for sending `flash messages` to users.

Project description

Flash messages

Components to display small messages to users.

Sending a message to the current user

To send a message to the current user, you can use the session-based message source. Let’s set one up:

>>> from z3c.flashmessage.sources import SessionMessageSource
>>> from __future__ import unicode_literals
>>> source = SessionMessageSource()
>>> source.send('The world will come to an end in 40 seconds!')

The source allows to list all current messages:

>>> m = list(source.list())
>>> m
[<z3c.flashmessage.message.Message object at 0x...>]
>>> m[0].message
'The world will come to an end in 40 seconds!'
>>> str(m[0].type)

Receiving messages

The standard message that is generated removes itself from the source when it is received. The receiver will call prepare() on the message before it is handed out to the code that receives it:

>>> m[0].prepare(source)
>>> list(source.list())

There also is another default message that does not delete itself when being read:

>>> from z3c.flashmessage.message import PersistentMessage
>>> source.send(PersistentMessage('I will stay forever!'))
>>> m = list(source.list())[0]
>>> m.message
'I will stay forever!'
>>> m.prepare(source)
>>> list(source.list())
[<z3c.flashmessage.message.PersistentMessage object at 0x...>]

Global receiver

There is a global receiver that queries all message sources that are set up as utilities. Let’s set up a session message source as a utility:

>>> from zope.component import provideUtility
>>> provideUtility(source)
>>> source.send('Test!')
>>> from z3c.flashmessage.sources import RAMMessageSource
>>> source2 = RAMMessageSource()
>>> provideUtility(source2, name='other')
>>> source2.send('Test 2!')
>>> source2.send('Test 3!')
>>> from z3c.flashmessage.receiver import GlobalMessageReceiver
>>> receiver = GlobalMessageReceiver()
>>> m = list(receiver.receive())
>>> len(m)
>>> m[0].message
'I will stay forever!'
>>> m[1].message
>>> m[2].message
'Test 2!'
>>> m[3].message
'Test 3!'

After the receiver handed out the messages, they are gone from the sources, because the receiver notifies the messages that they were read:

>>> len(list(receiver.receive()))

Filtering message types

When listing messages from a message source, we can restrict which messages we see. If we don’t give a type, then all messages are returned. The default type of a message is message:

>>> source3 = RAMMessageSource()
>>> source3.send('Test 2!')
>>> list(source3.list())
[<z3c.flashmessage.message.Message object at 0x...>]
>>> list(source3.list('message'))
[<z3c.flashmessage.message.Message object at 0x...>]
>>> list(source3.list('somethingelse'))

Performance and Scalability Issues

By default, messages are stored persistently in the ZODB using zope.session. This can be a significant scalability problem; see design.txt in zope.session for more information. You should think twice before using flashmessages for unauthenticated users, as this can easily lead to unnecessary database growth on anonymous page views, and conflict errors under heavy load.

One solution is to configure your system to store flashmessages in RAM. You would do this by configuring a utility providing z3c.flashmessage.interfaces.IMessageSource with the factory set to z3c.flashmessage.sources.RAMMessageSource, and a specific name if your application expects one.

RAM storage is much faster and removes the persistence issues described above, but there are two new problems. First, be aware that if your server process restarts for any reason, all unread flashmessages will be lost. Second, if you cluster your application servers using e.g. ZEO, you must also ensure that your load-balancer supports session affinity (so a specific client always hits the same back end server). This somewhat reduces the performance benefits of clustering.


2.1 (2018-11-12)

  • Claim support for Python 3.6, 3.7, PyPy and PyPy3.
  • Drop support for Python 3.3.
  • Drop support for python test.

2.0 (2016-08-08)

  • Standardize namespace __init__.
  • Claim compatibility for Python 3.3, 3.4, and 3.5.

1.3 (2010-10-28)

  • SessionMessageSource implicitly created sessions when the client was reading the messages from the source. Changed internal API so reading no longer creates a session when it not yet exists.

1.2 (2010-10-19)

  • Removed test dependency on

1.1 (2010-10-02)

  • Removed test dependency on

1.0 (2007-12-06)

  • Updated dependency to zope.session instead of to get rid of deprecation warnings.

1.0b2 (2007-09-12)

  • Bugfix: When there was more than one message in a source not all messages would be returned by the receiver.

1.0b1 (2007-08-22)

  • Initial public release.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for z3c.flashmessage, version 2.1
Filename, size File type Python version Upload date Hashes
Filename, size z3c.flashmessage-2.1-py2.py3-none-any.whl (14.3 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size z3c.flashmessage-2.1.tar.gz (13.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page