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
|
.. _environment_chapter:
Environment and Configuration
=============================
:mod:`repoze.bfg` 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
:mod:`repoze.bfg` use. You should not use them to indicate
application-specific configuration settings.
+---------------------------------+-----------------------------+----------------------------------------+
| Environment Variable Name | Config File Setting Name | Further Information |
+=================================+=============================+========================================+
| ``BFG_RELOAD_TEMPLATES`` | ``reload_templates`` | Reload templates without restart |
| | | when true |
| | | See also: |
| | | :ref:`reload_templates_section` |
+---------------------------------+-----------------------------+----------------------------------------+
| ``BFG_RELOAD_RESOURCES`` | ``reload_resources`` | Don't cache any resource file data |
| | | when true |
| | | See also: |
| | | :ref:`overriding_resources_section` |
+---------------------------------+-----------------------------+----------------------------------------+
| ``BFG_DEBUG_AUTHORIZATION`` | ``debug_authorization`` | Print view authorization failure & |
| | | success info to stderr when true |
| | | See also: |
| | | :ref:`debug_authorization_section` |
+---------------------------------+-----------------------------+----------------------------------------+
| ``BFG_DEBUG_NOTFOUND`` | ``debug_notfound`` | Print view-related NotFound debug |
| | | messages to stderr when true |
| | | See also: |
| | | :ref:`debug_notfound_section` |
+---------------------------------+-----------------------------+----------------------------------------+
| ``BFG_DEBUG_ALL`` | ``debug_all`` | Turns all debug_* settings on. |
+---------------------------------+-----------------------------+----------------------------------------+
| ``BFG_RELOAD_ALL`` | ``reload_all`` | Turns all reload_* settings on. |
+---------------------------------+-----------------------------+----------------------------------------+
| ``BFG_CONFIGURE_ZCML`` | ``configure_zcml`` | Use the specified filename to load |
| | | the :term:`application registry` |
| | | instead of the filename implied by |
| | | ``filename`` value passed to |
| | | ``repoze.bfg.router.make_app``. If |
| | | this is a relative filename, it will |
| | | be considered relative to the |
| | | ``package`` passed to ``make_app`` |
| | | by the application. It may also |
| | | take the form of a resource |
| | | "specification" which names both the |
| | | package name and a package-relative |
| | | filename, e.g. |
| | | ``dotted.package.name:path/to.zcml``. |
| | | If it is a resource specification, |
| | | both the *package* and the |
| | | *filename* passed to ``make_app`` |
| | | are overridden with the implied |
| | | values. |
+---------------------------------+-----------------------------+----------------------------------------+
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 :mod:`repoze.bfg` 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::
[app:main]
use = egg:MyProject#app
reload_templates = true
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
:mod:`repoze.bfg` application using the following command line::
BFG_DEBUG_AUTHORIZATION=1 BFG_RELOAD_TEMPLATES=1 bin/paster serve MyProject.ini
If you started your application this way, your :mod:`repoze.bfg`
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 ``debug_``). on in one fell swoop, you can use
``BFG_DEBUG_ALL=1`` as an environment variable setting or you may use
``debug_all=true`` in the config file. Note that this does not effect
settings that do not start with ``debug_*`` such as
``reload_templates``.
If you want to turn all ``reload`` settings (every setting that starts
with ``reload_``). on in one fell swoop, you can use
``BFG_RELOAD_ALL=1`` as an environment variable setting or you may use
``reload_all=true`` in the config file. Note that this does not
effect settings that do not start with ``reload_*`` such as
``debug_notfound``.
Understanding the Distinction Between ``reload_templates`` and ``reload_resources``
-----------------------------------------------------------------------------------
The difference between ``reload_resources`` and ``reload_templates``
is a bit subtle. Templates are themselves also treated by
:mod:`repoze.bfg` as :term:`pkg_resources` resource files (along with
static files and other resources), so the distinction can be
confusing. It's helpful to read :ref:`overriding_resources_section`
for some context about resources in general.
When ``reload_templates`` is true, :mod:`repoze.bfg`` takes advantage
of the underlying templating systems' ability to check for file
modifications to an individual template file. When
``reload_templates`` is true but ``reload_resources`` is *not* true,
the template filename returned by pkg_resources is cached by
:mod:`repoze.bfg` 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 ``reload_templates`` to
``True`` doesn't effect performance dramatically (although it should
still not be used in production because it has some effect).
However, when ``reload_resources`` is true, :mod:`repoze.bfg` will not
cache the template filename, meaning you can see the effect of
changing the content of an overridden resource 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 resource directories. Setting
``reload_resources`` to ``True`` effects performance *dramatically*
(slowing things down by an order of magnitude for each template
rendering) but it's convenient when moving files around in overridden
resource directories. ``reload_resources`` makes the system *very
slow* when templates are in use. Never set ``reload_resources`` to
``True`` on a production system.
|
