1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
|
Installation
============
Getting the code
----------------
The recommended way to install the Debug Toolbar is via pip_::
$ pip install django-debug-toolbar
If you aren't familiar with pip, you may also obtain a copy of the
``debug_toolbar`` directory and add it to your Python path.
.. _pip: http://www.pip-installer.org/
To test an upcoming release, you can install the `in-development version
<http://github.com/django-debug-toolbar/django-debug-toolbar/tarball/master#egg=django-debug-toolbar-dev>`_
instead with the following command::
$ pip install django-debug-toolbar==dev
Quick setup
-----------
Add ``debug_toolbar`` to your ``INSTALLED_APPS`` setting::
INSTALLED_APPS = (
# ...
'debug_toolbar',
)
For a simple Django project, that's all you need!
The Debug Toolbar will automatically adjust a few settings when you start the
development server. This happens only when the ``DEBUG`` setting is ``True``.
If the automatic setup doesn't work for your project, if you want to learn
what it does, or if you prefer defining your settings explicitly, read below.
.. note::
The automatic setup relies on ``debug_toolbar.models`` being imported when
the server starts. Django doesn't provide a better hook to execute code
during the start-up sequence. This works with ``manage.py runserver``
because it validates models before serving requests.
Explicit setup
--------------
URLconf
~~~~~~~
Add the Debug Toolbar's URLs to your project's URLconf as follows::
from django.conf import settings
from django.conf.urls import include, patterns, url
if settings.DEBUG:
import debug_toolbar
urlpatterns += patterns('',
url(r'^__debug__/', include(debug_toolbar.urls)),
)
This example uses the ``__debug__`` prefix, but you can use any prefix that
doesn't clash with your application's URLs. Note the lack of quotes around
``debug_toolbar.urls``.
If the URLs aren't included in your root URLconf, the Debug Toolbar
automatically appends them.
Middleware
~~~~~~~~~~
The Debug Toolbar is mostly implemented in a middleware. Enable it in your
settings module as follows::
MIDDLEWARE_CLASSES = (
# ...
'debug_toolbar.middleware.DebugToolbarMiddleware',
# ...
)
The order of ``MIDDLEWARE_CLASSES`` is important. You should include the Debug
Toolbar middleware as early as possible in the list. However, it must come
after any other middleware that encodes the response's content, such as
``GZipMiddleware``.
If ``MIDDLEWARE_CLASSES`` doesn't contain the middleware, the Debug Toolbar
automatically adds it the beginning of the list.
Internal IPs
~~~~~~~~~~~~
The Debug Toolbar is shown only if your IP is listed in the ``INTERNAL_IPS``
setting. (You can change this logic with the ``SHOW_TOOLBAR_CALLBACK``
option.) For local development, you should add ``'127.0.0.1'`` to
``INTERNAL_IPS``.
If ``INTERNAL_IPS`` is empty, the Debug Toolbar automatically sets it to
``'127.0.0.1'`` and ``'::1'``.
|
