mirror of
https://github.com/django/django.git
synced 2024-12-29 12:36:08 +00:00
757c456d23
Added a tutorial step that highlights Django Debug Toolbar, on of the most common third party packages. It also added a mention of djangopackages.com as a place to search for other libraries and a link to Adam Johnson’s post on evaluating whether a package is well-maintained. Third-party packages are one of Django’s strengths. This should give folks a sound route in. Backport of7715c9fef5and1df7814e4bfrom main
102 lines
4.7 KiB
Plaintext
102 lines
4.7 KiB
Plaintext
=====================================
|
||
Writing your first Django app, part 8
|
||
=====================================
|
||
|
||
This tutorial begins where :doc:`Tutorial 7 </intro/tutorial07>` left off. We've
|
||
built our web-poll application and will now look at third-party packages. One of
|
||
Django's strengths is the rich ecosystem of third-party packages. They're
|
||
community developed packages that can be used to quickly improve the feature set
|
||
of an application.
|
||
|
||
This tutorial will show how to add `Django Debug Toolbar
|
||
<https://django-debug-toolbar.readthedocs.io>`_, a commonly used third-party
|
||
package. The Django Debug Toolbar has ranked in the top three most used
|
||
third-party packages in the Django Developers Survey in recent years.
|
||
|
||
.. admonition:: Where to get help:
|
||
|
||
If you're having trouble going through this tutorial, please head over to
|
||
the :doc:`Getting Help</faq/help>` section of the FAQ.
|
||
|
||
Installing Django Debug Toolbar
|
||
===============================
|
||
|
||
Django Debug Toolbar is a useful tool for debugging Django web applications.
|
||
It's a third-party package maintained by the `Jazzband
|
||
<https://jazzband.co>`_ organization. The toolbar helps you understand how your
|
||
application functions and to identify problems. It does so by providing panels
|
||
that provide debug information about the current request and response.
|
||
|
||
To install a third-party application like the toolbar, you need to install
|
||
the package by running the below command within an activated virtual
|
||
environment. This is similar to our earlier step to :ref:`install Django
|
||
<installing-official-release>`.
|
||
|
||
.. console::
|
||
|
||
$ python -m pip install django-debug-toolbar
|
||
|
||
Third-party packages that integrate with Django need some post-installation
|
||
setup to integrate them with your project. Often you will need to add the
|
||
package's Django app to your :setting:`INSTALLED_APPS` setting. Some packages
|
||
need other changes, like additions to your URLconf (``urls.py``).
|
||
|
||
Django Debug Toolbar requires several setup steps. Follow them in `its
|
||
installation guide
|
||
<https://django-debug-toolbar.readthedocs.io/en/latest/installation.html>`_.
|
||
The steps are not duplicated in this tutorial, because as a third-party
|
||
package, it may change separately to Django's schedule.
|
||
|
||
Once installed, you should be able to see the DjDT "handle" on the right side
|
||
of the browser window when you refresh the polls application. Click it to open
|
||
the debug toolbar and use the tools in each panel. See the `panels
|
||
documentation page
|
||
<https://django-debug-toolbar.readthedocs.io/en/latest/panels.html>`__ for more
|
||
information on what the panels show.
|
||
|
||
Getting help from others
|
||
========================
|
||
|
||
At some point you will run into a problem, for example the
|
||
toolbar may not render. When this happens and you're unable to
|
||
resolve the issue yourself, there are options available to you.
|
||
|
||
#. If the problem is with a specific package, check if there's a
|
||
troubleshooting of FAQ in the package's documentation. For example the
|
||
Django Debug Toolbar has a `Tips section
|
||
<https://django-debug-toolbar.readthedocs.io/en/latest/tips.html>`_ that
|
||
outlines troubleshooting options.
|
||
#. Search for similar issues on the package's issue tracker. Django Debug
|
||
Toolbar’s is `on GitHub <https://github.com/jazzband/django-debug-toolbar/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc>`_.
|
||
#. Consult the `Django Forum <https://forum.djangoproject.com/>`_.
|
||
#. Join the `Django Discord server <https://discord.gg/xcRH6mN4fa>`_.
|
||
#. Join the #Django IRC channel on `Libera.chat <https://libera.chat/>`_.
|
||
|
||
Installing other third-party packages
|
||
=====================================
|
||
|
||
There are many more third-party packages, which you can find using the
|
||
fantastic Django resource, `Django Packages <https://djangopackages.org/>`_.
|
||
|
||
It can be difficult to know what third-party packages you should use. This
|
||
depends on your needs and goals. Sometimes it's fine to use a package that's
|
||
in its alpha state. Other times, you need to know it's production ready.
|
||
`Adam Johnson has a blog post
|
||
<https://adamj.eu/tech/2021/11/04/the-well-maintained-test/>`_ that outlines
|
||
a set of characteristics a that qualifies a package as "well maintained".
|
||
Django Packages shows data for some of these characteristics, such as when the
|
||
package was last updated.
|
||
|
||
As Adam points out in his post, when the answer to one of the questions is
|
||
"no", that's an opportunity to contribute.
|
||
|
||
What's next?
|
||
============
|
||
|
||
The beginner tutorial ends here. In the meantime, you might want to check out
|
||
some pointers on :doc:`where to go from here </intro/whatsnext>`.
|
||
|
||
If you are familiar with Python packaging and interested in learning how to
|
||
turn polls into a "reusable app", check out :doc:`Advanced tutorial: How to
|
||
write reusable apps</intro/reusable-apps>`.
|