change flash API as per email convo with Ben and Mike

2 files changed, 55 insertions, 72 deletions

diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst
index dab64ba15..b3c14e5f7 100644
--- a/docs/api/interfaces.rst
+++ b/docs/api/interfaces.rst
@@ -35,4 +35,3 @@ Other Interfaces
 
   .. autointerface:: ITemplateRenderer
 
-  .. autointerface:: IFlashMessages
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()
+   []