From 6f6d3649b280d3585d4c48541cac14e3959f9776 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 22 Dec 2010 16:57:23 -0500 Subject: change flash API as per email convo with Ben and Mike --- docs/narr/flash.rst | 126 +++++++++++++++++++++++----------------------------- 1 file changed, 55 insertions(+), 71 deletions(-) (limited to 'docs/narr/flash.rst') diff --git a/docs/narr/flash.rst b/docs/narr/flash.rst index 331793533..d41c2cdaf 100644 --- a/docs/narr/flash.rst +++ b/docs/narr/flash.rst @@ -11,113 +11,97 @@ factory` as described in :ref:`using_the_default_session_factory` or Flash messaging has two main uses: to display a status message only once to the user after performing an internal redirect, and to allow generic code to log messages for single-time display without having direct access to an HTML -template. The user interface consists of two methods of the :term:`session` -object. +template. The user interface consists of a number of methods of the +:term:`session` object. Using the ``session.flash`` Method ---------------------------------- -To add a message to a flash queue, use a session object's ``flash`` method: +To add a message to a flash message queue, use a session object's ``flash`` +method: .. code-block:: python :linenos: request.session.flash('mymessage') -The ``.flash`` method appends a message to the queue, creating the queue if -necessary. The message is not modified in any way. +The ``.flash`` method appends a message to a flash queue, creating the queue +if necessary. -The ``category`` argument names a category or level. The library defines -several default category names: ``debug``, ``info``, ``success``, ``warning`` -and ``error``. The default category level is ``info``. +``.flash`` accepts three arguments: -The ``queue_name`` argument allows you to define multiple message -queues. This can be used to display different kinds of messages in different -places on a page. You cam pass any name for your queue, but it must be a -string. The default value is the empty string, which chooses the default -queue. Each queue is independent, and can be popped by ``unflash`` -separately. +.. method:: flash(message, queue='', allow_duplicate=True) -Constant names for flash message category names are importable from the -:mod:`pyramid.flash` module as ``DEBUG``, ``INFO``, ``SUCCESS``, ``WARNING`` -and ``ERROR``, which respectively name ``debug``, ``info``, ``success``, -``warning`` and ``error`` strings. For example you can do this: +The ``message`` argument is required. It represents a message you wish to +later display to a user. It is usually a string but the ``message`` you +provide is not modified in any way. -.. code-block:: python +The ``queue`` argument allows you to choose a queue to which to append the +message you provide. This can be used to push different kinds of messages +into flash storage for later display in different places on a page. You cam +pass any name for your queue, but it must be a string. The default value is +the empty string, which chooses the default queue. Each queue is independent, +and can be popped by ``pop_flash`` or examined via ``peek_flash`` separately. +``queue`` defaults to the empty string. The empty string represents the +default flash message queue. - from pyramid import flash - request.session.flash(msg, flash.DEBUG) +.. code-block:: python -Or you can use the literal name ``debug``: + request.session.flash(msg, 'myappsqueue') -.. code-block:: python +The ``allow_duplicate`` argument, which defaults to ``True``. If this is +``False``, if you attempt to add a message to a queue which is already +present in the queue, it will not be added. - request.session.flash(msg, 'debug') +Using the ``session.pop_flash`` Method +-------------------------------------- -Both examples do the same thing. The meanings of flash category names are -detailed in :mod:`pyramid.flash`. +Once one or more messages has been added to a flash queue by the +``session.flash`` API, the ``session.pop_flash`` API can be used to pop that +queue and return it for use. To pop a particular queue of messages from the flash object, use the session -object's ``unflash`` method. +object's ``pop_flash`` method. .. code-block:: python :linenos: - >>> request.session.flash('info message', 'info') - >>> messages = request.session.unflash() - >>> messages['info'] + >>> request.session.flash('info message') + >>> request.session.pop_flash() ['info message'] -Using the ``session.unflash`` Method ------------------------------------- - -Once one or more messages has been added to a flash queue by the -``session.flash`` API, the ``session.unflash`` API can be used to pop that -queue and return it for use. - -For example some code that runs in a view callable might call the -``session.flash`` API: +Calling ``session.pop_flash()`` again like above without a corresponding call +to ``session.flash`` will return an empty list, because the queue has already +been popped. .. code-block:: python :linenos: - request.session.flash('mymessage') - -A corresponding ``session.unflash`` might be called on a subsequent request: - -.. code-block:: python - :linenos: + >>> request.session.flash('info message') + >>> request.session.pop_flash() + ['info message'] + >>> request.session.pop_flash() + [] - messages = request.session.unflash() +The object returned from ``pop_flash`` is a list. -Calling ``session.unflash`` again like above without a corresponding call to -``session.flash`` will return an empty ``messages`` object, because the queue -has already been popped. +Using the ``session.pop_flash`` Method +-------------------------------------- -The ``messages`` object returned from ``unflash`` is a dictionary-like -object. Its keys are category names, and its values are sequences of -strings. For ease of use, the dict-like object returned by ``unflash`` isn't -a "plain" dict: it's an object which has several helper methods, each named -after a particular flash category level. These methods return all messages -related to the category name: +Once one or more messages has been added to a flash queue by the +``session.flash`` API, the ``session.peek_flash`` API can be used to "peek" +at that queue. Unlike ``session.pop_flash``, the queue is not popped from +flash storage. .. code-block:: python :linenos: - >>> request.session.flash('debug message', 'debug') - >>> request.session.flash('info message', 'info') - >>> messages = request.session.unflash() - >>> info_messages = messages.debug() - ['debug message'] - >>> info_messages = messages.info() + >>> request.session.flash('info message') + >>> request.session.peek_flash() ['info message'] - -The full API of the ``messages`` object returned by ``unflash`` is documented -in :class:`pyramid.interfaces.IFlashMessages`. - -.. The ``ignore_duplicate`` flag tells whether to suppress duplicate -.. messages. If true, and another message with identical text exists in the -.. queue, don't add the new message. But if the existing message has a -.. different category than the new message, change its category to match the -.. new message. - + >>> request.session.peek_flash() + ['info message'] + >>> request.session.pop_flash() + ['info message'] + >>> request.session.peek_flash() + [] -- cgit v1.2.3 From b6f7b34c95ae96cb70d583211e40a8b4300dea17 Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Wed, 29 Dec 2010 00:26:10 +0200 Subject: Typo: cam -> can. --- docs/narr/flash.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/flash.rst') diff --git a/docs/narr/flash.rst b/docs/narr/flash.rst index d41c2cdaf..0bffd6ddf 100644 --- a/docs/narr/flash.rst +++ b/docs/narr/flash.rst @@ -38,7 +38,7 @@ provide is not modified in any way. The ``queue`` argument allows you to choose a queue to which to append the message you provide. This can be used to push different kinds of messages -into flash storage for later display in different places on a page. You cam +into flash storage for later display in different places on a page. You can pass any name for your queue, but it must be a string. The default value is the empty string, which chooses the default queue. Each queue is independent, and can be popped by ``pop_flash`` or examined via ``peek_flash`` separately. -- cgit v1.2.3 From 2c29ef9007681902575384157eea8b36d53cca30 Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Wed, 29 Dec 2010 00:26:46 +0200 Subject: Rephrase sentence with no verb. --- docs/narr/flash.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/flash.rst') diff --git a/docs/narr/flash.rst b/docs/narr/flash.rst index 0bffd6ddf..ad50dc82b 100644 --- a/docs/narr/flash.rst +++ b/docs/narr/flash.rst @@ -49,7 +49,7 @@ default flash message queue. request.session.flash(msg, 'myappsqueue') -The ``allow_duplicate`` argument, which defaults to ``True``. If this is +The ``allow_duplicate`` argument defaults to ``True``. If this is ``False``, if you attempt to add a message to a queue which is already present in the queue, it will not be added. -- cgit v1.2.3 From 87e5443d655b745ba7a5a675bdd52027a2240d11 Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Wed, 29 Dec 2010 00:29:11 +0200 Subject: "one or more has" -> "one or more have". Sounds more natural to me, and Googling for "one or more: singular or plural" seems to agree. --- docs/narr/flash.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/flash.rst') diff --git a/docs/narr/flash.rst b/docs/narr/flash.rst index ad50dc82b..d009da4fb 100644 --- a/docs/narr/flash.rst +++ b/docs/narr/flash.rst @@ -56,7 +56,7 @@ present in the queue, it will not be added. Using the ``session.pop_flash`` Method -------------------------------------- -Once one or more messages has been added to a flash queue by the +Once one or more messages have been added to a flash queue by the ``session.flash`` API, the ``session.pop_flash`` API can be used to pop that queue and return it for use. -- cgit v1.2.3 From 133f1231b1288e20777b56c82d5c5b7730010eab Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Wed, 29 Dec 2010 00:36:21 +0200 Subject: Show the method signatures of pop_flash/peek_flash. The narrative referred to popping messages from a particular queue, but the code examples didn't show how to indicate which queue you were interested in, leaving the reader a bit confused. --- docs/narr/flash.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/narr/flash.rst') diff --git a/docs/narr/flash.rst b/docs/narr/flash.rst index d009da4fb..71c6cf305 100644 --- a/docs/narr/flash.rst +++ b/docs/narr/flash.rst @@ -63,6 +63,8 @@ queue and return it for use. To pop a particular queue of messages from the flash object, use the session object's ``pop_flash`` method. +.. method:: pop_flash(queue='') + .. code-block:: python :linenos: @@ -93,6 +95,8 @@ Once one or more messages has been added to a flash queue by the at that queue. Unlike ``session.pop_flash``, the queue is not popped from flash storage. +.. method:: peek_flash(queue='') + .. code-block:: python :linenos: -- cgit v1.2.3