Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 600 lines (452 sloc) 21.449 kB
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
1 .. _command_line_chapter:
2
3 Command-Line Pyramid
4 ====================
5
6 Your :app:`Pyramid` application can be controlled and inspected using a
7 variety of command-line utilities. These utilities are documented in this
8 chapter.
9
10 .. index::
11 pair: matching views; printing
12 single: paster pviews
13
14 .. _displaying_matching_views:
15
16 Displaying Matching Views for a Given URL
17 -----------------------------------------
18
19 For a big application with several views, it can be hard to keep the view
20 configuration details in your head, even if you defined all the views
21 yourself. You can use the ``paster pviews`` command in a terminal window to
22 print a summary of matching routes and views for a given URL in your
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
23 application. The ``paster pviews`` command accepts two arguments. The first
24 argument to ``pviews`` is the path to your application's ``.ini`` file and
25 section name inside the ``.ini`` file which points to your application. This
26 should be of the format ``config_file#section_name``. The second argument is
27 the URL to test for matching views. The ``section_name`` may be omitted; if
28 it is, it's considered to be ``main``.
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
29
30 Here is an example for a simple view configuration using :term:`traversal`:
31
32 .. code-block:: text
33 :linenos:
34
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
35 $ ../bin/paster pviews development.ini#tutorial /FrontPage
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
36
37 URL = /FrontPage
38
39 context: <tutorial.models.Page object at 0xa12536c>
40 view name:
41
42 View:
43 -----
44 tutorial.views.view_page
45 required permission = view
46
47 The output always has the requested URL at the top and below that all the
48 views that matched with their view configuration details. In this example
49 only one view matches, so there is just a single *View* section. For each
50 matching view, the full code path to the associated view callable is shown,
51 along with any permissions and predicates that are part of that view
52 configuration.
53
54 A more complex configuration might generate something like this:
55
56 .. code-block:: text
57 :linenos:
58
59 $ ../bin/paster pviews development.ini#shootout /about
60
61 URL = /about
62
63 context: <shootout.models.RootFactory object at 0xa56668c>
64 view name: about
65
66 Route:
67 ------
68 route name: about
69 route pattern: /about
70 route path: /about
71 subpath:
72 route predicates (request method = GET)
73
74 View:
75 -----
76 shootout.views.about_view
77 required permission = view
78 view predicates (request_param testing, header X/header)
79
80 Route:
81 ------
82 route name: about_post
83 route pattern: /about
84 route path: /about
85 subpath:
86 route predicates (request method = POST)
87
88 View:
89 -----
90 shootout.views.about_view_post
91 required permission = view
92 view predicates (request_param test)
93
94 View:
95 -----
96 shootout.views.about_view_post2
97 required permission = view
98 view predicates (request_param test2)
99
100 In this case, we are dealing with a :term:`URL dispatch` application. This
101 specific URL has two matching routes. The matching route information is
102 displayed first, followed by any views that are associated with that route.
103 As you can see from the second matching route output, a route can be
104 associated with more than one view.
105
106 For a URL that doesn't match any views, ``paster pviews`` will simply print
107 out a *Not found* message.
108
109
110 .. index::
111 single: interactive shell
112 single: IPython
c28a03e @jpcw add bpython support to pshell
jpcw authored
113 single: bpython
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
114 single: paster pshell
115 single: pshell
116
117 .. _interactive_shell:
118
119 The Interactive Shell
120 ---------------------
121
122 Once you've installed your program for development using ``setup.py
123 develop``, you can use an interactive Python shell to execute expressions in
124 a Python environment exactly like the one that will be used when your
125 application runs "for real". To do so, use the ``paster pshell`` command.
126
127 The argument to ``pshell`` follows the format ``config_file#section_name``
128 where ``config_file`` is the path to your application's ``.ini`` file and
129 ``section_name`` is the ``app`` section name inside the ``.ini`` file which
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
130 points to your application. For example, if your application ``.ini`` file
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
131 might have a ``[app:main]`` section that looks like so:
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
132
133 .. code-block:: ini
134 :linenos:
135
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
136 [app:main]
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
137 use = egg:MyProject
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
138 pyramid.reload_templates = true
139 pyramid.debug_authorization = false
140 pyramid.debug_notfound = false
141 pyramid.debug_templates = true
142 pyramid.default_locale_name = en
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
143
144 If so, you can use the following command to invoke a debug shell using the
145 name ``MyProject`` as a section name:
146
147 .. code-block:: text
148
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
149 chrism@thinko env26]$ bin/paster pshell starter/development.ini#MyProject
150 Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32)
151 [GCC 4.4.3] on linux2
152 Type "help" for more information.
153
154 Environment:
155 app The WSGI application.
156 registry Active Pyramid registry.
157 request Active request object.
158 root Root of the default resource tree.
159 root_factory Default root factory used to create `root`.
33a3ead @mmerickel Added some docs for the new 'setup' option key in [pshell].
mmerickel authored
160
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
161 >>> root
162 <myproject.resources.MyResource object at 0x445270>
163 >>> registry
164 <Registry myproject>
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
165 >>> registry.settings['pyramid.debug_notfound']
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
166 False
167 >>> from myproject.views import my_view
168 >>> from pyramid.request import Request
169 >>> r = Request.blank('/')
170 >>> my_view(r)
171 {'project': 'myproject'}
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
172
173 The WSGI application that is loaded will be available in the shell as the
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
174 ``app`` global. Also, if the application that is loaded is the :app:`Pyramid`
175 app with no surrounding middleware, the ``root`` object returned by the
176 default :term:`root factory`, ``registry``, and ``request`` will be
177 available.
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
178
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
179 You can also simply rely on the ``main`` default section name by omitting any
180 hash after the filename:
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
181
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
182 .. code-block:: text
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
183
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
184 chrism@thinko env26]$ bin/paster pshell starter/development.ini
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
185
186 Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).
187
6ce1e0c @mcdonc add more index markers
mcdonc authored
188 .. index::
189 pair: pshell; extending
190
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
191 .. _extending_pshell:
192
193 Extending the Shell
194 ~~~~~~~~~~~~~~~~~~~
195
33a3ead @mmerickel Added some docs for the new 'setup' option key in [pshell].
mmerickel authored
196 It is convenient when using the interactive shell often to have some
197 variables significant to your application already loaded as globals when
5adf4c0 @mcdonc add description of keys and values
mcdonc authored
198 you start the ``pshell``. To facilitate this, ``pshell`` will look for a
199 special ``[pshell]`` section in your INI file and expose the subsequent
200 key/value pairs to the shell. Each key is a variable name that will be
201 global within the pshell session; each value is a :term:`dotted Python name`.
33a3ead @mmerickel Added some docs for the new 'setup' option key in [pshell].
mmerickel authored
202 If specified, the special key ``setup`` should be a :term:`dotted Python name`
203 pointing to a callable that accepts the dictionary of globals that will
204 be loaded into the shell. This allows for some custom initializing code
205 to be executed each time the ``pshell`` is run. The ``setup`` callable
206 can also be specified from the commandline using the ``--setup`` option
207 which will override the key in the INI file.
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
208
209 For example, you want to expose your model to the shell, along with the
210 database session so that you can mutate the model on an actual database.
211 Here, we'll assume your model is stored in the ``myapp.models`` package.
212
213 .. code-block:: ini
214 :linenos:
215
216 [pshell]
33a3ead @mmerickel Added some docs for the new 'setup' option key in [pshell].
mmerickel authored
217 setup = myapp.lib.pshell.setup
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
218 m = myapp.models
219 session = myapp.models.DBSession
220 t = transaction
221
33a3ead @mmerickel Added some docs for the new 'setup' option key in [pshell].
mmerickel authored
222 By defining the ``setup`` callable, we will create the module
223 ``myapp.lib.pshell`` containing a callable named ``setup`` that will receive
224 the global environment before it is exposed to the shell. Here we mutate the
225 environment's request as well as add a new value containing a WebTest version
226 of the application to which we can easily submit requests.
227
228 .. code-block:: python
229 :linenos:
230
231 # myapp/lib/pshell.py
232 from webtest import TestApp
233
234 def setup(env):
235 env['request'].host = 'www.example.com'
236 env['request'].scheme = 'https'
237 env['testapp'] = TestApp(env['app'])
238
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
239 When this INI file is loaded, the extra variables ``m``, ``session`` and
33a3ead @mmerickel Added some docs for the new 'setup' option key in [pshell].
mmerickel authored
240 ``t`` will be available for use immediately. Since a ``setup`` callable
241 was also specified, it is executed and a new variable ``testapp`` is
242 exposed, and the request is configured to generate urls from the host
243 ``http://www.example.com``. For example:
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
244
245 .. code-block:: text
246
247 chrism@thinko env26]$ bin/paster pshell starter/development.ini
248 Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32)
249 [GCC 4.4.3] on linux2
250 Type "help" for more information.
251
252 Environment:
253 app The WSGI application.
254 registry Active Pyramid registry.
255 request Active request object.
256 root Root of the default resource tree.
257 root_factory Default root factory used to create `root`.
33a3ead @mmerickel Added some docs for the new 'setup' option key in [pshell].
mmerickel authored
258 testapp <webtest.TestApp object at ...>
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
259
260 Custom Variables:
261 m myapp.models
262 session myapp.models.DBSession
263 t transaction
33a3ead @mmerickel Added some docs for the new 'setup' option key in [pshell].
mmerickel authored
264
265 >>> testapp.get('/')
266 <200 OK text/html body='<!DOCTYPE...l>\n'/3337>
267 >>> request.route_url('home')
268 'https://www.example.com/'
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
269
6ce1e0c @mcdonc add more index markers
mcdonc authored
270 .. index::
271 single: IPython
02b6046 @jpcw add bpython support to pshell with raydeo remarks and design
jpcw authored
272 single: bpython
6ce1e0c @mcdonc add more index markers
mcdonc authored
273
02b6046 @jpcw add bpython support to pshell with raydeo remarks and design
jpcw authored
274 IPython or bpython
275 ~~~~~~~~~~~~~~~~~~
c28a03e @jpcw add bpython support to pshell
jpcw authored
276
02b6046 @jpcw add bpython support to pshell with raydeo remarks and design
jpcw authored
277 If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_ or
278 `bpython <http://bpython-interpreter.org/>`_ or both installed in
279 the interpreter you use to invoke the ``pshell`` command, ``pshell`` will
280 autodiscover them and use the first respectively found in this order :
281 IPython, bpython, standard Python interpreter. However you could
282 specifically invoke one of your choice with the ``-p choice`` or
283 ``--python-shell choice`` option.
c28a03e @jpcw add bpython support to pshell
jpcw authored
284
285 .. code-block:: text
286
02b6046 @jpcw add bpython support to pshell with raydeo remarks and design
jpcw authored
287 [chrism@vitaminf shellenv]$ ../bin/pshell -p ipython | bpython | python \
c28a03e @jpcw add bpython support to pshell
jpcw authored
288 development.ini#MyProject
289
290
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
291 .. index::
292 pair: routes; printing
293 single: paster proutes
294 single: proutes
295
296 .. _displaying_application_routes:
297
298 Displaying All Application Routes
299 ---------------------------------
300
301 You can use the ``paster proutes`` command in a terminal window to print a
302 summary of routes related to your application. Much like the ``paster
303 pshell`` command (see :ref:`interactive_shell`), the ``paster proutes``
304 command accepts one argument with the format ``config_file#section_name``.
af05604 @mcdonc - Change paster pviews and paster proutes to use bootstrap.
mcdonc authored
305 The ``config_file`` is the path to your application's ``.ini`` file, and
306 ``section_name`` is the ``app`` section name inside the ``.ini`` file which
307 points to your application. By default, the ``section_name`` is ``main`` and
308 can be omitted.
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
309
310 For example:
311
312 .. code-block:: text
313 :linenos:
314
315 [chrism@thinko MyProject]$ ../bin/paster proutes development.ini#MyProject
316 Name Pattern View
317 ---- ------- ----
318 home / <function my_view>
319 home2 / <function my_view>
320 another /another None
321 static/ static/*subpath <static_view object>
322 catchall /*subpath <function static_view>
323
324 ``paster proutes`` generates a table. The table has three columns: a Name
9343b6f @cguardia eliminated repeated word
cguardia authored
325 column, a Pattern column, and a View column. The items listed in the
f7afa75 @cguardia corrected typo
cguardia authored
326 Name column are route names, the items listed in the Pattern column are route
ae4c577 @mcdonc move all paster commands to a separate chapter
mcdonc authored
327 patterns, and the items listed in the View column are representations of the
328 view callable that will be invoked when a request matches the associated
329 route pattern. The view column may show ``None`` if no associated view
330 callable could be found. If no routes are configured within your
331 application, nothing will be printed to the console when ``paster proutes``
332 is executed.
333
6ce1e0c @mcdonc add more index markers
mcdonc authored
334 .. index::
1311321 @mcdonc add tweens module, add docs for ptweens and tweens to hooks
mcdonc authored
335 pair: tweens; printing
336 single: paster ptweens
337 single: ptweens
338
339 .. _displaying_tweens:
340
341 Displaying "Tweens"
342 -------------------
343
05f610e @mcdonc document under and over params
mcdonc authored
344 A :term:`tween` is a bit of code that sits between the main Pyramid
345 application request handler and the WSGI application which calls it. A user
346 can get a representation of both the implicit tween ordering (the ordering
347 specified by calls to :meth:`pyramid.config.Configurator.add_tween`) and the
348 explicit tween ordering (specified by the ``pyramid.tweens`` configuration
157c290 @mcdonc disallow adding a tween factory which is an instance without passing …
mcdonc authored
349 setting) orderings using the ``paster ptweens`` command. Tween factories
350 will show up represented by their standard Python dotted name in the
351 ``paster ptweens`` output.
1311321 @mcdonc add tweens module, add docs for ptweens and tweens to hooks
mcdonc authored
352
353 For example, here's the ``paster pwteens`` command run against a system
354 configured without any explicit tweens:
355
356 .. code-block:: text
357 :linenos:
358
05f610e @mcdonc document under and over params
mcdonc authored
359 [chrism@thinko pyramid]$ paster ptweens development.ini
1311321 @mcdonc add tweens module, add docs for ptweens and tweens to hooks
mcdonc authored
360 "pyramid.tweens" config value NOT set (implicitly ordered tweens used)
361
05f610e @mcdonc document under and over params
mcdonc authored
362 Implicit Tween Chain
363
364 Position Name Alias
365 -------- ---- -----
366 - - INGRESS
367 0 pyramid_debugtoolbar.toolbar.toolbar_tween_factory pdbt
368 1 pyramid.tweens.excview_tween_factory excview
369 - - MAIN
1311321 @mcdonc add tweens module, add docs for ptweens and tweens to hooks
mcdonc authored
370
371 Here's the ``paster pwteens`` command run against a system configured *with*
372 explicit tweens defined in its ``development.ini`` file:
373
374 .. code-block:: text
375 :linenos:
376
05f610e @mcdonc document under and over params
mcdonc authored
377 [chrism@thinko pyramid]$ paster ptweens development.ini
1311321 @mcdonc add tweens module, add docs for ptweens and tweens to hooks
mcdonc authored
378 "pyramid.tweens" config value set (explicitly ordered tweens used)
379
380 Explicit Tween Chain (used)
381
05f610e @mcdonc document under and over params
mcdonc authored
382 Position Name
383 -------- ----
384 - INGRESS
385 0 starter.tween_factory2
386 1 starter.tween_factory1
387 2 pyramid.tweens.excview_tween_factory
388 - MAIN
1311321 @mcdonc add tweens module, add docs for ptweens and tweens to hooks
mcdonc authored
389
390 Implicit Tween Chain (not used)
391
05f610e @mcdonc document under and over params
mcdonc authored
392 Position Name Alias
393 -------- ---- -----
394 - - INGRESS
395 0 pyramid_debugtoolbar.toolbar.toolbar_tween_factory pdbt
396 1 pyramid.tweens.excview_tween_factory excview
397 - - MAIN
1311321 @mcdonc add tweens module, add docs for ptweens and tweens to hooks
mcdonc authored
398
399 Here's the application configuration section of the ``development.ini`` used
400 by the above ``paster ptweens`` command which reprorts that the explicit
401 tween chain is used:
402
403 .. code-block:: text
404 :linenos:
405
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
406 [app:main]
1311321 @mcdonc add tweens module, add docs for ptweens and tweens to hooks
mcdonc authored
407 use = egg:starter
05f610e @mcdonc document under and over params
mcdonc authored
408 reload_templates = true
409 debug_authorization = false
410 debug_notfound = false
411 debug_routematch = false
412 debug_templates = true
413 default_locale_name = en
414 pyramid.include = pyramid_debugtoolbar
415 pyramid.tweens = starter.tween_factory2
1311321 @mcdonc add tweens module, add docs for ptweens and tweens to hooks
mcdonc authored
416 starter.tween_factory1
05f610e @mcdonc document under and over params
mcdonc authored
417 pyramid.tweens.excview_tween_factory
418
419 See :ref:`registering_tweens` for more information about tweens.
6ce1e0c @mcdonc add more index markers
mcdonc authored
420
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
421 .. _writing_a_script:
422
423 Writing a Script
424 ----------------
425
426 All web applications are, at their hearts, systems which accept a request and
427 return a response. When a request is accepted by a :app:`Pyramid`
428 application, the system receives state from the request which is later relied
42eaadb @mmerickel garden
mmerickel authored
429 on by your application code. For example, one :term:`view callable` may assume
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
430 it's working against a request that has a ``request.matchdict`` of a
431 particular composition, while another assumes a different composition of the
432 matchdict.
433
434 In the meantime, it's convenient to be able to write a Python script that can
435 work "in a Pyramid environment", for instance to update database tables used
436 by your :app:`Pyramid` application. But a "real" Pyramid environment doesn't
437 have a completely static state independent of a request; your application
438 (and Pyramid itself) is almost always reliant on being able to obtain
439 information from a request. When you run a Python script that simply imports
440 code from your application and tries to run it, there just is no request
441 data, because there isn't any real web request. Therefore some parts of your
442 application and some Pyramid APIs will not work.
443
444 For this reason, :app:`Pyramid` makes it possible to run a script in an
445 environment much like the environment produced when a particular
446 :term:`request` reaches your :app:`Pyramid` application. This is achieved by
447 using the :func:`pyramid.paster.bootstrap` command in the body of your
448 script.
449
12382c2 @mcdonc note version reqt; fix dangling ref
mcdonc authored
450 .. note:: This feature is new as of :app:`Pyramid` 1.1.
451
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
452 In the simplest case, :func:`pyramid.paster.bootstrap` can be used with a
453 single argument, which accepts the :term:`PasteDeploy` ``.ini`` file
454 representing Pyramid your application configuration as a single argument:
455
456 .. code-block:: python
457
458 from pyramid.paster import bootstrap
795ddb4 @mmerickel Renamed the 'info' dict to 'env' in scripting.
mmerickel authored
459 env = bootstrap('/path/to/my/development.ini')
460 print env['request'].route_url('home')
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
461
462 :func:`pyramid.paster.bootstrap` returns a dictionary containing
463 framework-related information. This dictionary will always contain a
464 :term:`request` object as its ``request`` key.
465
795ddb4 @mmerickel Renamed the 'info' dict to 'env' in scripting.
mmerickel authored
466 The following keys are available in the ``env`` dictionary returned by
795aec4 @cguardia typo in func name
cguardia authored
467 :func:`pyramid.paster.bootstrap`:
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
468
469 request
470
471 A :class:`pyramid.request.Request` object implying the current request
472 state for your script.
473
474 app
475
476 The :term:`WSGI` application object generated by bootstrapping.
477
478 root
479
480 The :term:`resource` root of your :app:`Pyramid` application. This is an
481 object generated by the :term:`root factory` configured in your
482 application.
483
484 registry
485
486 The :term:`application registry` of your :app:`Pyramid` application.
487
488 closer
489
490 A parameterless callable that can be used to pop an internal
491 :app:`Pyramid` threadlocal stack (used by
492 :func:`pyramid.threadlocal.get_current_registry` and
493 :func:`pyramid.threadlocal.get_current_request`) when your scripting job
494 is finished.
495
496 Let's assume that the ``/path/to/my/development.ini`` file used in the
497 example above looks like so:
498
499 .. code-block:: ini
500
501 [pipeline:main]
391402e @mcdonc - Projects created via a scaffold no longer depend on the ``WebError``
mcdonc authored
502 pipeline = translogger
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
503 another
504
391402e @mcdonc - Projects created via a scaffold no longer depend on the ``WebError``
mcdonc authored
505 [filter:translogger]
506 filter_app_factory = egg:Paste#translogger
507 setup_console_handler = False
508 logger_name = wsgi
509
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
510 [app:another]
511 use = egg:MyProject
512
513 The configuration loaded by the above bootstrap example will use the
514 configuration implied by the ``[pipeline:main]`` section of your
515 configuration file by default. Specifying ``/path/to/my/development.ini`` is
516 logically equivalent to specifying ``/path/to/my/development.ini#main``. In
517 this case, we'll be using a configuration that includes an ``app`` object
391402e @mcdonc - Projects created via a scaffold no longer depend on the ``WebError``
mcdonc authored
518 which is wrapped in the Paste "translogger" middleware (which logs requests
519 to the console).
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
520
521 You can also specify a particular *section* of the PasteDeploy ``.ini`` file
12382c2 @mcdonc note version reqt; fix dangling ref
mcdonc authored
522 to load instead of ``main``:
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
523
524 .. code-block:: python
525
526 from pyramid.paster import bootstrap
795ddb4 @mmerickel Renamed the 'info' dict to 'env' in scripting.
mmerickel authored
527 env = bootstrap('/path/to/my/development.ini#another')
528 print env['request'].route_url('home')
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
529
530 The above example specifies the ``another`` ``app``, ``pipeline``, or
69452f6 @mmerickel Changed the URL generation example to be more practical.
mmerickel authored
531 ``composite`` section of your PasteDeploy configuration file. The ``app``
532 object present in the ``env`` dictionary returned by
533 :func:`pyramid.paster.bootstrap` will be a :app:`Pyramid` :term:`router`.
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
534
69452f6 @mmerickel Changed the URL generation example to be more practical.
mmerickel authored
535 Changing the Request
536 ~~~~~~~~~~~~~~~~~~~~
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
537
69452f6 @mmerickel Changed the URL generation example to be more practical.
mmerickel authored
538 By default, Pyramid will generate a request object in the ``env`` dictionary
539 for the URL ``http://localhost:80/``. This means that any URLs generated
540 by Pyramid during the execution of your script will be anchored here. This
541 is generally not what you want.
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
542
69452f6 @mmerickel Changed the URL generation example to be more practical.
mmerickel authored
543 So how do we make Pyramid generate the correct URLs?
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
544
69452f6 @mmerickel Changed the URL generation example to be more practical.
mmerickel authored
545 Assuming that you have a route configured in your application like so:
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
546
69452f6 @mmerickel Changed the URL generation example to be more practical.
mmerickel authored
547 .. code-block:: python
548
549 config.add_route('verify', '/verify/{code}')
550
551 You need to inform the Pyramid environment that the WSGI application is
552 handling requests from a certain base. For example, we want to mount our
553 application at `example.com/prefix` and the generated URLs should use HTTPS.
554 This can be done by mutating the request object:
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
555
556 .. code-block:: python
557
558 from pyramid.paster import bootstrap
69452f6 @mmerickel Changed the URL generation example to be more practical.
mmerickel authored
559 env = bootstrap('/path/to/my/development.ini#another')
560 env['request'].host = 'example.com'
561 env['request'].scheme = 'https'
562 env['request'].script_name = '/prefix'
563 print env['request'].application_url
564 # will print 'https://example.com/prefix/another/url'
565
566 Now you can readily use Pyramid's APIs for generating URLs:
567
568 .. code-block:: python
569
fb90f01 @mcdonc - The ``route_url``, ``route_path``, ``resource_url``, ``static_url``…
mcdonc authored
570 env['request'].route_url('verify', code='1337')
69452f6 @mmerickel Changed the URL generation example to be more practical.
mmerickel authored
571 # will return 'https://example.com/prefix/verify/1337'
572
573 Cleanup
574 ~~~~~~~
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
575
576 When your scripting logic finishes, it's good manners (but not required) to
577 call the ``closer`` callback:
578
579 .. code-block:: python
580
581 from pyramid.paster import bootstrap
795ddb4 @mmerickel Renamed the 'info' dict to 'env' in scripting.
mmerickel authored
582 env = bootstrap('/path/to/my/development.ini')
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
583
584 # .. do stuff ...
585
795ddb4 @mmerickel Renamed the 'info' dict to 'env' in scripting.
mmerickel authored
586 env['closer']()
5fb458c @mcdonc - Added a section entitled "Writing a Script" to the "Command-Line Py…
mcdonc authored
587
7141f0d @mcdonc mention manual logging config
mcdonc authored
588 Setting Up Logging
589 ~~~~~~~~~~~~~~~~~~
590
591 By default, :func:`pyramid.paster.bootstrap` does not configure logging
592 parameters present in the configuration file. If you'd like to configure
593 logging based on ``[logger]`` and related sections in the configuration file,
594 use the following command:
595
596 .. code-block:: python
597
6e3025d @mcdonc wrong path for logging.config
mcdonc authored
598 import logging.config
599 logging.config.fileConfig('/path/to/my/development.ini')
Something went wrong with that request. Please try again.