diff options
| author | Christoph Zwerschke <cito@online.de> | 2016-04-19 20:07:12 +0200 |
|---|---|---|
| committer | Christoph Zwerschke <cito@online.de> | 2016-04-19 20:07:12 +0200 |
| commit | 3629c49e46207ff5162a82883c14937e6ef4c186 (patch) | |
| tree | 1306181202cb8313f16080789f5b9ab1eeb61d53 /docs/quick_tutorial/debugtoolbar.rst | |
| parent | 804ba0b2f434781e77d2b5191f1cd76a490f6610 (diff) | |
| parent | 6c16fb020027fac47e4d2e335cd9e264dba8aa3b (diff) | |
| download | pyramid-3629c49e46207ff5162a82883c14937e6ef4c186.tar.gz pyramid-3629c49e46207ff5162a82883c14937e6ef4c186.tar.bz2 pyramid-3629c49e46207ff5162a82883c14937e6ef4c186.zip | |
Merge remote-tracking branch 'refs/remotes/Pylons/master'
Diffstat (limited to 'docs/quick_tutorial/debugtoolbar.rst')
| -rw-r--r-- | docs/quick_tutorial/debugtoolbar.rst | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst new file mode 100644 index 000000000..aaf904390 --- /dev/null +++ b/docs/quick_tutorial/debugtoolbar.rst @@ -0,0 +1,116 @@ +.. _qtut_debugtoolbar: + +============================================ +04: Easier Development with ``debugtoolbar`` +============================================ + +Error handling and introspection using the ``pyramid_debugtoolbar`` add-on. + + +Background +========== + +As we introduce the basics, we also want to show how to be productive in +development and debugging. For example, we just discussed template reloading, +and earlier we showed ``--reload`` for application reloading. + +``pyramid_debugtoolbar`` is a popular Pyramid add-on which makes several tools +available in your browser. Adding it to your project illustrates several points +about configuration. + + +Objectives +========== + +- Install and enable the toolbar to help during development. + +- Explain Pyramid add-ons. + +- Show how an add-on gets configured into your application. + + +Steps +===== + +#. First we copy the results of the previous step, as well as install the + ``pyramid_debugtoolbar`` package: + + .. code-block:: bash + + $ cd ..; cp -r ini debugtoolbar; cd debugtoolbar + $ $VENV/bin/pip install -e . + $ $VENV/bin/pip install pyramid_debugtoolbar + +#. Our ``debugtoolbar/development.ini`` gets a configuration entry for + ``pyramid.includes``: + + .. literalinclude:: debugtoolbar/development.ini + :language: ini + :linenos: + +#. Run the WSGI application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ in your browser. See the handy + toolbar on the right. + + +Analysis +======== + +``pyramid_debugtoolbar`` is a full-fledged Python package, available on PyPI +just like thousands of other Python packages. Thus we start by installing the +``pyramid_debugtoolbar`` package into our virtual environment using normal +Python package installation commands. + +The ``pyramid_debugtoolbar`` Python package is also a Pyramid add-on, which +means we need to include its add-on configuration into our web application. We +could do this with imperative configuration in ``tutorial/__init__.py`` by +using ``config.include``. Pyramid also supports wiring in add-on configuration +via our ``development.ini`` using ``pyramid.includes``. We use this to load the +configuration for the debugtoolbar. + +You'll now see an attractive button on the right side of your browser, which +you may click to provide introspective access to debugging information in a new +rowser tab. Even better, if your web application generates an error, you will +see a nice traceback on the screen. When you want to disable this toolbar, +there's no need to change code: you can remove it from ``pyramid.includes`` in +the relevant ``.ini`` configuration file (thus showing why configuration files +are handy). + +Note that the toolbar injects a small amount of HTML/CSS into your app just +before the closing ``</body>`` tag in order to display itself. If you start to +experience otherwise inexplicable client-side weirdness, you can shut it off +by commenting out the ``pyramid_debugtoolbar`` line in ``pyramid.includes`` +temporarily. + +.. seealso:: See also :ref:`pyramid_debugtoolbar <toolbar:overview>`. + + +Extra Credit +============ + +#. Why don't we add ``pyramid_debugtoolbar`` to the list of + ``install_requires`` dependencies in ``debugtoolbar/setup.py``? + +#. Introduce a bug into your application. Change: + + .. code-block:: python + + def hello_world(request): + return Response('<body><h1>Hello World!</h1></body>') + + to: + + .. code-block:: python + + def hello_world(request): + return xResponse('<body><h1>Hello World!</h1></body>') + + Save, and visit http://localhost:6543/ again. Notice the nice traceback + display. On the lowest line, click the "screen" icon to the right, and try + typing the variable names ``request`` and ``Response``. What else can you + discover? |