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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
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
instead with the following command::
$ pip install -e git+https://github.com/django-debug-toolbar/django-debug-toolbar.git#egg=django-debug-toolbar
Quick setup
-----------
Make sure that ``'django.contrib.staticfiles'`` is `set up properly
<https://docs.djangoproject.com/en/stable/howto/static-files/>`_ and add
``'debug_toolbar.apps.DebugToolbarConfig'`` (Django ≥ 1.7) or
``'debug_toolbar'`` (Django < 1.7) to your ``INSTALLED_APPS`` setting::
INSTALLED_APPS = (
# ...
'django.contrib.staticfiles',
# ...
# If you're using Django 1.7.x or later
'debug_toolbar.apps.DebugToolbarConfig',
# If you're using Django 1.6.x or earlier
'debug_toolbar',
)
STATIC_URL = '/static/'
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, provided the ``DEBUG`` setting is ``True``.
If you're upgrading from a previous version, you should review the
:doc:`change log <changes>` and look for specific upgrade instructions.
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.
.. warning::
The automatic setup imports your project's URLconf in order to add the
Debug Toolbar's URLs. This may trigger circular imports, for instance when
the URLconf imports views that import models. If the development server
crashes with a long stack trace after hitting an :exc:`ImportError` or an
:exc:`~django.core.exceptions.ImproperlyConfigured` exception, follow the
explicit setup instructions.
Explicit setup
--------------
First, tell the toolbar not to adjust your settings automatically by adding
this line in your settings module::
DEBUG_TOOLBAR_PATCH_SETTINGS = False
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'``.
|
