Debian Codegraph @

docs/intro/tutorial08.txt

raw
1 =====================================
2 Writing your first Django app, part 8
3 =====================================
4
5 This tutorial begins where :doc:`Tutorial 7 </intro/tutorial07>` left off. We've
6 built our web-poll application and will now look at third-party packages. One of
7 Django's strengths is the rich ecosystem of third-party packages. They're
8 community developed packages that can be used to quickly improve the feature set
9 of an application.
10
11 This tutorial will show how to add :pypi:`Django Debug Toolbar
12 <django-debug-toolbar>`, a commonly used third-party package. The Django Debug
13 Toolbar has ranked in the top three most used third-party packages in the
14 Django Developers Survey in recent years.
15
16 .. admonition:: Where to get help:
17
18 If you're having trouble going through this tutorial, please head over to
19 the :doc:`Getting Help</faq/help>` section of the FAQ.
20
21 Installing Django Debug Toolbar
22 ===============================
23
24 Django Debug Toolbar is a useful tool for debugging Django web applications.
25 It's a third-party package that is maintained by the community organization
26 `Django Commons <https://github.com/django-commons>`_. The toolbar helps you
27 understand how your application functions and to identify problems. It does so
28 by providing panels that provide debug information about the current request
29 and response.
30
31 To install a third-party application like the toolbar, you need to install
32 the package by running the below command within an activated virtual
33 environment. This is similar to our earlier step to :ref:`install Django
34 <installing-official-release>`.
35
36 .. console::
37
38 $ python -m pip install django-debug-toolbar
39
40 Third-party packages that integrate with Django need some post-installation
41 setup to integrate them with your project. Often you will need to add the
42 package's Django app to your :setting:`INSTALLED_APPS` setting. Some packages
43 need other changes, like additions to your URLconf (``urls.py``).
44
45 Django Debug Toolbar requires several setup steps. Follow them in `its
46 installation guide
47 <https://django-debug-toolbar.readthedocs.io/en/latest/installation.html>`_.
48 The steps are not duplicated in this tutorial, because as a third-party
49 package, it may change separately to Django's schedule.
50
51 Once installed, you should be able to see the DjDT "handle" on the right side
52 of the browser window when you browse to ``http://localhost:8000/admin/``.
53 Click it to open the debug toolbar and use the tools in each panel. See the
54 `panels documentation page`__ for more information on what the panels show.
55
56 __ https://django-debug-toolbar.readthedocs.io/en/latest/panels.html
57
58 Getting help from others
59 ========================
60
61 At some point you will run into a problem, for example the
62 toolbar may not render. When this happens and you're unable to
63 resolve the issue yourself, there are options available to you.
64
65 #. If the problem is with a specific package, check if there's a
66 troubleshooting guide or FAQ in the package's documentation. For example the
67 Django Debug Toolbar has a `Tips section
68 <https://django-debug-toolbar.readthedocs.io/en/latest/tips.html>`_ that
69 outlines troubleshooting options.
70 #. Search for similar issues on the package's issue tracker. Django Debug
71 Toolbar’s is `on GitHub <https://github.com/django-commons/django-debug-toolbar/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc>`_.
72 #. Consult the `Django Forum <https://forum.djangoproject.com/>`_.
73 #. Join the `Django Discord server <https://chat.djangoproject.com>`_.
74
75 Installing other third-party packages
76 =====================================
77
78 There are many more third-party packages, which you can find using the
79 fantastic Django resource, `Django Packages <https://djangopackages.org/>`_.
80
81 It can be difficult to know what third-party packages you should use. This
82 depends on your needs and goals. Sometimes it's fine to use a package that's
83 in its alpha state. Other times, you need to know it's production ready.
84 `Adam Johnson has a blog post
85 <https://adamj.eu/tech/2021/11/04/the-well-maintained-test/>`_ that outlines
86 a set of characteristics that qualifies a package as "well maintained".
87 Django Packages shows data for some of these characteristics, such as when the
88 package was last updated.
89
90 As Adam points out in his post, when the answer to one of the questions is
91 "no", that's an opportunity to contribute.
92
93 What's next?
94 ============
95
96 The beginner tutorial ends here. In the meantime, you might want to check out
97 some pointers on :doc:`where to go from here </intro/whatsnext>`.
98
99 If you are familiar with Python packaging and interested in learning how to
100 turn polls into a "reusable app", check out :doc:`Advanced tutorial: How to
101 write reusable apps</intro/reusable-apps>`.