Metadata-Version: 1.1
Name: django-debugtools
Version: 2.0
Summary: A toolbox of small utilities to assist Django development
Home-page: https://github.com/edoburu/django-debugtools
Author: Diederik van der Boor
Author-email: opensource@edoburu.nl
License: Apache 2.0
Download-URL: https://github.com/edoburu/django-debugtools/zipball/master
Description: Introduction
        ============
        
        The ``debugtools`` module offers some easy to use debugging utilities to assist Django development.
        It features:
        
        * A template tag to print context.
        * A ``XViewMiddleware`` variation to see which *view* and *template* was used to render a page.
        * A panel for django-debug-toolbar_ to show which *view* and *template* was used to render a page.
        * A jQuery ``debug()`` function.
        
        
        Installation
        ============
        
        First install the module, preferably in a virtual environment. It can be installed from PyPI::
        
            pip install django-debugtools
        
        Or the current folder can be installed::
        
            pip install .
        
        Configuration
        -------------
        
        Add the module to the installed apps::
        
            INSTALLED_APPS += (
                'debugtools',
            )
        
        As of Django 1.9, either use ``{% load debugtools_tags %}`` or add the following to the settings:
        
        .. code-block:: python
        
            TEMPLATES = [
                {
                    'BACKEND': 'django.template.backends.django.DjangoTemplates',
                    'DIRS': [],
                    'APP_DIRS': True,
                    'OPTIONS': {
                        'context_processors': [
                            'django.template.context_processors.debug',
                            'django.template.context_processors.request',
                            # ...
                        ],
                       'builtins': [                                     # Add this section
                            "debugtools.templatetags.debugtools_tags",   # Add this line
                        ],
                    },
                },
            ]
        
        Or, when you use a ``local.py`` settings file:
        
        .. code-block:: python
        
            TEMPLATES[0]['OPTIONS']['builtins'] += [
                "debugtools.templatetags.debugtools_tags",  # enables {% print %}
            ]
        
        
        Features
        --------
        
        Print Template Tag
        ~~~~~~~~~~~~~~~~~~
        
        In Django templates, the following code can be used::
        
            {% print variable1 variable2 %}
        
        This will print out the specific variables, in case of ``{% print original %}``:
        
        .. image:: https://github.com/edoburu/django-debugtools/raw/master/docs/images/print-original.png
           :width: 959px
           :height: 166px
        
        When no variables are given (e.g. ``{% print %}``), all context variables are displayed:
        
        .. image:: https://github.com/edoburu/django-debugtools/raw/master/docs/images/template-context.png
           :width: 744px
           :height: 569px
        
        
        The template context variables are printed in a customized ``pprint.pformat`` format, for easy reading.
        Note no ``{% load %}`` tag is needed; the ``{% print %}`` function is added to the template builtins for debugging convenience.
        
        Print Queries template tag
        ~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        For convenience, there is also a ``{% print_queries %}`` tag,
        based on http://djangosnippets.org/snippets/93/
        
        For more sophisticated debugging, you may want to use the *django-debug-toolbar* for this job.
        
        
        Debug Toolbar Panel
        ~~~~~~~~~~~~~~~~~~~
        
        Add the following settings to your django-debug-toolbar_ configuration::
        
            DEBUG_TOOLBAR_PANELS = (
                'debug_toolbar.panels.versions.VersionsPanel',
                'debug_toolbar.panels.timer.TimerPanel',
                'debug_toolbar.panels.settings.SettingsPanel',
                'debug_toolbar.panels.headers.HeadersPanel',
                'debug_toolbar.panels.request.RequestPanel',
                'debug_toolbar.panels.sql.SQLPanel',
                'debug_toolbar.panels.staticfiles.StaticFilesPanel',
                'debugtools.panels.ViewPanel',    # Add this one
                'debug_toolbar.panels.templates.TemplatesPanel',
                'debug_toolbar.panels.cache.CachePanel',
                'debug_toolbar.panels.signals.SignalsPanel',
                'debug_toolbar.panels.logging.LoggingPanel',
                'debug_toolbar.panels.redirects.RedirectsPanel',
            )
        
        .. image:: https://github.com/edoburu/django-debugtools/raw/master/docs/images/debug-toolbar.png
           :width: 887px
           :height: 504px
        
        |
        
        jQuery debug print
        ~~~~~~~~~~~~~~~~~~
        
        Add the following to the page::
        
            <script type="text/javascript" src="{{ STATIC_URL }}debugtools/jquery.debug.js"></script>
        
        Now you can print the jQuery selector context to the console::
        
            $("#foo").children('li').debug().addClass('bar');
        
        This will print the matched ``<li>`` elements in the console, among with the current jQuery selector.
        Optionally, a prefix can be included in the ``debug()`` call::
        
            $("#foo").debug("at baz: ").addClass('bar');
        
        
        X-View Middleware
        ~~~~~~~~~~~~~~~~~
        
        As alternative to the django-debug-toolbar_ panel, you can also add the ``XViewMiddleware``.
        Add the following setting::
        
            INTERNAL_IPS = (
                '127.0.0.1',
            )
        
            MIDDLEWARE_CLASSES += (
                'debugtools.middleware.XViewMiddleware',
            )
        
        All requests from the internal IP, or made by the admin user will have a ``X-View`` header and ``X-View-Template`` header.
        In the Firebug console, or Chrome web inspector, you can see which view and template handled the current request:
        
        .. image:: https://github.com/edoburu/django-debugtools/raw/master/docs/images/firebug-xview.png
           :width: 811px
           :height: 41px
        
        The alternative templates are also displayed, in case the view allows the template to be overwritten with a different name.
        
        
        Print tag examples
        ------------------
        
        For example, when using the following code::
        
            {% print original %}
        
            {% print inline_admin_formset %}
        
            {% for inline_admin_form in inline_admin_formset %}
                {% print inline_admin_form %}
                {% print inline_admin_form.form.name %}
            {% endfor %}
        
        It prints the context values, which helps to learn a lot about the template context:
        
        .. image:: https://github.com/edoburu/django-debugtools/raw/master/docs/images/print-original.png
           :width: 959px
           :height: 166px
        
        |
        
        .. image:: https://github.com/edoburu/django-debugtools/raw/master/docs/images/inline_admin_formset.png
           :width: 959px
           :height: 208px
        
        |
        
        .. image:: https://github.com/edoburu/django-debugtools/raw/master/docs/images/inline_admin_form.png
           :width: 959px
           :height: 355px
        
        |
        
        .. image:: https://github.com/edoburu/django-debugtools/raw/master/docs/images/adminform.form.name.png
           :width: 959px
           :height: 352px
        
        This makes it much easier to understand what the code provides to templates.
        
        .. _django-debug-toolbar: https://github.com/django-debug-toolbar/django-debug-toolbar
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Framework :: Django
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.1
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Topic :: Software Development :: Debuggers
