Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 590 lines (437 sloc) 22.394 kB
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
1 .. index::
2 single: environment variables
3 single: settings
4 single: reload
5 single: debug_authorization
92c3e50 @mcdonc resource -> asset
mcdonc authored
6 single: reload_assets
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
7 single: debug_notfound
8 single: debug_all
9 single: reload_all
c5f24b2 Prep for b1
Chris McDonough authored
10 single: debug settings
6ce1e0c @mcdonc add more index markers
mcdonc authored
11 single: debug_routematch
12 single: prevent_http_cache
c5f24b2 Prep for b1
Chris McDonough authored
13 single: reload settings
7534bae Merge i18n branch via svn merge --ignore-ancestry -r9030:9150 $REPOZE…
Chris McDonough authored
14 single: default_locale_name
c5f24b2 Prep for b1
Chris McDonough authored
15 single: environment variables
16 single: ini file settings
17 single: PasteDeploy settings
879bb56 @Cito More small fixes made reading the rest of the docs and the tutorials.
Cito authored
18
47b4d3e Docs
Chris McDonough authored
19 .. _environment_chapter:
20
e40eb20 - Remove explanation of changing the request type in a new request
Chris McDonough authored
21 Environment Variables and ``.ini`` File Settings
22 ================================================
47b4d3e Docs
Chris McDonough authored
23
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored
24 :app:`Pyramid` behavior can be configured through a combination of
47b4d3e Docs
Chris McDonough authored
25 operating system environment variables and ``.ini`` configuration file
26 application section settings. The meaning of the environment
27 variables and the configuration file settings overlap.
28
29 .. note:: Where a configuration file setting exists with the same
30 meaning as an environment variable, and both are present at
31 application startup time, the environment variable setting
32 takes precedence.
33
34 The term "configuration file setting name" refers to a key in the
35 ``.ini`` configuration for your application. The configuration file
36 setting names documented in this chapter are reserved for
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored
37 :app:`Pyramid` use. You should not use them to indicate
47b4d3e Docs
Chris McDonough authored
38 application-specific configuration settings.
39
2747781 Overlong lines.
Chris McDonough authored
40 Reloading Templates
e4ed8fd Section header fixes.
Chris McDonough authored
41 -------------------
2747781 Overlong lines.
Chris McDonough authored
42
d433754 @caseman clarify
caseman authored
43 When this value is true, templates are automatically reloaded whenever
44 they are modified without restarting the application, so you can see
45 changes to templates take effect immediately during development. This
46 flag is meaningful to Chameleon and Mako templates, as well as most
47 third-party template rendering extensions.
2747781 Overlong lines.
Chris McDonough authored
48
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
49 +---------------------------------+--------------------------------+
50 | Environment Variable Name | Config File Setting Name |
51 +=================================+================================+
52 | ``PYRAMID_RELOAD_TEMPLATES`` | ``pyramid.reload_templates`` |
b4870b1 @mcdonc readd aliases to environment tables
mcdonc authored
53 | | or ``reload_templates`` |
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
54 | | |
55 | | |
56 +---------------------------------+--------------------------------+
2747781 Overlong lines.
Chris McDonough authored
57
92c3e50 @mcdonc resource -> asset
mcdonc authored
58 Reloading Assets
59 ----------------
2747781 Overlong lines.
Chris McDonough authored
60
2033eeb @stevepiercy - Garden PR #1121
stevepiercy authored
61 Don't cache any asset file data when this value is true.
62
63 .. seealso::
64
65 See also :ref:`overriding_assets_section`.
2747781 Overlong lines.
Chris McDonough authored
66
67 +---------------------------------+-----------------------------+
68 | Environment Variable Name | Config File Setting Name |
69 +=================================+=============================+
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
70 | ``PYRAMID_RELOAD_ASSETS`` | ``pyramid.reload_assets`` |
b4870b1 @mcdonc readd aliases to environment tables
mcdonc authored
71 | | or ``reload_assets`` |
2747781 Overlong lines.
Chris McDonough authored
72 | | |
73 | | |
74 +---------------------------------+-----------------------------+
75
7956595 @mcdonc remove following (confusing)
mcdonc authored
76 .. note:: For backwards compatibility purposes, aliases can be
e79d360 @mcdonc - All environment variables which used to be prefixed with ``BFG_`` a…
mcdonc authored
77 used for configurating asset reloading: ``PYRAMID_RELOAD_RESOURCES`` (envvar)
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
78 and ``pyramid.reload_resources`` (config file).
92c3e50 @mcdonc resource -> asset
mcdonc authored
79
2747781 Overlong lines.
Chris McDonough authored
80 Debugging Authorization
e4ed8fd Section header fixes.
Chris McDonough authored
81 -----------------------
2747781 Overlong lines.
Chris McDonough authored
82
83 Print view authorization failure and success information to stderr
2033eeb @stevepiercy - Garden PR #1121
stevepiercy authored
84 when this value is true.
85
86 .. seealso::
87
88 See also :ref:`debug_authorization_section`.
2747781 Overlong lines.
Chris McDonough authored
89
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
90 +---------------------------------+-----------------------------------+
91 | Environment Variable Name | Config File Setting Name |
92 +=================================+===================================+
93 | ``PYRAMID_DEBUG_AUTHORIZATION`` | ``pyramid.debug_authorization`` |
b4870b1 @mcdonc readd aliases to environment tables
mcdonc authored
94 | | or ``debug_authorization`` |
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
95 | | |
96 | | |
97 +---------------------------------+-----------------------------------+
2747781 Overlong lines.
Chris McDonough authored
98
99 Debugging Not Found Errors
e4ed8fd Section header fixes.
Chris McDonough authored
100 --------------------------
2747781 Overlong lines.
Chris McDonough authored
101
102 Print view-related ``NotFound`` debug messages to stderr
2033eeb @stevepiercy - Garden PR #1121
stevepiercy authored
103 when this value is true.
104
105 .. seealso::
106
107 See also :ref:`debug_notfound_section`.
2747781 Overlong lines.
Chris McDonough authored
108
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
109 +---------------------------------+------------------------------+
110 | Environment Variable Name | Config File Setting Name |
111 +=================================+==============================+
112 | ``PYRAMID_DEBUG_NOTFOUND`` | ``pyramid.debug_notfound`` |
b4870b1 @mcdonc readd aliases to environment tables
mcdonc authored
113 | | or ``debug_notfound`` |
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
114 | | |
115 | | |
116 +---------------------------------+------------------------------+
2747781 Overlong lines.
Chris McDonough authored
117
24bf2a8 @mcdonc Features
mcdonc authored
118 Debugging Route Matching
119 ------------------------
120
121 Print debugging messages related to :term:`url dispatch` route matching when
2033eeb @stevepiercy - Garden PR #1121
stevepiercy authored
122 this value is true.
123
124 .. seealso::
125
126 See also :ref:`debug_routematch_section`.
24bf2a8 @mcdonc Features
mcdonc authored
127
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
128 +---------------------------------+--------------------------------+
129 | Environment Variable Name | Config File Setting Name |
130 +=================================+================================+
131 | ``PYRAMID_DEBUG_ROUTEMATCH`` | ``pyramid.debug_routematch`` |
b4870b1 @mcdonc readd aliases to environment tables
mcdonc authored
132 | | or ``debug_routematch`` |
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
133 | | |
134 | | |
135 +---------------------------------+--------------------------------+
e573d43 @mcdonc - New environment setting ``PYRAMID_PREVENT_HTTP_CACHE`` and new
mcdonc authored
136
137 .. _preventing_http_caching:
138
139 Preventing HTTP Caching
140 ------------------------
141
142 Prevent the ``http_cache`` view configuration argument from having any effect
143 globally in this process when this value is true. No http caching-related
144 response headers will be set by the Pyramid ``http_cache`` view configuration
2033eeb @stevepiercy - Garden PR #1121
stevepiercy authored
145 feature when this is true.
146
147 .. seealso::
148
149 See also :ref:`influencing_http_caching`.
e573d43 @mcdonc - New environment setting ``PYRAMID_PREVENT_HTTP_CACHE`` and new
mcdonc authored
150
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
151 +---------------------------------+----------------------------------+
152 | Environment Variable Name | Config File Setting Name |
153 +=================================+==================================+
154 | ``PYRAMID_PREVENT_HTTP_CACHE`` | ``pyramid.prevent_http_cache`` |
b4870b1 @mcdonc readd aliases to environment tables
mcdonc authored
155 | | or ``prevent_http_cache`` |
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
156 | | |
157 | | |
158 +---------------------------------+----------------------------------+
24bf2a8 @mcdonc Features
mcdonc authored
159
6596304 @chrisrossi Add 'prevent_cachebuster' setting.
chrisrossi authored
160 Preventing Cache Busting
161 ------------------------
162
15b9794 @chrisrossi cachebuster -> cachebust
chrisrossi authored
163 Prevent the ``cachebust`` static view configuration argument from having any
6596304 @chrisrossi Add 'prevent_cachebuster' setting.
chrisrossi authored
164 effect globally in this process when this value is true. No cache buster will
165 be configured or used when this is true.
166
6b88bdf @mcdonc add versionadded notes
mcdonc authored
167 .. versionadded:: 1.6
168
6596304 @chrisrossi Add 'prevent_cachebuster' setting.
chrisrossi authored
169 .. seealso::
170
171 See also :ref:`cache_busting`.
172
173 +---------------------------------+----------------------------------+
174 | Environment Variable Name | Config File Setting Name |
175 +=================================+==================================+
15b9794 @chrisrossi cachebuster -> cachebust
chrisrossi authored
176 | ``PYRAMID_PREVENT_CACHEBUST`` | ``pyramid.prevent_cachebust`` |
177 | | or ``prevent_cachebust`` |
6596304 @chrisrossi Add 'prevent_cachebuster' setting.
chrisrossi authored
178 | | |
179 | | |
180 +---------------------------------+----------------------------------+
181
2747781 Overlong lines.
Chris McDonough authored
182 Debugging All
e4ed8fd Section header fixes.
Chris McDonough authored
183 -------------
2747781 Overlong lines.
Chris McDonough authored
184
185 Turns on all ``debug*`` settings.
186
187 +---------------------------------+-----------------------------+
188 | Environment Variable Name | Config File Setting Name |
189 +=================================+=============================+
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
190 | ``PYRAMID_DEBUG_ALL`` | ``pyramid.debug_all`` |
b4870b1 @mcdonc readd aliases to environment tables
mcdonc authored
191 | | or ``debug_all`` |
2747781 Overlong lines.
Chris McDonough authored
192 | | |
193 | | |
194 +---------------------------------+-----------------------------+
195
e4ed8fd Section header fixes.
Chris McDonough authored
196 Reloading All
197 -------------
2747781 Overlong lines.
Chris McDonough authored
198
199 Turns on all ``reload*`` settings.
200
201 +---------------------------------+-----------------------------+
202 | Environment Variable Name | Config File Setting Name |
203 +=================================+=============================+
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
204 | ``PYRAMID_RELOAD_ALL`` | ``pyramid.reload_all`` |
b4870b1 @mcdonc readd aliases to environment tables
mcdonc authored
205 | | or ``reload_all`` |
7534bae Merge i18n branch via svn merge --ignore-ancestry -r9030:9150 $REPOZE…
Chris McDonough authored
206 | | |
207 | | |
208 +---------------------------------+-----------------------------+
209
c5378a4 Default locale name.
Chris McDonough authored
210 .. _default_locale_name_setting:
211
7534bae Merge i18n branch via svn merge --ignore-ancestry -r9030:9150 $REPOZE…
Chris McDonough authored
212 Default Locale Name
213 --------------------
214
215 The value supplied here is used as the default locale name when a
2033eeb @stevepiercy - Garden PR #1121
stevepiercy authored
216 :term:`locale negotiator` is not registered.
217
218 .. seealso::
219
220 See also :ref:`localization_deployment_settings`.
7534bae Merge i18n branch via svn merge --ignore-ancestry -r9030:9150 $REPOZE…
Chris McDonough authored
221
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
222 +---------------------------------+-----------------------------------+
223 | Environment Variable Name | Config File Setting Name |
224 +=================================+===================================+
225 | ``PYRAMID_DEFAULT_LOCALE_NAME`` | ``pyramid.default_locale_name`` |
b4870b1 @mcdonc readd aliases to environment tables
mcdonc authored
226 | | or ``default_locale_name`` |
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
227 | | |
228 | | |
229 +---------------------------------+-----------------------------------+
47b4d3e Docs
Chris McDonough authored
230
a8c81db @mcdonc add a whatsnew-1.2 doc
mcdonc authored
231 .. _including_packages:
232
8cd013e @mcdonc add docs for pyramid.includes; allow space-separated or cr separated …
mcdonc authored
233 Including Packages
234 ------------------
235
236 ``pyramid.includes`` instructs your application to include other packages.
237 Using the setting is equivalent to using the
238 :meth:`pyramid.config.Configurator.include` method.
239
240 +---------------------------------+
241 | Config File Setting Name |
242 +=================================+
243 | ``pyramid.includes`` |
244 | |
245 | |
246 | |
247 +---------------------------------+
248
3a6bdf9 @tshepang use clearer language
tshepang authored
249 The value assigned to ``pyramid.includes`` should be a sequence. The
8cd013e @mcdonc add docs for pyramid.includes; allow space-separated or cr separated …
mcdonc authored
250 sequence can take several different forms.
251
252 1) It can be a string.
253
254 If it is a string, the package names can be separated by spaces::
255
256 package1 package2 package3
257
3144aff @tshepang fix markup
tshepang authored
258 The package names can also be separated by carriage returns::
8cd013e @mcdonc add docs for pyramid.includes; allow space-separated or cr separated …
mcdonc authored
259
260 package1
261 package2
262 package3
263
264 2) It can be a Python list, where the values are strings::
265
266 ['package1', 'package2', 'package3']
267
268 Each value in the sequence should be a :term:`dotted Python name`.
269
270 ``pyramid.includes`` vs. :meth:`pyramid.config.Configurator.include`
271 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
272
4736974 @mcdonc garden changes; fix docs rendering
mcdonc authored
273 Two methods exist for including packages: ``pyramid.includes`` and
274 :meth:`pyramid.config.Configurator.include`. This section explains their
275 equivalence.
276
277 Using PasteDeploy
278 +++++++++++++++++
8cd013e @mcdonc add docs for pyramid.includes; allow space-separated or cr separated …
mcdonc authored
279
280 Using the following ``pyramid.includes`` setting in the PasteDeploy ``.ini``
281 file in your application:
282
283 .. code-block:: ini
284
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
285 [app:main]
4736974 @mcdonc garden changes; fix docs rendering
mcdonc authored
286 pyramid.includes = pyramid_debugtoolbar
287 pyramid_tm
8cd013e @mcdonc add docs for pyramid.includes; allow space-separated or cr separated …
mcdonc authored
288
289 Is equivalent to using the following statements in your configuration code:
290
291 .. code-block:: python
292 :linenos:
293
4736974 @mcdonc garden changes; fix docs rendering
mcdonc authored
294 from pyramid.config import Configurator
8cd013e @mcdonc add docs for pyramid.includes; allow space-separated or cr separated …
mcdonc authored
295
4736974 @mcdonc garden changes; fix docs rendering
mcdonc authored
296 def main(global_config, **settings):
297 config = Configurator(settings=settings)
298 # ...
299 config.include('pyramid_debugtoolbar')
300 config.include('pyramid_tm')
301 # ...
8cd013e @mcdonc add docs for pyramid.includes; allow space-separated or cr separated …
mcdonc authored
302
303 It is fine to use both or either form.
304
305 Plain Python
306 ++++++++++++
307
308 Using the following ``pyramid.includes`` setting in your plain-Python Pyramid
309 application:
310
311 .. code-block:: python
312 :linenos:
313
314 from pyramid.config import Configurator
315
316 if __name__ == '__main__':
317 settings = {'pyramid.includes':'pyramid_debugtoolbar pyramid_tm'}
318 config = Configurator(settings=settings)
319
320 Is equivalent to using the following statements in your configuration code:
321
322 .. code-block:: python
323 :linenos:
324
325 from pyramid.config import Configurator
326
327 if __name__ == '__main__':
328 settings = {}
329 config = Configurator(settings=settings)
330 config.include('pyramid_debugtoolbar')
331 config.include('pyramid_tm')
332
333 It is fine to use both or either form.
334
a8c81db @mcdonc add a whatsnew-1.2 doc
mcdonc authored
335 .. _explicit_tween_config:
336
be46dac @mcdonc add pyramid.tweens configuration value docs
mcdonc authored
337 Explicit Tween Configuration
338 ----------------------------
339
340 This value allows you to perform explicit :term:`tween` ordering in your
341 configuration. Tweens are bits of code used by add-on authors to extend
342 Pyramid. They form a chain, and require ordering.
343
344 Ideally, you won't need to use the ``pyramid.tweens`` setting at all. Tweens
345 are generally ordered and included "implicitly" when an add-on package which
346 registers a tween is "included". Packages are included when you name a
347 ``pyramid.includes`` setting in your configuration or when you call
125ea45 @tshepang fix some cross-references
tshepang authored
348 :meth:`pyramid.config.Configurator.include`.
be46dac @mcdonc add pyramid.tweens configuration value docs
mcdonc authored
349
350 Authors of included add-ons provide "implicit" tween configuration ordering
351 hints to Pyramid when their packages are included. However, the implicit
352 tween ordering is only best-effort. Pyramid will attempt to provide an
353 implicit order of tweens as best it can using hints provided by add-on
354 authors, but because it's only best-effort, if very precise tween ordering is
355 required, the only surefire way to get it is to use an explicit tween order.
356 You may be required to inspect your tween ordering (see
357 :ref:`displaying_tweens`) and add a ``pyramid.tweens`` configuration value at
358 the behest of an add-on author.
359
360 +---------------------------------+
361 | Config File Setting Name |
362 +=================================+
363 | ``pyramid.tweens`` |
364 | |
365 | |
366 | |
367 +---------------------------------+
368
3a6bdf9 @tshepang use clearer language
tshepang authored
369 The value assigned to ``pyramid.tweens`` should be a sequence. The
be46dac @mcdonc add pyramid.tweens configuration value docs
mcdonc authored
370 sequence can take several different forms.
371
372 1) It can be a string.
373
374 If it is a string, the tween names can be separated by spaces::
375
376 pkg.tween_factory1 pkg.tween_factory2 pkg.tween_factory3
377
378 The tween names can also be separated by carriage returns::
379
380 pkg.tween_factory1
381 pkg.tween_factory2
382 pkg.tween_factory3
383
384 2) It can be a Python list, where the values are strings::
385
386 ['pkg.tween_factory1', 'pkg.tween_factory2', 'pkg.tween_factory3']
387
388 Each value in the sequence should be a :term:`dotted Python name`.
389
f8869cb @mcdonc remove stray references to Paste
mcdonc authored
390 PasteDeploy Configuration vs. Plain-Python Configuration
391 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
be46dac @mcdonc add pyramid.tweens configuration value docs
mcdonc authored
392
393 Using the following ``pyramid.tweens`` setting in the PasteDeploy ``.ini``
394 file in your application:
395
396 .. code-block:: ini
397
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
398 [app:main]
4736974 @mcdonc garden changes; fix docs rendering
mcdonc authored
399 pyramid.tweens = pyramid_debugtoolbar.toolbar.tween_factory
400 pyramid.tweens.excview_tween_factory
401 pyramid_tm.tm_tween_factory
be46dac @mcdonc add pyramid.tweens configuration value docs
mcdonc authored
402
403 Is equivalent to using the following statements in your configuration code:
404
405 .. code-block:: python
406 :linenos:
407
4736974 @mcdonc garden changes; fix docs rendering
mcdonc authored
408 from pyramid.config import Configurator
409
410 def main(global_config, **settings):
411 settings['pyramid.tweens'] = [
412 'pyramid_debugtoolbar.toolbar.tween_factory',
413 'pyramid.tweebs.excview_tween_factory',
414 'pyramid_tm.tm_tween_factory',
415 ]
416 config = Configurator(settings=settings)
be46dac @mcdonc add pyramid.tweens configuration value docs
mcdonc authored
417
418 It is fine to use both or either form.
419
47b4d3e Docs
Chris McDonough authored
420 Examples
421 --------
422
423 Let's presume your configuration file is named ``MyProject.ini``, and
424 there is a section representing your application named ``[app:main]``
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored
425 within the file that represents your :app:`Pyramid` application.
47b4d3e Docs
Chris McDonough authored
426 The configuration file settings documented in the above "Config File
427 Setting Name" column would go in the ``[app:main]`` section. Here's
2747781 Overlong lines.
Chris McDonough authored
428 an example of such a section:
429
430 .. code-block:: ini
23bfce0 @blaflamme Narrative doc cleanup
blaflamme authored
431 :linenos:
47b4d3e Docs
Chris McDonough authored
432
433 [app:main]
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
434 use = egg:MyProject
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
435 pyramid.reload_templates = true
436 pyramid.debug_authorization = true
47b4d3e Docs
Chris McDonough authored
437
438 You can also use environment variables to accomplish the same purpose
439 for settings documented as such. For example, you might start your
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored
440 :app:`Pyramid` application using the following command line:
2747781 Overlong lines.
Chris McDonough authored
441
23bfce0 @blaflamme Narrative doc cleanup
blaflamme authored
442 .. code-block:: text
47b4d3e Docs
Chris McDonough authored
443
e79d360 @mcdonc - All environment variables which used to be prefixed with ``BFG_`` a…
mcdonc authored
444 $ PYRAMID_DEBUG_AUTHORIZATION=1 PYRAMID_RELOAD_TEMPLATES=1 \
f73f0e3 @tshepang consistency: use $VENV whenever virtualenv binaries are used
tshepang authored
445 $VENV/bin/pserve MyProject.ini
47b4d3e Docs
Chris McDonough authored
446
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored
447 If you started your application this way, your :app:`Pyramid`
47b4d3e Docs
Chris McDonough authored
448 application would behave in the same manner as if you had placed the
449 respective settings in the ``[app:main]`` section of your
450 application's ``.ini`` file.
17ce574 Features
Chris McDonough authored
451
d809ac7 - Add a ``reload_resources`` configuration file setting (aka the
Chris McDonough authored
452 If you want to turn all ``debug`` settings (every setting that starts
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
453 with ``pyramid.debug_``). on in one fell swoop, you can use
e79d360 @mcdonc - All environment variables which used to be prefixed with ``BFG_`` a…
mcdonc authored
454 ``PYRAMID_DEBUG_ALL=1`` as an environment variable setting or you may use
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
455 ``pyramid.debug_all=true`` in the config file. Note that this does not affect
456 settings that do not start with ``pyramid.debug_*`` such as
457 ``pyramid.reload_templates``.
d809ac7 - Add a ``reload_resources`` configuration file setting (aka the
Chris McDonough authored
458
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
459 If you want to turn all ``pyramid.reload`` settings (every setting that starts
460 with ``pyramid.reload_``) on in one fell swoop, you can use
e79d360 @mcdonc - All environment variables which used to be prefixed with ``BFG_`` a…
mcdonc authored
461 ``PYRAMID_RELOAD_ALL=1`` as an environment variable setting or you may use
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
462 ``pyramid.reload_all=true`` in the config file. Note that this does not
463 affect settings that do not start with ``pyramid.reload_*`` such as
464 ``pyramid.debug_notfound``.
d809ac7 - Add a ``reload_resources`` configuration file setting (aka the
Chris McDonough authored
465
496cb6f @caseman add a note explaining why you might want to use envars
caseman authored
466 .. note::
467 Specifying configuration settings via environment variables is generally
468 most useful during development, where you may wish to augment or
469 override the more permanent settings in the configuration file.
470 This is useful because many of the reload and debug settings may
879bb56 @Cito More small fixes made reading the rest of the docs and the tutorials.
Cito authored
471 have performance or security (i.e., disclosure) implications
496cb6f @caseman add a note explaining why you might want to use envars
caseman authored
472 that make them undesirable in a production environment.
473
879bb56 @Cito More small fixes made reading the rest of the docs and the tutorials.
Cito authored
474 .. index::
c5f24b2 Prep for b1
Chris McDonough authored
475 single: reload_templates
92c3e50 @mcdonc resource -> asset
mcdonc authored
476 single: reload_assets
477
478 Understanding the Distinction Between ``reload_templates`` and ``reload_assets``
479 --------------------------------------------------------------------------------
480
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
481 The difference between ``pyramid.reload_assets`` and
482 ``pyramid.reload_templates`` is a bit subtle. Templates are themselves also
483 treated by :app:`Pyramid` as asset files (along with other static files), so the
484 distinction can be confusing. It's helpful to read
485 :ref:`overriding_assets_section` for some context about assets in general.
92c3e50 @mcdonc resource -> asset
mcdonc authored
486
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
487 When ``pyramid.reload_templates`` is true, :app:`Pyramid` takes advantage of the
92c3e50 @mcdonc resource -> asset
mcdonc authored
488 underlying templating systems' ability to check for file modifications to an
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
489 individual template file. When ``pyramid.reload_templates`` is true but
490 ``pyramid.reload_assets`` is *not* true, the template filename returned by the
92c3e50 @mcdonc resource -> asset
mcdonc authored
491 ``pkg_resources`` package (used under the hood by asset resolution) is cached
492 by :app:`Pyramid` on the first request. Subsequent requests for the same
493 template file will return a cached template filename. The underlying
494 templating system checks for modifications to this particular file for every
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
495 request. Setting ``pyramid.reload_templates`` to ``True`` doesn't affect
496 performance dramatically (although it should still not be used in production
497 because it has some effect).
92c3e50 @mcdonc resource -> asset
mcdonc authored
498
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
499 However, when ``pyramid.reload_assets`` is true, :app:`Pyramid` will not cache
500 the template filename, meaning you can see the effect of changing the content
501 of an overridden asset directory for templates without restarting the server
92c3e50 @mcdonc resource -> asset
mcdonc authored
502 after every change. Subsequent requests for the same template file may
503 return different filenames based on the current state of overridden asset
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
504 directories. Setting ``pyramid.reload_assets`` to ``True`` affects performance
92c3e50 @mcdonc resource -> asset
mcdonc authored
505 *dramatically*, slowing things down by an order of magnitude for each
506 template rendering. However, it's convenient to enable when moving files
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
507 around in overridden asset directories. ``pyramid.reload_assets`` makes the
508 system *very slow* when templates are in use. Never set
509 ``pyramid.reload_assets`` to ``True`` on a production system.
d809ac7 - Add a ``reload_resources`` configuration file setting (aka the
Chris McDonough authored
510
6ce1e0c @mcdonc add more index markers
mcdonc authored
511 .. index::
512 par: settings; adding custom
513
0ee9c20 @mcdonc add 'What's new In Pyramid 1.1' document
mcdonc authored
514 .. _adding_a_custom_setting:
515
f6799bb @mcdonc add 'adding a custom settings'
mcdonc authored
516 Adding A Custom Setting
517 -----------------------
518
519 From time to time, you may need to add a custom setting to your application.
520 Here's how:
521
522 - If you're using an ``.ini`` file, change the ``.ini`` file, adding the
523 setting to the ``[app:foo]`` section representing your Pyramid application.
524 For example:
525
526 .. code-block:: ini
527
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
528 [app:main]
f6799bb @mcdonc add 'adding a custom settings'
mcdonc authored
529 # .. other settings
530 debug_frobnosticator = True
531
532 - In the ``main()`` function that represents the place that your Pyramid WSGI
533 application is created, anticipate that you'll be getting this key/value
534 pair as a setting and do any type conversion necessary.
535
536 If you've done any type conversion of your custom value, reset the
537 converted values into the ``settings`` dictionary *before* you pass the
538 dictionary as ``settings`` to the :term:`Configurator`. For example:
539
540 .. code-block:: python
541
542 def main(global_config, **settings):
543 # ...
544 from pyramid.settings import asbool
545 debug_frobnosticator = asbool(settings.get(
546 'debug_frobnosticator', 'false'))
547 settings['debug_frobnosticator'] = debug_frobnosticator
548 config = Configurator(settings=settings)
549
550 .. note:: It's especially important that you mutate the ``settings``
551 dictionary with the converted version of the variable *before* passing
552 it to the Configurator: the configurator makes a *copy* of ``settings``,
553 it doesn't use the one you pass directly.
1feefdb @nek4life Updated environment documentation to include an example of accessing …
nek4life authored
554
555 - When creating an ``includeme`` function that will be later added to your
556 application's configuration you may access the ``settings`` dictionary
557 through the instance of the :term:`Configurator` that is passed into the
558 function as its only argument. For Example:
559
560 .. code-block:: python
561
562 def includeme(config):
563 settings = config.registry.settings
564 debug_frobnosticator = settings['debug_frobnosticator']
70b951b @tshepang improve readability
tshepang authored
565
566 - In the runtime code from where you need to access the new settings value,
567 find the value in the ``registry.settings`` dictionary and use it. In
f6799bb @mcdonc add 'adding a custom settings'
mcdonc authored
568 :term:`view` code (or any other code that has access to the request), the
569 easiest way to do this is via ``request.registry.settings``. For example:
570
571 .. code-block:: python
572
1feefdb @nek4life Updated environment documentation to include an example of accessing …
nek4life authored
573 settings = request.registry.settings
f6799bb @mcdonc add 'adding a custom settings'
mcdonc authored
574 debug_frobnosticator = settings['debug_frobnosticator']
575
576 If you wish to use the value in code that does not have access to the
577 request and you wish to use the value, you'll need to use the
578 :func:`pyramid.threadlocal.get_current_registry` API to obtain the current
579 registry, then ask for its ``settings`` attribute. For example:
580
581 .. code-block:: python
582
583 registry = pyramid.threadlocal.get_current_registry()
584 settings = registry.settings
585 debug_frobnosticator = settings['debug_frobnosticator']
586
879bb56 @Cito More small fixes made reading the rest of the docs and the tutorials.
Cito authored
587
588
f6799bb @mcdonc add 'adding a custom settings'
mcdonc authored
589
Something went wrong with that request. Please try again.