1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
.. 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 :app:`Pyramid` configuration.
A very basic, insecure sample session factory implementation is
provided in the :app:`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 :app:`Pyramid`
application by using the ``session_factory`` argument to the
:class:`pyramid.configuration.Configurator` class:
.. code-block:: python
:linenos:
from pyramid.session import UnencryptedCookieSessionFactoryConfig
my_session_factory = UnencryptedCookieSessionFactoryConfig('itsaseekreet')
from pyramid.configuration import Configurator
config = Configurator(session_factory = my_session_factory)
.. warning::
Note the very long, very explicit name for
``UnencryptedCookieSessionFactoryConfig``. It's trying to tell you that
this implementation is, by default, *unencrypted*. 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 pyramid.response 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:
``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.
.. index::
single: pyramid_beaker
single: Beaker
Using Alternate Session Factories
---------------------------------
At the time of this writing, exactly one alternate session factory
implementation exists, named ``pyramid_beaker``. This is a session
factory that uses the `Beaker <http://beaker.groovie.org/>`_ library
as a backend. Beaker has support for file-based sessions, database
based sessions, and encrypted cookie-based sessions. See
`http://github.com/Pylons/pyramid_beaker
<http://github.com/Pylons/pyramid_beaker>`_ for more information about
``pyramid_beaker``.
.. index::
single: session factory
Creating Your Own Session Factory
---------------------------------
If none of the default or otherwise available sessioning
implementations for :app:`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.
|
