Navigation

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.

Note

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.

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.

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.

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
Displaying "Tweens") and add a pyramid.tweens configuration value at
the behest of an add-on author.

Config File Setting Name

pyramid.tweens

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

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:

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.

Note

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 systems' 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.

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 of settings,
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 the settings dictionary
through the instance of the Configurator that is passed into the
function as its only argument. For Example:

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 via request.registry.settings. For example:

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 its settings attribute. For example: