1 """
2 Configuration system for CherryPy.
3
4 Configuration in CherryPy is implemented via dictionaries. Keys are strings
5 which name the mapped value, which may be of any type.
6
7
8 Architecture
9 ------------
10
11 CherryPy Requests are part of an Application, which runs in a global context,
12 and configuration data may apply to any of those three scopes:
13
14 Global
15 Configuration entries which apply everywhere are stored in
16 cherrypy.config.
17
18 Application
19 Entries which apply to each mounted application are stored
20 on the Application object itself, as 'app.config'. This is a two-level
21 dict where each key is a path, or "relative URL" (for example, "/" or
22 "/path/to/my/page"), and each value is a config dict. Usually, this
23 data is provided in the call to tree.mount(root(), config=conf),
24 although you may also use app.merge(conf).
25
26 Request
27 Each Request object possesses a single 'Request.config' dict.
28 Early in the request process, this dict is populated by merging global
29 config entries, Application entries (whose path equals or is a parent
30 of Request.path_info), and any config acquired while looking up the
31 page handler (see next).
32
33
34 Declaration
35 -----------
36
37 Configuration data may be supplied as a Python dictionary, as a filename,
38 or as an open file object. When you supply a filename or file, CherryPy
39 uses Python's builtin ConfigParser; you declare Application config by
40 writing each path as a section header::
41
42 [/path/to/my/page]
43 request.stream = True
44
45 To declare global configuration entries, place them in a [global] section.
46
47 You may also declare config entries directly on the classes and methods
48 (page handlers) that make up your CherryPy application via the ``_cp_config``
49 attribute. For example::
50
51 class Demo:
52 _cp_config = {'tools.gzip.on': True}
53
54 def index(self):
55 return "Hello world"
56 index.exposed = True
57 index._cp_config = {'request.show_tracebacks': False}
58
59 .. note::
60
61 This behavior is only guaranteed for the default dispatcher.
62 Other dispatchers may have different restrictions on where
63 you can attach _cp_config attributes.
64
65
66 Namespaces
67 ----------
68
69 Configuration keys are separated into namespaces by the first "." in the key.
70 Current namespaces:
71
72 engine
73 Controls the 'application engine', including autoreload.
74 These can only be declared in the global config.
75
76 tree
77 Grafts cherrypy.Application objects onto cherrypy.tree.
78 These can only be declared in the global config.
79
80 hooks
81 Declares additional request-processing functions.
82
83 log
84 Configures the logging for each application.
85 These can only be declared in the global or / config.
86
87 request
88 Adds attributes to each Request.
89
90 response
91 Adds attributes to each Response.
92
93 server
94 Controls the default HTTP server via cherrypy.server.
95 These can only be declared in the global config.
96
97 tools
98 Runs and configures additional request-processing packages.
99
100 wsgi
101 Adds WSGI middleware to an Application's "pipeline".
102 These can only be declared in the app's root config ("/").
103
104 checker
105 Controls the 'checker', which looks for common errors in
106 app state (including config) when the engine starts.
107 Global config only.
108
109 The only key that does not exist in a namespace is the "environment" entry.
110 This special entry 'imports' other config entries from a template stored in
111 cherrypy._cpconfig.environments[environment]. It only applies to the global
112 config, and only when you use cherrypy.config.update.
113
114 You can define your own namespaces to be called at the Global, Application,
115 or Request level, by adding a named handler to cherrypy.config.namespaces,
116 app.namespaces, or app.request_class.namespaces. The name can
117 be any string, and the handler must be either a callable or a (Python 2.5
118 style) context manager.
119 """
120
121 import cherrypy
122 from cherrypy._cpcompat import set, basestring
123 from cherrypy.lib import reprconf
124
125
126 NamespaceSet = reprconf.NamespaceSet
127
128
130 """Merge one app config (from a dict, file, or filename) into another.
131
132 If the given config is a filename, it will be appended to
133 the list of files to monitor for "autoreload" changes.
134 """
135 if isinstance(other, basestring):
136 cherrypy.engine.autoreload.files.add(other)
137
138
139 for section, value_map in reprconf.as_dict(other).items():
140 if not isinstance(value_map, dict):
141 raise ValueError(
142 "Application config must include section headers, but the "
143 "config you tried to merge doesn't have any sections. "
144 "Wrap your config in another dict with paths as section "
145 "headers, for example: {'/': config}.")
146 base.setdefault(section, {}).update(value_map)
147
148
149 -class Config(reprconf.Config):
150
151 """The 'global' configuration data for the entire CherryPy process."""
152
159
169
171 """Decorator for page handlers to set _cp_config."""
172 if args:
173 raise TypeError(
174 "The cherrypy.config decorator does not accept positional "
175 "arguments; you must use keyword arguments.")
176
177 def tool_decorator(f):
178 if not hasattr(f, "_cp_config"):
179 f._cp_config = {}
180 for k, v in kwargs.items():
181 f._cp_config[k] = v
182 return f
183 return tool_decorator
184
185
186
187 Config.environments = environments = {
188 "staging": {
189 'engine.autoreload.on': False,
190 'checker.on': False,
191 'tools.log_headers.on': False,
192 'request.show_tracebacks': False,
193 'request.show_mismatched_params': False,
194 },
195 "production": {
196 'engine.autoreload.on': False,
197 'checker.on': False,
198 'tools.log_headers.on': False,
199 'request.show_tracebacks': False,
200 'request.show_mismatched_params': False,
201 'log.screen': False,
202 },
203 "embedded": {
204
205 'engine.autoreload.on': False,
206 'checker.on': False,
207 'tools.log_headers.on': False,
208 'request.show_tracebacks': False,
209 'request.show_mismatched_params': False,
210 'log.screen': False,
211 'engine.SIGHUP': None,
212 'engine.SIGTERM': None,
213 },
214 "test_suite": {
215 'engine.autoreload.on': False,
216 'checker.on': False,
217 'tools.log_headers.on': False,
218 'request.show_tracebacks': True,
219 'request.show_mismatched_params': True,
220 'log.screen': False,
221 },
222 }
223
224
225
251 Config.namespaces["server"] = _server_namespace_handler
252
253
255 """Backward compatibility handler for the "engine" namespace."""
256 engine = cherrypy.engine
257
258 deprecated = {
259 'autoreload_on': 'autoreload.on',
260 'autoreload_frequency': 'autoreload.frequency',
261 'autoreload_match': 'autoreload.match',
262 'reload_files': 'autoreload.files',
263 'deadlock_poll_freq': 'timeout_monitor.frequency'
264 }
265
266 if k in deprecated:
267 engine.log(
268 'WARNING: Use of engine.%s is deprecated and will be removed in a '
269 'future version. Use engine.%s instead.' % (k, deprecated[k]))
270
271 if k == 'autoreload_on':
272 if v:
273 engine.autoreload.subscribe()
274 else:
275 engine.autoreload.unsubscribe()
276 elif k == 'autoreload_frequency':
277 engine.autoreload.frequency = v
278 elif k == 'autoreload_match':
279 engine.autoreload.match = v
280 elif k == 'reload_files':
281 engine.autoreload.files = set(v)
282 elif k == 'deadlock_poll_freq':
283 engine.timeout_monitor.frequency = v
284 elif k == 'SIGHUP':
285 engine.listeners['SIGHUP'] = set([v])
286 elif k == 'SIGTERM':
287 engine.listeners['SIGTERM'] = set([v])
288 elif "." in k:
289 plugin, attrname = k.split(".", 1)
290 plugin = getattr(engine, plugin)
291 if attrname == 'on':
292 if v and hasattr(getattr(plugin, 'subscribe', None), '__call__'):
293 plugin.subscribe()
294 return
295 elif (
296 (not v) and
297 hasattr(getattr(plugin, 'unsubscribe', None), '__call__')
298 ):
299 plugin.unsubscribe()
300 return
301 setattr(plugin, attrname, v)
302 else:
303 setattr(engine, k, v)
304 Config.namespaces["engine"] = _engine_namespace_handler
305
306
317 Config.namespaces["tree"] = _tree_namespace_handler
318