Applies a monkeypatch which forces Django's template language to error far more loudly about invalid assumptions
Project description
- Version:
- 0.2.0
Brief
This app applies a monkeypatch which forces Django’s template language to error very loudly about variables which are used in a template but don’t exist in the context.
Rationale
Given a template like this:
<html><head></head>
<body>
{% if chef.can_add_cakes %}
<label class="alert alert-{{ chef.is_cake_chef|yesno:"success,danger,default" }}
{% endif %}
everything works fine, until you refactor and any of the following happens:
chef is no longer the name of the variable.
can_add_cakes is refactored to be called can_add_pastries
is_cake_chef is renamed is_pastry_king
If those happen, the template will either silently display nothing, or will display the label incorrectly. This monkeypatch attempts to fix that.
Specifically:
chef will raise an exception if the variable were called sous_chef
chef.can_add_cakes will raise an exception if can_add_cakes was no longer a valid attribute/property/method of chef
chef.is_cake_chef will raise an exception for the same reasons.
Thus you can refactor somewhat more freely, knowing that if the template renders it’s OK. It ain’t compile time safety, but it’s better than silently swallowing errors because you forgot something!
The exception itself would look something like:
Token 'chef' of 'chef.can_add_cakes' in template 'my/cool/template.html' does not resolve. Possibly you meant to use 'sous_chef'. Silence this occurance only by adding 'chef.can_add_cakes': ['my/cool/template.html'] to the settings.SHOUTY_VARIABLE_BLACKLIST dictionary. Silence this globally by adding 'chef.can_add_cakes': ['*'] to the settings.SHOUTY_VARIABLE_BLACKLIST dictionary.
Setup
This package is available on PyPI and can be installed using pip or whatever like so:
pip install django-shouty-templates==0.2.0
Then add shouty.Shout or shouty to your settings.INSTALLED_APPS
Optional configuration
A list of values which may be set in your project’s settings module:
settings.SHOUTY_VARIABLES
May be True|False and determines if the exception is raised when trying to use a variable which doesn’t exist.
Defaults to True.
settings.SHOUTY_URLS
May be True|False and determines if an exception is raised when doing {% url 'myurl' as my_var %} and myurl doesn’t actually resolve to a view.
Defaults to True.
settings.SHOUTY_VARIABLE_BLACKLIST
Useful for if you are trying to fix up an existing project, or ignore problems in third-party templates.
Expects a dict of str keys and a sequence (eg: tuple or list) of templates in which to ignore it:
SHOUTY_VARIABLE_BLACKLIST = {
"chef.can_add_cakes": ("*",),
"my_sometimes_set_variable": ["admin/custom_view.html", "admin/custom_view_detail.html"],
"random_in_memory_template": ["<unknown source>"],
"*": ["admin/login.html", "<unknown source>"],
}
Of special note is the use of *, which has a more magical meaning.
Using "key": ["*"] would silence errors about the variable named key in all templates
Using "*": ["path/to/template.html"] would silence all variable errors in that specific template only (see GitHub issue 6)
And also the far less frequently useful <unknown source> or django.template.base.UNKNOWN_SOURCE which is essentially usually for Template instances not loaded from a file on disk
settings.SHOUTY_URL_BLACKLIST
A tuple of 2-tuple to prevent certain URLs and their output variables f rom shouting at you loudly. Useful for existing projects or third-party apps which are less strict.
By way of example, {% url "myurl" as my_var %} may be suppressed with:
SHOUTY_URL_BLACKLIST = (
('myurl', 'my_var'),
)
which would still let {% url "myurl" as "my_other_var" %} raise an exception.
Default configuration
There’s a hard-coded blacklist of variables and URLs to make sure the Django admin (+ admindocs), django-debug-toolbar, django-pipeline, django-admin-honeypot, djangorestframework, etc all work.
if/elif/else testing
When an {% if x %} statement is seen in the template, all conditions are checked to ensure the context will always resolve correctly. Additionally, if you use {% if %} and {% elif %} together and don’t have an {% else %} it’ll raise an error to remind you to handle that case, even if handling it is just to output nothing.
Tests
Just run python3 -m shouty and hope for the best. I usually do.
The license
It’s FreeBSD. There’s should be a LICENSE file in the root of the repository, and in any archives.
Copyright (c) 2019, Keryn Knight All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Change history for django-shouty-templates
0.2.0
Bugfix: Updates to ostensibly support Django 4.0+
Feature: Error loudly when an {% if ... %}...{% elif %} statement is present without an {% else %}
Feature: Allow for silencing all missing variables within a single given template (or set of templates)
Bugfix: Attempt to fix parsing of where a missing variable occurs within things like {% blocktrans with filter_title=title %}
Bugfix: when the render_context doesn’t have a template or it’s None it’s now properly skipped.
0.1.6
Feature: Ignore variables which prevented much of REST Framework’s browsable API from working.
Feature: Ignore variables which would cause the django-admin-honeypot package’s fake login screen to error.
Feature: Ignore variables which might cause django-pipeline rendering of <link> and <script> to error.
Bugfix: Improve per-template silencing via SHOUTY_VARIABLE_BLACKLIST
Bugfix: Attempt to have fewer false positives when highlighting the location in the template of the exception.
0.1.5
Feature: system check to validate any SHOUTY_VARIABLE_BLACKLIST in your settings.
Feature: Attempt to highlight the exception location in any subtemplate, better than Django currently does.
Feature: Update exception message with any potential typo candidates.
Feature: Silencing missing variables on a per-template basis.
Feature: Deep inspection of {% if ... %} {% elif ... %} nodes for any which are variables which don’t exist.
Bugfix: Patch methods hidden from the debug error page should now be consistently hidden always, rather than dependant on hitting the expected branch.
Bugfix: Unit tests now exist to demonstrate how it should behave, at least on Django 2.2~
0.1.4
Feature: the patch methods themselves (new_resolve_lookup and new_url_render) are skipped during rendering the debug error page. The exception message and functionality remain the same.
Feature: exception messages now attempt to clarify what template name (loader relative) was rendering when the missing variable was encountered.
Chore: Updated the mypy type signatures for some of the variables and methods to indicate the only values I’m expecting to accept.
0.1.3
Feature: Silenced errors when using debug or sql_queries in a template, as they’re conditionally set by django.template.context_processors.debug
0.1.2
Feature: Added 11 new tokens to the default blacklist, covering more of the default Django admin and the default exception reporter.
Bugfix: Changed the syntax of the AppConfig.ready method to be py2 type annotation compatible.
0.1.1
Initial release
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django-shouty-templates-0.2.0.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | a828f462a93bff67314408a24325450c04a978133bedb584d98288de72e491b1 |
|
| MD5 | 8ba25237685878f1d55f24405644fc56 |
|
| BLAKE2b-256 | 4042cbf63e390369bf4870ecb28f3ed840fdd83047878418b1e0ee409148bb58 |
Hashes for django_shouty_templates-0.2.0-py2.py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | d0b92f866519b106a0d94f5f51cda281d3eb537a4d1f7718234808b646227b62 |
|
| MD5 | 44e511665ebb0bd55398a5c25fc6cb07 |
|
| BLAKE2b-256 | 605b192123ca919abb386d28575df8897301497be2f44da0ff028842b38a8bfb |
