Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 488 lines (320 sloc) 18.311 kB
137b769 @bbangert Doc updates
bbangert authored
1 .. _configuration:
2
3 =============
4 Configuration
5 =============
6
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
7 Pylons comes with two main ways to configure an application:
8
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
9 * The configuration file (:ref:`run-config`)
10 * The application's ``config`` directory
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
11
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
12 The files in the ``config`` directory change certain aspects of how the application behaves. Any options that the webmaster should be able to change during deployment should be specified in a configuration file.
137b769 @bbangert Doc updates
bbangert authored
13
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
14 .. tip::
15 A good indicator of whether an option should be set in the ``config`` directory code vs. the configuration file is whether or not the option is necessary for the functioning of the application. If the application won't function without the setting, it belongs in the appropriate :file:`config/` directory file. If the option should be changed depending on deployment, it belongs in the :ref:`run-config`.
137b769 @bbangert Doc updates
bbangert authored
16
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
17 The applications :file:`config/` directory includes:
137b769 @bbangert Doc updates
bbangert authored
18
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
19 * :file:`config/environment.py` described in :ref:`environment-config`
20 * :file:`config/middleware.py` described in :ref:`middleware-config`
ebc508f @pjenvey small updates, mostly from the latest template. fix a typo
pjenvey authored
21 * :file:`config/deployment.ini_tmpl` described in :ref:`production-config`
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
22 * :file:`config/routing.py` described in :ref:`url-config`
b6d3a6e Added the onion
kelvin@Trinity.local authored
23
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
24 Each of these files allows developers to change key aspects of how the application behaves.
b6d3a6e Added the onion
kelvin@Trinity.local authored
25
137b769 @bbangert Doc updates
bbangert authored
26 .. _run-config:
27
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
28 *********************
c85feb4 @bbangert More doc updates
bbangert authored
29 Runtime Configuration
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
30 *********************
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
31
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
32 When a new project is created a sample configuration file called :file:`development.ini` is automatically produced as one of the project files. This default configuration file contains sensible options for development use, for example when developing a Pylons application it is very useful to be able to see a debug report every time an error occurs. The :file:`development.ini` file includes options to enable debug mode so these errors are shown.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
33
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
34 Since the configuration file is used to determine which application is run, multiple configuration files can be used to easily toggle sets of options. Typically a developer might have a ``development.ini`` configuration file for testing and a ``production.ini`` file produced by the :command:`paster make-config` command for testing the command produces sensible production output. A :file:`test.ini` configuration is also included in the project for test-specific options.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
35
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
36 To specify a configuration file to use when running the application, change the last part of the :command:`paster serve` to include the desired config file:
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
37
38 .. code-block :: bash
39
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
40 $ paster serve production.ini
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
41
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
42 .. seealso::
43 Configuration file format **and options** are described in great detail in the `Paste Deploy documentation <http://pythonpaste.org/deploy/>`_.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
44
45
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
46 Getting Information From Configuration Files
47 ============================================
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
48
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
49 All information from the configuration file is available in the ``pylons.config`` object. ``pylons.config`` also contains application configuration as defined in the project's :file:`config.environment` module.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
50
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
51 .. code-block :: python
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
52
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
53 from pylons import config
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
54
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
55 ``pylons.config`` behaves like a dictionary. For example, if the configuration file has an entry under the ``[app:main]`` block:
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
56
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
57 .. code-block :: ini
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
58
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
59 cache_dir = %(here)s/data
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
60
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
61 That can then be read in the projects code:
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
62
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
63 .. code-block :: python
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
64
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
65 from pylons import config
81128e9 @bbangert Doc fix
bbangert authored
66 cache_dir = config['cache.dir']
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
67
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
68 Or the current debug status like this:
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
69
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
70 .. code-block :: python
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
71
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
72 debug = config['debug']
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
73
2b1c94a @bbangert Finished configuration section
bbangert authored
74 Evaluating Non-string Data in Configuration Files
75 -------------------------------------------------
76
77 By default, all the values in the configuration file are considered strings.
78 To make it easier to handle boolean values, the Paste library comes with a
79 function that will convert ``true`` and ``false`` to proper Python boolean
80 values:
81
82 .. code-block :: python
83
84 from paste.deploy.converters import asbool
85
86 debug = asbool(config['debug'])
87
88 This is used already in the default projects' :ref:`middleware-config` to
89 toggle middleware that should only be used in development mode (with
90 ``debug``) set to true.
91
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
92
ebc508f @pjenvey small updates, mostly from the latest template. fix a typo
pjenvey authored
93 .. _production-config:
94
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
95 Production Configuration Files
96 ==============================
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
97
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
98 To change the defaults of the configuration INI file that should be used when deploying the application, edit the :file:`config/deployment.ini_tmpl` file. This is the file that will be used as a template during deployment, so that the person handling deployment has a starting point of the minimum options the application needs set.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
99
ebc508f @pjenvey small updates, mostly from the latest template. fix a typo
pjenvey authored
100 One of the most important options set in the deployment ini is the ``debug = true`` setting. The email options should be setup so that errors can be e-mailed to the appropriate developers or webmaster in the event of an application error.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
101
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
102 Generating the Production Configuration
103 ---------------------------------------
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
104
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
105 To generate the production.ini file from the projects' :file:`config/deployment.ini_tmpl` it must first be installed either as an :term:`egg` or under development mode. Assuming the name of the Pylons application is ``helloworld``, run:
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
106
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
107 .. code-block :: bash
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
108
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
109 $ paster make-config helloworld production.ini
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
110
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
111 .. note::
112 This command will also work from inside the project when its being developed.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
113
ebc508f @pjenvey small updates, mostly from the latest template. fix a typo
pjenvey authored
114 It is the responsibility of the developer to ensure that a sensible set of default configuration values exist when the webmaster uses the ``paster make-config`` command.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
115
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
116 .. warning::
117 **Always** make sure that the ``debug`` is set to ``false`` when deploying a Pylons application.
137b769 @bbangert Doc updates
bbangert authored
118
119
c85feb4 @bbangert More doc updates
bbangert authored
120 .. _environment-config:
137b769 @bbangert Doc updates
bbangert authored
121
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
122 ***********
c85feb4 @bbangert More doc updates
bbangert authored
123 Environment
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
124 ***********
c85feb4 @bbangert More doc updates
bbangert authored
125
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
126 The :file:`config/environment.py` module sets up the basic Pylons environment
c85feb4 @bbangert More doc updates
bbangert authored
127 variables needed to run the application. Objects that should be setup once
128 for the entire application should either be setup here, or in the
8255571 @ches small doc typo - `__init__` method, not file
ches authored
129 :file:`lib/app_globals` :meth:`__init__` method.
c85feb4 @bbangert More doc updates
bbangert authored
130
131 It also calls the :ref:`url-config` function to setup how the URL's will
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
132 be matched up to :ref:`controllers`, creates the :term:`app_globals`
c85feb4 @bbangert More doc updates
bbangert authored
133 object, configures which module will be referred to as :term:`h`, and is
134 where the template engine is setup.
135
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
136 When using SQLAlchemy it's recommended that the SQLAlchemy engine be setup
137 in this module. The default SQLAlchemy configuration that Pylons comes
138 with creates the engine here which is then used in :file:`model/__init__.py`.
c85feb4 @bbangert More doc updates
bbangert authored
139
140
141 .. _url-config:
142
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
143 *****************
c85feb4 @bbangert More doc updates
bbangert authored
144 URL Configuration
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
145 *****************
c85feb4 @bbangert More doc updates
bbangert authored
146
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
147 A Python library called Routes handles mapping URLs to controllers and their methods, or their :term:`action` as Routes refers to them. By default, Pylons sets up the following :term:`route`\s (found in :file:`config/routing.py`):
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
148
149 .. code-block:: python
150
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
151 map.connect('/{controller}/{action}')
152 map.connect('/{controller}/{action}/{id}')
153
154 .. versionchanged:: 0.9.7
155 Prior to Routes 1.9, all map.connect statements required variable parts
156 to begin with a ``:`` like ``map.connect(':controller/:action')``. This
157 syntax is now optional, and the new ``{}`` syntax is recommended.
158
82af045 @bbangert Re-org of some sections
bbangert authored
159 Any part of the path inside the curly braces is a variable (a `variable part`
160 ) that will match
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
161 any text in the URL for that 'part'. A 'part' of the URL is the text between
162 two forward slashes. Every part of the URL must be present for the
163 :term:`route` to match, otherwise a 404 will be returned.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
164
82af045 @bbangert Re-org of some sections
bbangert authored
165 The routes above are translated by the Routes library into regular expressions
166 for high performance URL matching. By default, all the variable parts (except
167 for the special case of ``{controller}``) become a matching regular expression
168 of ``[^/]+`` to match anything except for a forward slash. This can be
169 changed easily, for example to have the ``{id}`` only match digits:
170
171 .. code-block :: python
172
173 map.connect('/{controller}/{action}/{id:\d+}')
174
175 If the desired regular expression includes the ``{}``, then it should be
176 specified separately for the variable part. To limit the ``{id}`` to only
177 match at least 2-4 digits:
178
179 .. code-block :: python
180
181 map.connect('/{controller}/{action}/{id}', requirements=dict(id='\d{2,4}'))
182
183 The controller and action can also be specified as keyword arguments so that
184 they don't need to be included in the URL:
185
186 .. code-block :: python
187
188 # Archives by 2 digit year -> /archives/08
189 map.connect('/archives/{year:\d\d}', controller='articles', action='archives')
190
191 Any variable part, or keyword argument in the ``map.connect`` statement will
192 be available for use in the
193 action used. For the route above, which resolves to the `articles`
194 controller:
195
196 .. code-block :: python
197
198 class ArticlesController(BaseController):
e24cdfc @pjenvey update per pylons.url
pjenvey authored
199
82af045 @bbangert Re-org of some sections
bbangert authored
200 def archives(self, year):
e24cdfc @pjenvey update per pylons.url
pjenvey authored
201 ...
82af045 @bbangert Re-org of some sections
bbangert authored
202
203 The part of the URL that matched as the year is available by name in the
204 function argument.
205
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
206 .. note::
207 Routes also includes the ability to attempt to 'minimize' the URL. This
208 behavior is generally not intuitive, and starting in Pylons 0.9.7 is
209 turned off by default with the ``map.minimization=False`` setting.
210
211 The default mapping can match to any controller and any of their
212 actions which means the following URLs will match:
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
213
214 .. code-block:: text
215
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
216 /hello/index >> controller: hello, action: index
217 /entry/view/4 >> controller: entry, action: view, id:4
218 /comment/edit/2 >> controller: comment, action: edit, id:2
219
220 This simple scheme can be suitable for even large applications when complex URL's aren't needed.
221
222 Controllers can be organized into directories as well. For example, if the admins should have a separate ``comments`` controller:
223
224 .. code-block:: bash
225
226 $ paster controller admin/comments
227
228 Will create the ``admin`` directory along with the appropriate ``comments``
229 controller under it. To get to the comments controller:
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
230
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
231 .. code-block:: text
232
233 /admin/comments/index >> controller: admin/comments, action: index
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
234
83b5741 @bbangert Tweak url config
bbangert authored
235 .. note::
236 The ``{controller}`` match is special, in that it doesn't always stop
237 at the next forward slash (``/``). As the example above demonstrates,
238 it is able to match controllers nested under a directory should they
239 exist.
240
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
241 Adding a route to match ``/``
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
242 =============================
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
243
244 The controller and action can be specified directly in the :meth:`map.connect`
d1791a3 @pjenvey mention how the default public/index.html interacts with a / route
pjenvey authored
245 statement, as well as the raw URL to be matched:
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
246
247 .. code-block:: python
248
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
249 map.connect('/', controller='main', action='index')
250
d1791a3 @pjenvey mention how the default public/index.html interacts with a / route
pjenvey authored
251 results in ``/`` being handled by the ``index`` method of the ``main``
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
252 controller.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
253
d1791a3 @pjenvey mention how the default public/index.html interacts with a / route
pjenvey authored
254 .. note::
255 By default, projects' static files (in the :file:`public/` directory) are
256 served in preference to controllers. New Pylons projects include a welcome
257 page (:file:`public/index.html`) that shows up at the ``/`` url. You'll
258 want to remove this file before mapping a route there.
259
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
260 Generating URLs
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
261 ===============
262
e24cdfc @pjenvey update per pylons.url
pjenvey authored
263 URLs are generated via the callable :class:`routes.util.URLGenerator`
264 object. Pylons provides an instance of this special object at
265 :data:`pylons.url`. It accepts keyword arguments indicating the desired
266 controller, action and additional variables defined in a route.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
267
268 .. code-block:: python
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
269
270 # generates /content/view/2
e24cdfc @pjenvey update per pylons.url
pjenvey authored
271 url(controller='content', action='view', id=2)
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
272
e24cdfc @pjenvey update per pylons.url
pjenvey authored
273 To generate the URL of the matched route of the current request, call
274 :meth:`routes.util.URLGenerator.current`:
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
275
276 .. code-block:: python
277
e24cdfc @pjenvey update per pylons.url
pjenvey authored
278 # Generates /content/view/3 during a request for /content/view/3
279 url.current()
280
281 :meth:`routes.util.URLGenerator.current` also accepts the same arguments as
282 `url()`. This uses `Routes memory
283 <http://routes.groovie.org/manual.html#route-memory>`_ to generate a small
284 change to the current URL without the need to specify all the relevant
285 arguments:
286
287 .. code-block:: python
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
288
e24cdfc @pjenvey update per pylons.url
pjenvey authored
289 # Generates /content/view/2 during a request for /content/view/3
290 url.current(id=2)
c85feb4 @bbangert More doc updates
bbangert authored
291
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
292 .. seealso::
293
294 `Routes manual <http://routes.groovie.org/manual.html>`_
295 Full details and source code.
c85feb4 @bbangert More doc updates
bbangert authored
296
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
297
c85feb4 @bbangert More doc updates
bbangert authored
298 .. _middleware-config:
299
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
300 **********
c85feb4 @bbangert More doc updates
bbangert authored
301 Middleware
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
302 **********
c85feb4 @bbangert More doc updates
bbangert authored
303
aabcb3c @bbangert Adding concepts section, moving explanation of middleware to it
bbangert authored
304 A projects WSGI stack should be setup in the :file:`config/middleware.py`
305 module. Ideally this file should import middleware it needs, and set it up
306 in the `make_app` function.
b6d3a6e Added the onion
kelvin@Trinity.local authored
307
aabcb3c @bbangert Adding concepts section, moving explanation of middleware to it
bbangert authored
308 The default stack that is setup for a Pylons application is described in
309 detail in :ref:`wsgi-middleware`.
b6d3a6e Added the onion
kelvin@Trinity.local authored
310
aabcb3c @bbangert Adding concepts section, moving explanation of middleware to it
bbangert authored
311 Default middleware stack:
b6d3a6e Added the onion
kelvin@Trinity.local authored
312
aabcb3c @bbangert Adding concepts section, moving explanation of middleware to it
bbangert authored
313 .. code-block :: python
b6d3a6e Added the onion
kelvin@Trinity.local authored
314
aabcb3c @bbangert Adding concepts section, moving explanation of middleware to it
bbangert authored
315 # The Pylons WSGI app
316 app = PylonsApp()
317
318 # Routing/Session/Cache Middleware
319 app = RoutesMiddleware(app, config['routes.map'])
320 app = SessionMiddleware(app, config)
321 app = CacheMiddleware(app, config)
322
ebc508f @pjenvey small updates, mostly from the latest template. fix a typo
pjenvey authored
323 # CUSTOM MIDDLEWARE HERE (filtered by error handling middlewares)
324
aabcb3c @bbangert Adding concepts section, moving explanation of middleware to it
bbangert authored
325 if asbool(full_stack):
326 # Handle Python exceptions
327 app = ErrorHandler(app, global_conf, **config['pylons.errorware'])
328
329 # Display error documents for 401, 403, 404 status codes (and
330 # 500 when debug is disabled)
331 if asbool(config['debug']):
332 app = StatusCodeRedirect(app)
333 else:
334 app = StatusCodeRedirect(app, [400, 401, 403, 404, 500])
335
336 # Establish the Registry for this application
337 app = RegistryManager(app)
338
ebc508f @pjenvey small updates, mostly from the latest template. fix a typo
pjenvey authored
339 if asbool(static_files):
340 # Serve static files
341 static_app = StaticURLParser(config['pylons.paths']['static_files'])
342 app = Cascade([static_app, app])
343
aabcb3c @bbangert Adding concepts section, moving explanation of middleware to it
bbangert authored
344 return app
b6d3a6e Added the onion
kelvin@Trinity.local authored
345
aabcb3c @bbangert Adding concepts section, moving explanation of middleware to it
bbangert authored
346 Since each piece of middleware wraps the one before it, the stack needs to be
347 assembled in reverse order from the order in which its called. That is, the
348 very last middleware that wraps the WSGI Application, is the very first that
349 will be called by the server.
350
351 The last piece of middleware in the stack, called Cascade, is used to
ebc508f @pjenvey small updates, mostly from the latest template. fix a typo
pjenvey authored
352 serve static content files during development. For top performance,
353 consider disabling the Cascade middleware via setting the
354 ``static_files = false`` in the configuration file. Then have the
355 webserver or a :term:`CDN` serve static files.
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
356
357 .. warning::
358
359 When unsure about whether or not to change the middleware, **don't**. The
360 order of the middleware is important to the proper functioning of a
361 Pylons application, and shouldn't be altered unless needed.
b6d3a6e Added the onion
kelvin@Trinity.local authored
362
363 Adding custom middleware
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
364 ========================
b6d3a6e Added the onion
kelvin@Trinity.local authored
365
366 Custom middleware should be included in the :file:`config/middleware.py` at
367 comment marker::
368
369 # CUSTOM MIDDLEWARE HERE (filtered by error handling middlewares)
370
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
371 For example, to add a middleware component named `MyMiddleware`,
372 include it in :file:`config/middleware.py`::
b6d3a6e Added the onion
kelvin@Trinity.local authored
373
374 # The Pylons WSGI app
375 app = PylonsApp()
376
377 # Routing/Session/Cache Middleware
378 app = RoutesMiddleware(app, config['routes.map'])
379 app = SessionMiddleware(app, config)
380 app = CacheMiddleware(app, config)
381
ebc508f @pjenvey small updates, mostly from the latest template. fix a typo
pjenvey authored
382 # CUSTOM MIDDLEWARE HERE (filtered by error handling middlewares)
383 app = MyMiddleware(app)
384
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
385 The app object is simply passed as a parameter to the `MyMiddleware` middleware which in turn should return a wrapped WSGI application.
b6d3a6e Added the onion
kelvin@Trinity.local authored
386
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
387 Care should be taken when deciding in which layer to place custom
ebc508f @pjenvey small updates, mostly from the latest template. fix a typo
pjenvey authored
388 middleware. In most cases middleware should be placed before the Pylons WSGI
389 application and its supporting Routes/Session/Cache middlewares, however if the
390 middleware should run *after* the CacheMiddleware::
b6d3a6e Added the onion
kelvin@Trinity.local authored
391
392 # Routing/Session/Cache Middleware
393 app = RoutesMiddleware(app, config['routes.map'])
394 app = SessionMiddleware(app, config)
395
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
396 # MyMiddleware can only see the cache object, nothing *above* here
b6d3a6e Added the onion
kelvin@Trinity.local authored
397 app = MyMiddleware(app)
398
399 app = CacheMiddleware(app, config)
400
401 What is full_stack?
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
402 ===================
b6d3a6e Added the onion
kelvin@Trinity.local authored
403
404 In the Pylons ini file {:file:`development.ini` or :file:`production.ini`} this block determines if the flag full_stack is set to true or false::
405
406 [app:main]
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
407 use = egg:app_name
b6d3a6e Added the onion
kelvin@Trinity.local authored
408 full_stack = true
409
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
410 The full_stack flag determines if the ErrorHandler and StatusCodeRedirect is included as a layer in the middleware wrapping process. The only condition in which this option would be set to `false` is if multiple Pylons applications are running and will be wrapped in the appropriate middleware elsewhere.
137b769 @bbangert Doc updates
bbangert authored
411
412
413 .. _setup-config:
414
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
415 *****************
c85feb4 @bbangert More doc updates
bbangert authored
416 Application Setup
a8ed067 @bbangert Massive re-working of docs to finish up getting started and most of c…
bbangert authored
417 *****************
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
418
2b1c94a @bbangert Finished configuration section
bbangert authored
419 There are two kinds of 'Application Setup' that are occasionally referenced
420 with regards to a project using Pylons.
421
422 * Setting up a new application
423 * Configuring project information and package dependencies
424
425 Setting Up a New Application
426 ============================
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
427
2b1c94a @bbangert Finished configuration section
bbangert authored
428 To make it easier to setup a new instance of a project, such as setting up
429 the basic database schema, populating necessary defaults, etc. a setup
430 script can be created.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python d…
gjhiggins authored
431
2b1c94a @bbangert Finished configuration section
bbangert authored
432 In a Pylons project, the setup script to be run is located in the projects'
433 :file:`websetup.py` file. The default script loads the projects configuration
434 to make it easier to write application setup steps:
435
436 .. code-block :: python
437
438 import logging
439
440 from helloworld.config.environment import load_environment
441
442 log = logging.getLogger(__name__)
443
444 def setup_app(command, conf, vars):
445 """Place any commands to setup helloworld here"""
446 load_environment(conf.global_conf, conf.local_conf)
447
448 .. note::
449 If the project was configured during creation to use SQLAlchemy this file
450 will include some commands to setup the database connection to make it
451 easier to setup database tables.
452
453 To run the setup script using the development configuration:
454
455 .. code-block :: bash
456
457 $ paster setup-app development.ini
458
459 Configuring the Package
460 =======================
461
462 A newly created project with Pylons is a standard Python package. As a Python
463 package, it has a :file:`setup.py` file that records meta-information about
464 the package. Most of the options in it are fairly self-explanatory, the most
465 important being the 'install_requires' option:
466
467 .. code-block :: python
468
469 install_requires=[
470 "Pylons>=0.9.7",
471 ],
472
473 These lines indicate what packages are required for the proper functioning
474 of the application, and should be updated as needed. To re-parse the
475 :file:`setup.py` line for new dependencies:
476
477 .. code-block :: bash
478
479 $ python setup.py develop
480
481 In addition to updating the packages as needed so that the dependency
482 requirements are made, this command will ensure that this package is active
483 in the system (without requiring the traditional
484 :command:`python setup.py install`).
485
486 .. seealso::
5c328c2 @pjenvey h.url_for -> url_for
pjenvey authored
487 `Declaring Dependencies <http://peak.telecommunity.com/DevCenter/setuptools#declaring-dependencies>`_
Something went wrong with that request. Please try again.