diff options
Diffstat (limited to 'docs/narr/sessions.rst')
| -rw-r--r-- | docs/narr/sessions.rst | 33 |
1 files changed, 17 insertions, 16 deletions
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 8547a92cc..7a0a03384 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -27,8 +27,8 @@ limitation: network along which the cookie travels. - The maximum number of bytes that are storable in a serialized - representation of the session is fewer than 4000. Only very small - data sets can be kept in this + representation of the session is fewer than 4000. This is + suitable only for very small data sets. It is, however, digitally signed, and thus its data cannot easily be tampered with. @@ -62,8 +62,8 @@ Using a Session Object ---------------------- Once a session factory has been configured for your application, you -can access session objects provided by the session factory by asking -for the ``session`` attribute of any :term:`request` object. For +can access session objects provided by the session factory via +the ``session`` attribute of any :term:`request` object. For example: .. code-block:: python @@ -82,8 +82,7 @@ example: return Response('Fred was not in the session') You can use a session much like a Python dictionary. It supports all -methods of a Python dictionary, and it has three extra attributes, and -two extra methods. +dictionary methods, along with some extra attributes, and methods. Extra attributes: @@ -98,6 +97,8 @@ Extra methods: ``changed()`` Call this when you mutate a mutable value in the session namespace. + See the gotchas below for details on when, and why you should + call this. ``invalidate()`` Call this when you want to invalidate the session (dump all data, @@ -116,15 +117,15 @@ Some gotchas: pickleable, an error will be raised when the session is serialized. - If you place a mutable value (for example, a list or a dictionary) - in a session object, and you subsequently mutate that value, you - must call the ``changed()`` method of the session object. This is - because, although the session object can detect when you call its - data-modifying methods such as ``__setitem__``, ``pop`` and other - (and thus the session knows it needs to reserialize the session - data), when you change a mutable object stored in the session - itself, the session has no way to know that you changed that value. - When in doubt, call ``changed()`` after you've changed sessioning - data. + in a session object, and you subsequently mutate that value, you must + call the ``changed()`` method of the session object. In this case, the + session has no way to know that is was modified. However, when you + modify a session object directly, such as setting a value (i.e., + ``__setitem__``), or removing a key (e.g., ``del`` or ``pop``), the + session will automatically know that it needs to re-serialize its + data, thus calling ``changed()`` is unnecessary. There is no harm in + calling ``changed()`` in either case, so when in doubt, call it after + you've changed sessioning data. .. index:: single: pyramid_beaker @@ -154,6 +155,6 @@ session object by implementing a :term:`session factory`. Your session factory should return a :term:`session`. The interfaces for both types are available in :class:`pyramid.interfaces.ISessionFactory` and -:class:`pyramid.interfaces.ISession`. You might use the cookie +:class:`pyramid.interfaces.ISession`. You might use the cookie implementation in the :mod:`pyramid.session` module as inspiration. |