Environment Variables and .ini
File Settings¶
Pyramid behavior can be configured through a combination of operating
system environment variables and .ini
configuration file application
section settings. The meaning of the environment variables and the
configuration file settings overlap.
注釈
Where a configuration file setting exists with the same meaning as an environment variable, and both are present at application startup time, the environment variable setting takes precedence.
The term "configuration file setting name" refers to a key in the .ini
configuration for your application. The configuration file setting names
documented in this chapter are reserved for Pyramid use. You should not
use them to indicate application-specific configuration settings.
Reloading Templates¶
When this value is true, templates are automatically reloaded whenever they are modified without restarting the application, so you can see changes to templates take effect immediately during development. This flag is meaningful to Chameleon and Mako templates, as well as most third-party template rendering extensions.
Environment Variable Name |
Config File Setting Name |
---|---|
|
|
Reloading Assets¶
Don't cache any asset file data when this value is true.
参考
See also Overriding Assets.
Environment Variable Name |
Config File Setting Name |
---|---|
|
|
注釈
For backwards compatibility purposes, aliases can be used for
configuring asset reloading: PYRAMID_RELOAD_RESOURCES
(envvar) and
pyramid.reload_resources
(config file).
Debugging Not Found Errors¶
Print view-related NotFound
debug messages to stderr when this value is
true.
参考
See also NotFound Errors.
Environment Variable Name |
Config File Setting Name |
---|---|
|
|
Debugging Route Matching¶
Print debugging messages related to url dispatch route matching when this value is true.
参考
See also Debugging Route Matching.
Environment Variable Name |
Config File Setting Name |
---|---|
|
|
Preventing HTTP Caching¶
Prevent the http_cache
view configuration argument from having any effect
globally in this process when this value is true. No HTTP caching-related
response headers will be set by the Pyramid http_cache
view
configuration feature when this is true.
参考
See also Influencing HTTP Caching.
Environment Variable Name |
Config File Setting Name |
---|---|
|
|
Preventing Cache Busting¶
Prevent the cachebust
static view configuration argument from having any
effect globally in this process when this value is true. No cache buster will
be configured or used when this is true.
バージョン 1.6 で追加.
参考
See also Cache Busting.
Environment Variable Name |
Config File Setting Name |
---|---|
|
|
Debugging All¶
Turns on all debug*
settings.
Environment Variable Name |
Config File Setting Name |
---|---|
|
|
Reloading All¶
Turns on all reload*
settings.
Environment Variable Name |
Config File Setting Name |
---|---|
|
|
Default Locale Name¶
The value supplied here is used as the default locale name when a locale negotiator is not registered.
参考
See also Localization-Related Deployment Settings.
Environment Variable Name |
Config File Setting Name |
---|---|
|
|
Including Packages¶
pyramid.includes
instructs your application to include other packages.
Using the setting is equivalent to using the
pyramid.config.Configurator.include()
method.
Config File Setting Name |
---|
|
The value assigned to pyramid.includes
should be a sequence. The sequence
can take several different forms.
It can be a string.
If it is a string, the package names can be separated by spaces:
package1 package2 package3
The package names can also be separated by carriage returns:
package1 package2 package3
It can be a Python list, where the values are strings:
['package1', 'package2', 'package3']
Each value in the sequence should be a dotted Python name.
pyramid.includes
vs. pyramid.config.Configurator.include()
¶
Two methods exist for including packages: pyramid.includes
and
pyramid.config.Configurator.include()
. This section explains their
equivalence.
Using PasteDeploy¶
Using the following pyramid.includes
setting in the PasteDeploy .ini
file in your application:
[app:main]
pyramid.includes = pyramid_debugtoolbar
pyramid_tm
Is equivalent to using the following statements in your configuration code:
1from pyramid.config import Configurator
2
3def main(global_config, **settings):
4 config = Configurator(settings=settings)
5 # ...
6 config.include('pyramid_debugtoolbar')
7 config.include('pyramid_tm')
8 # ...
It is fine to use both or either form.
Plain Python¶
Using the following pyramid.includes
setting in your plain-Python Pyramid
application:
1from pyramid.config import Configurator
2
3if __name__ == '__main__':
4 settings = {'pyramid.includes':'pyramid_debugtoolbar pyramid_tm'}
5 config = Configurator(settings=settings)
Is equivalent to using the following statements in your configuration code:
1from pyramid.config import Configurator
2
3if __name__ == '__main__':
4 settings = {}
5 config = Configurator(settings=settings)
6 config.include('pyramid_debugtoolbar')
7 config.include('pyramid_tm')
It is fine to use both or either form.
Explicit Tween Configuration¶
This value allows you to perform explicit tween ordering in your configuration. Tweens are bits of code used by add-on authors to extend Pyramid. They form a chain, and require ordering.
Ideally you won't need to use the pyramid.tweens
setting at all. Tweens
are generally ordered and included "implicitly" when an add-on package which
registers a tween is "included". Packages are included when you name a
pyramid.includes
setting in your configuration or when you call
pyramid.config.Configurator.include()
.
Authors of included add-ons provide "implicit" tween configuration ordering
hints to Pyramid when their packages are included. However, the implicit tween
ordering is only best-effort. Pyramid will attempt to provide an implicit
order of tweens as best it can using hints provided by add-on authors, but
because it's only best-effort, if very precise tween ordering is required, the
only surefire way to get it is to use an explicit tween order. You may be
required to inspect your tween ordering (see ptweens: Displaying "Tweens") and add
a pyramid.tweens
configuration value at the behest of an add-on author.
Config File Setting Name |
---|
|
The value assigned to pyramid.tweens
should be a sequence. The sequence
can take several different forms.
It can be a string.
If it is a string, the tween names can be separated by spaces:
pkg.tween_factory1 pkg.tween_factory2 pkg.tween_factory3
The tween names can also be separated by carriage returns:
pkg.tween_factory1 pkg.tween_factory2 pkg.tween_factory3
It can be a Python list, where the values are strings:
['pkg.tween_factory1', 'pkg.tween_factory2', 'pkg.tween_factory3']
Each value in the sequence should be a dotted Python name.
PasteDeploy Configuration vs. Plain-Python Configuration¶
Using the following pyramid.tweens
setting in the PasteDeploy .ini
file
in your application:
[app:main]
pyramid.tweens = pyramid_debugtoolbar.toolbar.tween_factory
pyramid.tweens.excview_tween_factory
pyramid_tm.tm_tween_factory
Is equivalent to using the following statements in your configuration code:
1from pyramid.config import Configurator
2
3def main(global_config, **settings):
4 settings['pyramid.tweens'] = [
5 'pyramid_debugtoolbar.toolbar.tween_factory',
6 'pyramid.tweebs.excview_tween_factory',
7 'pyramid_tm.tm_tween_factory',
8 ]
9 config = Configurator(settings=settings)
It is fine to use both or either form.
Examples¶
Let's presume your configuration file is named MyProject.ini
, and there is
a section representing your application named [app:main]
within the file
that represents your Pyramid application. The configuration file
settings documented in the above "Config File Setting Name" column would go in
the [app:main]
section. Here's an example of such a section:
1[app:main]
2use = egg:MyProject
3pyramid.reload_templates = true
4pyramid.debug_authorization = true
You can also use environment variables to accomplish the same purpose for settings documented as such. For example, you might start your Pyramid application using the following command line:
PYRAMID_DEBUG_AUTHORIZATION=1 PYRAMID_RELOAD_TEMPLATES=1 \
$VENV/bin/pserve MyProject.ini
If you started your application this way, your Pyramid application would
behave in the same manner as if you had placed the respective settings in the
[app:main]
section of your application's .ini
file.
If you want to turn all debug
settings (every setting that starts with
pyramid.debug_
) on in one fell swoop, you can use PYRAMID_DEBUG_ALL=1
as an environment variable setting or you may use pyramid.debug_all=true
in
the config file. Note that this does not affect settings that do not start
with pyramid.debug_*
such as pyramid.reload_templates
.
If you want to turn all pyramid.reload
settings (every setting that starts
with pyramid.reload_
) on in one fell swoop, you can use
PYRAMID_RELOAD_ALL=1
as an environment variable setting or you may use
pyramid.reload_all=true
in the config file. Note that this does not affect
settings that do not start with pyramid.reload_*
such as
pyramid.debug_notfound
.
注釈
Specifying configuration settings via environment variables is generally most useful during development, where you may wish to augment or override the more permanent settings in the configuration file. This is useful because many of the reload and debug settings may have performance or security (i.e., disclosure) implications that make them undesirable in a production environment.
Understanding the Distinction Between reload_templates
and reload_assets
¶
The difference between pyramid.reload_assets
and
pyramid.reload_templates
is a bit subtle. Templates are themselves also
treated by Pyramid as asset files (along with other static files), so
the distinction can be confusing. It's helpful to read
Overriding Assets for some context about assets in general.
When pyramid.reload_templates
is true, Pyramid takes advantage of
the underlying templating system's ability to check for file modifications to
an individual template file. When pyramid.reload_templates
is true, but
pyramid.reload_assets
is not true, the template filename returned by the
pkg_resources
package (used under the hood by asset resolution) is cached
by Pyramid on the first request. Subsequent requests for the same
template file will return a cached template filename. The underlying
templating system checks for modifications to this particular file for every
request. Setting pyramid.reload_templates
to True
doesn't affect
performance dramatically (although it should still not be used in production
because it has some effect).
However, when pyramid.reload_assets
is true, Pyramid will not cache
the template filename, meaning you can see the effect of changing the content
of an overridden asset directory for templates without restarting the server
after every change. Subsequent requests for the same template file may return
different filenames based on the current state of overridden asset directories.
Setting pyramid.reload_assets
to True
affects performance
dramatically, slowing things down by an order of magnitude for each template
rendering. However, it's convenient to enable when moving files around in
overridden asset directories. pyramid.reload_assets
makes the system very
slow when templates are in use. Never set pyramid.reload_assets
to
True
on a production system.
Adding a Custom Setting¶
From time to time, you may need to add a custom setting to your application. Here's how:
If you're using an
.ini
file, change the.ini
file, adding the setting to the[app:foo]
section representing your Pyramid application. For example:[app:main] # .. other settings debug_frobnosticator = True
In the
main()
function that represents the place that your Pyramid WSGI application is created, anticipate that you'll be getting this key/value pair as a setting and do any type conversion necessary.If you've done any type conversion of your custom value, reset the converted values into the
settings
dictionary before you pass the dictionary assettings
to the Configurator. For example:def main(global_config, **settings): # ... from pyramid.settings import asbool debug_frobnosticator = asbool(settings.get( 'debug_frobnosticator', 'false')) settings['debug_frobnosticator'] = debug_frobnosticator config = Configurator(settings=settings)
注釈
It's especially important that you mutate the
settings
dictionary with the converted version of the variable before passing it to the Configurator: the configurator makes a copy ofsettings
, it doesn't use the one you pass directly.When creating an
includeme
function that will be later added to your application's configuration you may access thesettings
dictionary through the instance of the Configurator that is passed into the function as its only argument. For Example:
def includeme(config): settings = config.registry.settings debug_frobnosticator = settings['debug_frobnosticator']
In the runtime code from where you need to access the new settings value, find the value in the
registry.settings
dictionary and use it. In view code (or any other code that has access to the request), the easiest way to do this is viarequest.registry.settings
. For example:settings = request.registry.settings debug_frobnosticator = settings['debug_frobnosticator']
If you wish to use the value in code that does not have access to the request and you wish to use the value, you'll need to use the
pyramid.threadlocal.get_current_registry()
API to obtain the current registry, then ask for itssettings
attribute. For example:registry = pyramid.threadlocal.get_current_registry() settings = registry.settings debug_frobnosticator = settings['debug_frobnosticator']