| commit | author | age | ||
| b731b5 | 1 | .. _qtut_debugtoolbar: |
| PE | 2 | |
| b1b922 | 3 | ============================================ |
| PE | 4 | 04: Easier Development with ``debugtoolbar`` |
| 5 | ============================================ | |
| 6 | ||
| ba7880 | 7 | Error handling and introspection using the ``pyramid_debugtoolbar`` add-on. |
| b1b922 | 8 | |
| 823ef1 | 9 | |
| b1b922 | 10 | Background |
| PE | 11 | ========== |
| 12 | ||
| 823ef1 | 13 | As we introduce the basics, we also want to show how to be productive in |
| SP | 14 | development and debugging. For example, we just discussed template reloading, |
| 15 | and earlier we showed ``--reload`` for application reloading. | |
| b1b922 | 16 | |
| 823ef1 | 17 | ``pyramid_debugtoolbar`` is a popular Pyramid add-on which makes several tools |
| SP | 18 | available in your browser. Adding it to your project illustrates several points |
| 19 | about configuration. | |
| 20 | ||
| b1b922 | 21 | |
| PE | 22 | Objectives |
| 23 | ========== | |
| 24 | ||
| 823ef1 | 25 | - Install and enable the toolbar to help during development. |
| b1b922 | 26 | |
| 823ef1 | 27 | - Explain Pyramid add-ons. |
| b1b922 | 28 | |
| 823ef1 | 29 | - Show how an add-on gets configured into your application. |
| SP | 30 | |
| b1b922 | 31 | |
| PE | 32 | Steps |
| 33 | ===== | |
| 34 | ||
| 823ef1 | 35 | #. First we copy the results of the previous step, as well as install the |
| SP | 36 | ``pyramid_debugtoolbar`` package: |
| b1b922 | 37 | |
| PE | 38 | .. code-block:: bash |
| 39 | ||
| 187104 | 40 | $ cd ..; cp -r ini debugtoolbar; cd debugtoolbar |
| ba7880 | 41 | $ $VENV/bin/pip install -e . |
| SP | 42 | $ $VENV/bin/pip install pyramid_debugtoolbar |
| b1b922 | 43 | |
| PE | 44 | #. Our ``debugtoolbar/development.ini`` gets a configuration entry for |
| 45 | ``pyramid.includes``: | |
| 46 | ||
| 47 | .. literalinclude:: debugtoolbar/development.ini | |
| 48 | :language: ini | |
| 49 | :linenos: | |
| 50 | ||
| 51 | #. Run the WSGI application with: | |
| 52 | ||
| 53 | .. code-block:: bash | |
| 54 | ||
| 187104 | 55 | $ $VENV/bin/pserve development.ini --reload |
| b1b922 | 56 | |
| d749bf | 57 | #. Open http://localhost:6543/ in your browser. See the handy |
| b1b922 | 58 | toolbar on the right. |
| PE | 59 | |
| 823ef1 | 60 | |
| b1b922 | 61 | Analysis |
| PE | 62 | ======== |
| 63 | ||
| 903f48 | 64 | ``pyramid_debugtoolbar`` is a full-fledged Python package, available on PyPI |
| SP | 65 | just like thousands of other Python packages. Thus we start by installing the |
| 66 | ``pyramid_debugtoolbar`` package into our virtual environment using normal | |
| 67 | Python package installation commands. | |
| b1b922 | 68 | |
| 903f48 | 69 | The ``pyramid_debugtoolbar`` Python package is also a Pyramid add-on, which |
| SP | 70 | means we need to include its add-on configuration into our web application. We |
| 71 | could do this with imperative configuration in ``tutorial/__init__.py`` by | |
| 72 | using ``config.include``. Pyramid also supports wiring in add-on configuration | |
| 823ef1 | 73 | via our ``development.ini`` using ``pyramid.includes``. We use this to load the |
| SP | 74 | configuration for the debugtoolbar. |
| b1b922 | 75 | |
| 903f48 | 76 | You'll now see an attractive button on the right side of your browser, which |
| 823ef1 | 77 | you may click to provide introspective access to debugging information in a new |
| 8c1b6a | 78 | browser tab. Even better, if your web application generates an error, you will |
| 823ef1 | 79 | see a nice traceback on the screen. When you want to disable this toolbar, |
| SP | 80 | there's no need to change code: you can remove it from ``pyramid.includes`` in |
| 81 | the relevant ``.ini`` configuration file (thus showing why configuration files | |
| 82 | are handy). | |
| b1b922 | 83 | |
| ab06fa | 84 | Note that the toolbar injects a small amount of HTML/CSS into your app just |
| 903f48 | 85 | before the closing ``</body>`` tag in order to display itself. If you start to |
| SP | 86 | experience otherwise inexplicable client-side weirdness, you can shut it off |
| 87 | by commenting out the ``pyramid_debugtoolbar`` line in ``pyramid.includes`` | |
| 88 | temporarily. | |
| b1b922 | 89 | |
| 2033ee | 90 | .. seealso:: See also :ref:`pyramid_debugtoolbar <toolbar:overview>`. |
| ddcc03 | 91 | |
| 823ef1 | 92 | |
| 65687f | 93 | Extra credit |
| ddcc03 | 94 | ============ |
| TS | 95 | |
| ced8b4 | 96 | #. Why don't we add ``pyramid_debugtoolbar`` to the list of |
| SP | 97 | ``install_requires`` dependencies in ``debugtoolbar/setup.py``? |
| 76ff93 | 98 | |
| 823ef1 | 99 | #. Introduce a bug into your application. Change: |
| 76ff93 | 100 | |
| ced8b4 | 101 | .. code-block:: python |
| 76ff93 | 102 | |
| ced8b4 | 103 | def hello_world(request): |
| SP | 104 | return Response('<body><h1>Hello World!</h1></body>') |
| 76ff93 | 105 | |
| ced8b4 | 106 | to: |
| 76ff93 | 107 | |
| ced8b4 | 108 | .. code-block:: python |
| 76ff93 | 109 | |
| TS | 110 | def hello_world(request): |
| 111 | return xResponse('<body><h1>Hello World!</h1></body>') | |
| 112 | ||
| 823ef1 | 113 | Save, and visit http://localhost:6543/ again. Notice the nice traceback |
| SP | 114 | display. On the lowest line, click the "screen" icon to the right, and try |
| 115 | typing the variable names ``request`` and ``Response``. What else can you | |
| 116 | discover? | |
