From 04ebd572a92f6681209c70c42192775c63cd16cd Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 28 Oct 2010 22:40:16 -0400 Subject: sessioning docs --- docs/narr/security.rst | 2 +- docs/narr/sessions.rst | 152 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/narr/webob.rst | 12 ++-- 3 files changed, 159 insertions(+), 7 deletions(-) create mode 100644 docs/narr/sessions.rst (limited to 'docs/narr') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 109009842..5782837aa 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -241,7 +241,7 @@ application: When a default permission is registered: -- if a view configuration names an explicit ``permission`, the default +- if a view configuration names an explicit ``permission``, the default permission is ignored for that view registration, and the view-configuration-named permission is used. diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst new file mode 100644 index 000000000..e460e2d74 --- /dev/null +++ b/docs/narr/sessions.rst @@ -0,0 +1,152 @@ +.. index:: + single: session + +.. _sessions_chapter: + +Session Objects +=============== + +A :term:`session` is a namespace which is valid for some period of +continual activity that can be used to represent a user's interaction +with a web application. + +Using The Default Session Factory +--------------------------------- + +In order to use sessions, you must set up a :term:`session factory` +during your :mod:`pyramid` configuration. + +A very basic, insecure sample session factory implementation is +provided in the :mod:`pyramid` core. It uses a cookie to store +session information. This implementation has the following +limitation: + +- The session information in the cookies used by this implementation + is *not* encrypted, so it can be viewed by anyone with access to the + cookie storage of the user's browser or anyone with access to the + 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 + +It is, however, digitally signed, and thus its data cannot easily be +tampered with. + +You can configure this session factory in your :mod:`pyramid` +application by using the ``session_factory`` argument to the +:class:`pyramid.configuration.Configurator` class: + +.. code-block:: python + :linenos: + + from pyramid.session import InsecureCookieSessionFactoryConfig + my_session_factory = InsecureCookieSessionFactoryConfig('itsaseekreet') + + from pyramid.configuration import Configurator + config = Configurator(session_factory = my_session_factory) + +.. warning:: + + Note the very long, very explicit name for + ``InsecureCookieSessionFactoryConfig``. It's trying to tell you + that this implementation is, by default, *insecure*. You should + not use it when you keep sensitive information in the session + object, as the information can be easily read by both users of your + application and third parties who have access to your users' + network traffic. Use a different session factory implementation + (preferably one which keeps session data on the server) for + anything but the most basic of applications where "session security + doesn't matter". + +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 +example: + +.. code-block:: python + :linenos: + + from webob import Response + + def myview(request): + session = request.session + if 'abc' in session: + session['fred'] = 'yes' + session['abc'] = '123' + if 'fred' in session: + return Response('Fred was in the session') + else: + 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. + +Extra attributes: + +``modified`` + An integer timestamp indicating the last time the session was modified. + +``created`` + An integer timestamp indicating the time that this session was created. + +``new`` + A boolean. If ``new`` is True, this session is new. Otherwise, it has + been constituted from data that was already serialized. + +Extra methods: + +``changed()`` + Call this when you mutate a mutable value in the session namespace. + +``invalidate()`` + Call this when you want to invalidate the session (dump all data, + and -- perhaps -- set a clearing cookie). + +The formal definition of the methods and attributes supported by the +session object are in the :class:`pyramid.interfaces.ISession` +documentation. + +Some gotchas: + +- Keys and values of session data must be *pickleable*. This means, + typically, that they must be instances of basic types of objects, + such as strings, lists, dictionaries, tuples, integers, etc. If you + place an object in a session data key or value that is not + 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. + +Using Alternate Session Factories +--------------------------------- + +At the time of this writing, alternate session factories don't yet +exist. It is our intent that we will soon provide at least one other +session factory which will be easily installable: one that uses the +`Beaker `_ library as a backend. + +Creating Your Own Session Factory +--------------------------------- + +If none of the default or otherwise available sessioning +implementations for :mod:`pyramid` suit you, you may create your own +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 +implementation in the :mod:`pyramid.session` module as inspiration. + diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index b3bec882e..15f8da9cf 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -109,12 +109,12 @@ instance, ``req.if_modified_since`` returns a `datetime Special Attributes Added to the Request by :mod:`pyramid` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -In addition to the standard :term:`WebOb` attributes, -:mod:`pyramid` adds special attributes to every request: -``context``, ``registry``, ``root``, ``subpath``, ``traversed``, -``view_name``, ``virtual_root`` , and ``virtual_root_path``. These -attributes are documented further within the -:class:`pyramid.request.Request` API documentation. +In addition to the standard :term:`WebOb` attributes, :mod:`pyramid` +adds special attributes to every request: ``context``, ``registry``, +``root``, ``subpath``, ``traversed``, ``view_name``, ``virtual_root`` +, ``virtual_root_path``, and ``session``. These attributes are +documented further within the :class:`pyramid.request.Request` API +documentation. .. index:: single: request URLs -- cgit v1.2.3