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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
.. _configuration:
Configuring Pecan Applications
==============================
Pecan is very easy to configure. As long as you follow certain conventions,
using, setting and dealing with configuration should be very intuitive.
Pecan configuration files are pure Python. Each "section" of the
configuration is a dictionary assigned to a variable name in the
configuration module.
Default Values
---------------
Below is the complete list of default values the framework uses::
server = {
'port' : '8080',
'host' : '0.0.0.0'
}
app = {
'root' : None,
'modules' : [],
'static_root' : 'public',
'template_path' : ''
}
.. _application_configuration:
Application Configuration
-------------------------
The ``app`` configuration values are used by Pecan to wrap your
application into a valid `WSGI app
<http://www.wsgi.org/en/latest/what.html>`_. The ``app`` configuration
is specific to your application, and includes values like the root
controller class location.
A typical application configuration might look like this::
app = {
'root' : 'project.controllers.root.RootController',
'modules' : ['project'],
'static_root' : '%(confdir)s/public',
'template_path' : '%(confdir)s/project/templates',
'debug' : True
}
Let's look at each value and what it means:
**modules**
A list of modules where pecan will search for applications.
Generally this should contain a single item, the name of your
project's python package. At least one of the listed modules must
contain an ``app.setup_app`` function which is called to create the
WSGI app. In other words, this package should be where your
``app.py`` file is located, and this file should contain a
``setup_app`` function.
**root**
The root controller of your application. Remember to provide a
string representing a Python path to some callable (e.g.,
``"yourapp.controllers.root.RootController"``).
**static_root**
The directory where your static files can be found (relative to
the project root). Pecan comes with middleware that can
be used to serve static files (like CSS and Javascript files) during
development.
**template_path**
Points to the directory where your template files live (relative to
the project root).
**debug**
Enables ``WebError`` to display tracebacks in the browser
.. warning::
``app`` is a reserved variable name for that section of the
configuration, so make sure you don't override it.
.. warning::
Make sure **debug** is *always* set to ``False`` in production environments.
.. seealso::
* :ref:`app_template`
.. _server_configuration:
Server Configuration
--------------------
Pecan provides some sane defaults. Change these to alter the host and port your
WSGI app is served on.
::
server = {
'port' : '8080',
'host' : '0.0.0.0'
}
Additional Configuration
------------------------
Your application may need access to other configuration values at
runtime (like third-party API credentials). Put these settings in
their own blocks in your configuration file.
::
twitter = {
'api_key' : 'FOO',
'api_secret' : 'SECRET'
}
.. _accessibility:
Accessing Configuration at Runtime
----------------------------------
You can access any configuration value at runtime via :py:mod:`pecan.conf`.
This includes custom, application, and server-specific values.
For example, if you needed to specify a global administrator, you could
do so like this within the configuration file.
::
administrator = 'foo_bar_user'
And it would be accessible in :py:mod:`pecan.conf` as::
>>> from pecan import conf
>>> conf.administrator
'foo_bar_user'
Dictionary Conversion
---------------------
In certain situations you might want to deal with keys and values, but in strict
dictionary form. The :class:`Config` object has a helper method for this purpose
that will return a dictionary representation of the configuration, including nested values.
Below is a representation of how you can access the :func:`as_dict` method and what
it returns as a result (shortened for brevity):
::
>>> from pecan import conf
>>> conf
Config({'app': Config({'errors': {}, 'template_path': '', 'static_root': 'public', [...]
>>> conf.as_dict()
{'app': {'errors': {}, 'template_path': '', 'static_root': 'public', [...]
Prefixing Dictionary Keys
-------------------------
:func:`Config.as_dict` allows you to pass an optional string argument
if you need to prefix the keys in the returned dictionary.
::
>>> from pecan import conf
>>> conf
Config({'app': Config({'errors': {}, 'template_path': '', 'static_root': 'public', [...]
>>> conf.as_dict('prefixed_')
{'prefixed_app': {'prefixed_errors': {}, 'prefixed_template_path': '', 'prefixed_static_root': 'prefixed_public', [...]
|
