| 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 | ||
| 89ea49 | 35 | #. First we copy the results of the previous step. |
| b1b922 | 36 | |
| 89ea49 | 37 | .. code-block:: bash |
| b1b922 | 38 | |
| 89ea49 | 39 | cd ..; cp -r ini debugtoolbar; cd debugtoolbar |
| b1b922 | 40 | |
| 62bb82 | 41 | #. Add ``pyramid_debugtoolbar`` to our project's dependencies in ``setup.py``: |
| b1b922 | 42 | |
| 89ea49 | 43 | .. literalinclude:: debugtoolbar/setup.py |
| SP | 44 | :language: python |
| 45 | :linenos: | |
| 0a7993 | 46 | :emphasize-lines: 7 |
| b1b922 | 47 | |
| 89ea49 | 48 | #. Install our project and its newly added dependency. |
| b1b922 | 49 | |
| 89ea49 | 50 | .. code-block:: bash |
| b1b922 | 51 | |
| 89ea49 | 52 | $VENV/bin/pip install -e . |
| b1b922 | 53 | |
| 89ea49 | 54 | #. Our ``debugtoolbar/development.ini`` gets a configuration entry for ``pyramid.includes``: |
| SP | 55 | |
| 56 | .. literalinclude:: debugtoolbar/development.ini | |
| 57 | :language: ini | |
| 58 | :linenos: | |
| 59 | ||
| 60 | #. Run the WSGI application with: | |
| 61 | ||
| 62 | .. code-block:: bash | |
| 63 | ||
| 64 | $VENV/bin/pserve development.ini --reload | |
| 65 | ||
| 66 | #. Open http://localhost:6543/ in your browser. | |
| 67 | See the handy toolbar on the right. | |
| b1b922 | 68 | |
| 823ef1 | 69 | |
| b1b922 | 70 | Analysis |
| PE | 71 | ======== |
| 72 | ||
| 903f48 | 73 | ``pyramid_debugtoolbar`` is a full-fledged Python package, available on PyPI |
| SP | 74 | just like thousands of other Python packages. Thus we start by installing the |
| 75 | ``pyramid_debugtoolbar`` package into our virtual environment using normal | |
| 76 | Python package installation commands. | |
| b1b922 | 77 | |
| 903f48 | 78 | The ``pyramid_debugtoolbar`` Python package is also a Pyramid add-on, which |
| SP | 79 | means we need to include its add-on configuration into our web application. We |
| 80 | could do this with imperative configuration in ``tutorial/__init__.py`` by | |
| 81 | using ``config.include``. Pyramid also supports wiring in add-on configuration | |
| 823ef1 | 82 | via our ``development.ini`` using ``pyramid.includes``. We use this to load the |
| SP | 83 | configuration for the debugtoolbar. |
| b1b922 | 84 | |
| 903f48 | 85 | You'll now see an attractive button on the right side of your browser, which |
| 823ef1 | 86 | you may click to provide introspective access to debugging information in a new |
| 66bb38 | 87 | browser tab. Even better, if your web application generates an error, you will |
| 823ef1 | 88 | see a nice traceback on the screen. When you want to disable this toolbar, |
| SP | 89 | there's no need to change code: you can remove it from ``pyramid.includes`` in |
| 90 | the relevant ``.ini`` configuration file (thus showing why configuration files | |
| 91 | are handy). | |
| b1b922 | 92 | |
| ab06fa | 93 | Note that the toolbar injects a small amount of HTML/CSS into your app just |
| 903f48 | 94 | before the closing ``</body>`` tag in order to display itself. If you start to |
| SP | 95 | experience otherwise inexplicable client-side weirdness, you can shut it off |
| 96 | by commenting out the ``pyramid_debugtoolbar`` line in ``pyramid.includes`` | |
| 97 | temporarily. | |
| b1b922 | 98 | |
| 2033ee | 99 | .. seealso:: See also :ref:`pyramid_debugtoolbar <toolbar:overview>`. |
| ddcc03 | 100 | |
| 823ef1 | 101 | |
| 65687f | 102 | Extra credit |
| ddcc03 | 103 | ============ |
| TS | 104 | |
| 23fbca | 105 | #. We added ``pyramid_debugtoolbar`` to the list of ``dev_requires`` dependencies in ``debugtoolbar/setup.py``. |
| SP | 106 | We then installed the dependencies via ``pip install -e ".[dev]"`` by virtue of the Setuptools ``extras_require`` value in the Python dictionary. |
| 107 | Why did we add them there instead of in the ``requires`` list? | |
| 76ff93 | 108 | |
| 89ea49 | 109 | #. Introduce a bug into your application. Change: |
| 76ff93 | 110 | |
| 89ea49 | 111 | .. code-block:: python |
| 76ff93 | 112 | |
| 89ea49 | 113 | def hello_world(request): |
| SP | 114 | return Response('<body><h1>Hello World!</h1></body>') |
| 76ff93 | 115 | |
| 89ea49 | 116 | to: |
| 76ff93 | 117 | |
| 89ea49 | 118 | .. code-block:: python |
| 76ff93 | 119 | |
| 89ea49 | 120 | def hello_world(request): |
| SP | 121 | return xResponse('<body><h1>Hello World!</h1></body>') |
| 76ff93 | 122 | |
| 89ea49 | 123 | Save, and visit http://localhost:6543/ again. |
| SP | 124 | Notice the nice traceback display. |
| 125 | On the lowest line, click the "screen" icon to the right, and try typing the variable names ``request`` and ``Response``. | |
| 126 | What else can you discover? | |
