Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - 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)
'message'

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)
4
>>> m[0].message
'I will stay forever!'
>>> m[1].message
'Test!'
>>> 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()))
1

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.

CHANGES

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 zope.app.zcmlfiles.

1.1 (2010-10-02)

  • Removed test dependency on zope.app.testing.

1.0 (2007-12-06)

  • Updated dependency to zope.session instead of zope.app.session 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.
Release History

Release History

This version
History Node

2.0

History Node

1.3

History Node

1.2

History Node

1.1

History Node

1.0

History Node

1.0b2

History Node

1.0b1

History Node

1.0dev-r77761

History Node

1.0dev-r77758

Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
z3c.flashmessage-2.0.tar.gz (12.3 kB) Copy SHA256 Checksum SHA256 Source Aug 8, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting