Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 204 lines (152 sloc) 6.069 kB
aee4d7b @mcdonc first cut
mcdonc authored
1 pyramid_beaker
2 ==============
3
4c7fdd1 @pauleveritt Update index.rst
pauleveritt authored
4 .. _overview:
5
6524a0a @blaflamme added support for includeme register function
blaflamme authored
6 Overview
7 --------
8
72b6d85 added cache support
ergo authored
9 A :term:`Beaker` session factory backend for :term:`Pyramid`, also cache
10 configurator.
aee4d7b @mcdonc first cut
mcdonc authored
11
6524a0a @blaflamme added support for includeme register function
blaflamme authored
12 Installation
13 ------------
14
15 Install using setuptools, e.g. (within a virtualenv)::
16
17 $ easy_install pyramid_beaker
18
19 Setup
20 -----
21
2dea621 @kpinc Update index.rst
kpinc authored
22 Once :mod:`pyramid_beaker` is installed, you typically use the ``config.include``
6524a0a @blaflamme added support for includeme register function
blaflamme authored
23 mechanism to include it into your Pyramid project's configuration. In your
24 Pyramid project's ``__init__.py``:
25
26 .. code-block:: python
27
28 config = Configurator(.....)
29 config.include('pyramid_beaker')
30
31 Alternately, instead of using the Configurator's ``include`` method, you can
3fc4310 @msabramo Fix docs typo: Pyramid => pyramid_beaker
msabramo authored
32 activate :mod:`pyramid_beaker` by changing your application's ``.ini`` file, use the
6524a0a @blaflamme added support for includeme register function
blaflamme authored
33 following line:
34
35 .. code-block:: ini
36
37 pyramid.includes = pyramid_beaker
38
aee4d7b @mcdonc first cut
mcdonc authored
39 Usage
40 -----
41
72b6d85 added cache support
ergo authored
42 Session management
56c1ddb @mcdonc update changelog, make Makfile check out themes, fix rest renderings
mcdonc authored
43 ``````````````````
2dea621 @kpinc Update index.rst
kpinc authored
44 If you have included pyramid_beaker in your Pyramid project's configuration
45 as shown above then :func:`pyramid_beaker.session_factory_from_settings`
46 is called automatically and you need do nothing else.
47 Otherwise you will need to create a Pyramid
48 :term:`session factory` by adding a call to either the
aee4d7b @mcdonc first cut
mcdonc authored
49 :func:`pyramid_beaker.BeakerSessionFactoryConfig` function or the
2dea621 @kpinc Update index.rst
kpinc authored
50 :func:`pyramid_beaker.session_factory_from_settings` function in
51 the configuration code of your Pyramid project's ``__init__.py`` file
52 and subsequently register that
aee4d7b @mcdonc first cut
mcdonc authored
53 session factory with Pyramid. At that point, accessing
54 ``request.session`` will provide a Pyramid session using Beaker as a
55 backend.
56
57 :func:`pyramid_beaker.session_factory_from_settings` obtains session
58 settings from the ``**settings`` dictionary passed to the
59 Configurator. It assumes that you've placed session configuration
60 parameters prefixed with ``session.`` in your Pyramid application's
61 ``.ini`` file. For example:
62
63 .. code-block:: ini
64
65 [app:myapp]
66 .. other settings ..
67 session.type = file
68 session.data_dir = %(here)s/data/sessions/data
69 session.lock_dir = %(here)s/data/sessions/lock
70 session.key = mykey
71 session.secret = mysecret
2a07560 @mcdonc make sure session_factory_from_settings properly coerces cookie_from_…
mcdonc authored
72 session.cookie_on_exception = true
aee4d7b @mcdonc first cut
mcdonc authored
73
74 If your ``.ini`` file has such settings, you can use
75 :func:`pyramid_beaker.session_factory_from_settings` in your
76 application's configuration. For example, let's assume this code is
77 in the ``__init__.py`` of your Pyramid application that uses an
78 ``.ini`` file with the ``session.`` settings above to obtain its
79 ``**settings`` dictionary.
80
81 .. code-block:: python
82
83 from pyramid_beaker import session_factory_from_settings
e9643be @wichert Fix bad import in example
wichert authored
84 from pyramid.config import Configurator
aee4d7b @mcdonc first cut
mcdonc authored
85
86 def app(global_config, **settings):
87 """ This function returns a WSGI application.
88
89 It is usually called by the PasteDeploy framework during
90 ``paster serve``.
91 """
92 session_factory = session_factory_from_settings(settings)
93 config = Configurator(root_factory=get_root, settings=settings)
94 config.set_session_factory(session_factory)
95 # ... other configuration stuff...
96 return config.make_wsgi_app()
97
2a07560 @mcdonc make sure session_factory_from_settings properly coerces cookie_from_…
mcdonc authored
98 The ``cookie_on_exception`` option is specific to ``pyramid_beaker`` (as
99 opposed to all other options, which are specific to Beaker itself). It
100 indicates that the session cookie should be set even when a Pyramid exception
c11fba2 @mcdonc fix docs
mcdonc authored
101 view is being rendered. The default is ``True``, meaning that session
102 cookies will be sent back in responses generated by exception views.
72b6d85 added cache support
ergo authored
103
cf03019 @shazow Added docs mention of constant_csrf_token.
shazow authored
104 Additionally, the ``constant_csrf_token`` option can be set to override the
105 CSRF token value with some constant value. This is useful for testing but
106 should not be set in production.
107
72b6d85 added cache support
ergo authored
108 Beaker cache region support
109 ```````````````````````````
110
6524a0a @blaflamme added support for includeme register function
blaflamme authored
111 In the configuration portion of your :term:`Pyramid` app, if you are not using
112 the default activation setup, use the
72b6d85 added cache support
ergo authored
113 :func:`pyramid_beaker.set_cache_regions_from_settings` function to
114 set Beaker's cache regions. At that point, you can use Beaker's `cache_region`
115 functionality to enable caching for Your application.
116
117 :func:`pyramid_beaker.set_cache_regions_from_settings` obtains region
118 settings from the ``**settings`` dictionary passed to the
119 Configurator. It assumes that you've placed cache configuration
120 parameters prefixed with ``cache.`` in your Pyramid application's
121 ``.ini`` file. For example:
122
123 .. code-block:: ini
124
125 [app:myapp]
126 .. other settings ..
127 cache.regions = default_term, second, short_term, long_term
128 cache.type = memory
129 cache.second.expire = 1
130 cache.short_term.expire = 60
131 cache.default_term.expire = 300
132 cache.long_term.expire = 3600
133
134 If your ``.ini`` file has such settings, you can use
135 :func:`pyramid_beaker.set_cache_regions_from_settings` in your
136 application's configuration. For example, let's assume this code is
137 in the ``__init__.py`` of your Pyramid application that uses an
138 ``.ini`` file with the ``cache.`` settings above to obtain its
139 ``**settings`` dictionary.
140
141 .. code-block:: python
142
143 from pyramid_beaker import set_cache_regions_from_settings
144 from pyramid.configuration import configurator
145
146 def app(global_config, **settings):
147 """ This function returns a WSGI application.
148
149 It is usually called by the PasteDeploy framework during
150 ``paster serve``.
151 """
152 set_cache_regions_from_settings(settings)
153 config = Configurator(root_factory=get_root, settings=settings)
154 # ... other configuration stuff...
155 return config.make_wsgi_app()
156
1092376 @jkrebs Cleaned up the lock_dir and url settings to match the others. Added d…
jkrebs authored
157 Inherited region settings
158 ~~~~~~~~~~~~~~~~~~~~~~~~~
159
160 The following optional region settings inherit from the main cache
161 configuration or default as specified:
162
3ef17d1 @mmerickel Added key_length cache param for beaker 1.6+.
mmerickel authored
163 ``data_dir``
164 Inherits if specified.
165
2b78782 @rbcarson Add recognition of Beaker's 'enabled' option for cache regions.
rbcarson authored
166 ``enabled``
167 Inherits or defaults to True.
168
1092376 @jkrebs Cleaned up the lock_dir and url settings to match the others. Added d…
jkrebs authored
169 ``expire``
170 Inherits or defaults to 60 seconds.
171
3ef17d1 @mmerickel Added key_length cache param for beaker 1.6+.
mmerickel authored
172 ``key_length``
173 Inherits or defaults to 250 characters.
174
1092376 @jkrebs Cleaned up the lock_dir and url settings to match the others. Added d…
jkrebs authored
175 ``lock_dir``
176 Inherits if specified.
177
178 ``type``
179 Inherits or defaults to ``memory``.
180
181 ``url``
182 Inherits if specified.
183
aee4d7b @mcdonc first cut
mcdonc authored
184 API
185 ---
186
187 .. toctree::
188 :maxdepth: 2
189
190 api.rst
191
192 Indices and tables
193 ------------------
194
195 * :ref:`glossary`
196 * :ref:`genindex`
197 * :ref:`modindex`
198 * :ref:`search`
49cc775 @mcdonc ignore glossary
mcdonc authored
199
200 .. toctree::
201 :hidden:
202
203 glossary
Something went wrong with that request. Please try again.