From d3a982556d655adcf4ba331d2def685d8249170f Mon Sep 17 00:00:00 2001 From: Aymeric Augustin Date: Sun, 14 Dec 2014 23:13:03 +0100 Subject: [PATCH] Deprecated TEMPLATE_STRING_IF_INVALID. --- docs/internals/deprecation.txt | 1 + docs/ref/settings.txt | 5 ++++ docs/ref/templates/api.txt | 36 ++++++++++++-------------- docs/releases/1.6.txt | 2 +- docs/releases/1.8.txt | 1 + docs/topics/templates.txt | 6 ++--- tests/template_tests/test_callables.py | 2 +- tests/template_tests/tests.py | 8 +++++- tests/template_tests/utils.py | 16 ++++++------ 9 files changed, 44 insertions(+), 33 deletions(-) diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index eaaec49349..415b61eafd 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -90,6 +90,7 @@ details on these changes. * The following settings will be removed: * ``ALLOWED_INCLUDE_ROOTS`` + * ``TEMPLATE_STRING_IF_INVALID`` * The backwards compatibility alias ``django.template.loader.BaseLoader`` will be removed. diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index de50302e97..dd01e9e1cd 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -2452,6 +2452,11 @@ TEMPLATE_STRING_IF_INVALID Default: ``''`` (Empty string) +.. deprecated:: 1.8 + + Set the ``'string_if_invalid'`` option in the :setting:`OPTIONS + ` of a ``DjangoTemplates`` backend instead. + Output, as a string, that the template system should use for invalid (e.g. misspelled) variables. See :ref:`invalid-template-variables`. diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index ce28fbff74..5aacb2bc09 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -171,7 +171,7 @@ straight lookups. Here are some things to keep in mind: ``silent_variable_failure`` whose value is ``True``. If the exception *does* have a ``silent_variable_failure`` attribute whose value is ``True``, the variable will render as the value of the - :setting:`TEMPLATE_STRING_IF_INVALID` setting (an empty string, by default). + ``string_if_invalid`` configuration option (an empty string, by default). Example:: >>> t = Template("My name is {{ person.first_name }}.") @@ -200,7 +200,7 @@ straight lookups. Here are some things to keep in mind: silently. * A variable can only be called if it has no required arguments. Otherwise, - the system will return the value of :setting:`TEMPLATE_STRING_IF_INVALID`. + the system will return the value of the ``string_if_invalid`` option. .. _alters-data-description: @@ -217,7 +217,7 @@ straight lookups. Here are some things to keep in mind: To prevent this, set an ``alters_data`` attribute on the callable variable. The template system won't call a variable if it has ``alters_data=True`` set, and will instead replace the variable with - :setting:`TEMPLATE_STRING_IF_INVALID`, unconditionally. The + ``string_if_invalid``, unconditionally. The dynamically-generated :meth:`~django.db.models.Model.delete` and :meth:`~django.db.models.Model.save` methods on Django model objects get ``alters_data=True`` automatically. Example:: @@ -239,36 +239,34 @@ How invalid variables are handled ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Generally, if a variable doesn't exist, the template system inserts the -value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set to +value of the ``string_if_invalid`` configuration option, which is set to ``''`` (the empty string) by default. Filters that are applied to an invalid variable will only be applied if -:setting:`TEMPLATE_STRING_IF_INVALID` is set to ``''`` (the empty string). If -:setting:`TEMPLATE_STRING_IF_INVALID` is set to any other value, variable -filters will be ignored. +``string_if_invalid`` is set to ``''`` (the empty string). If +``string_if_invalid`` is set to any other value, variable filters will be +ignored. This behavior is slightly different for the ``if``, ``for`` and ``regroup`` template tags. If an invalid variable is provided to one of these template tags, the variable will be interpreted as ``None``. Filters are always applied to invalid variables within these template tags. -If :setting:`TEMPLATE_STRING_IF_INVALID` contains a ``'%s'``, the format marker will -be replaced with the name of the invalid variable. +If ``string_if_invalid`` contains a ``'%s'``, the format marker will be +replaced with the name of the invalid variable. .. admonition:: For debug purposes only! - While :setting:`TEMPLATE_STRING_IF_INVALID` can be a useful debugging tool, - it is a bad idea to turn it on as a 'development default'. + While ``string_if_invalid`` can be a useful debugging tool, it is a bad + idea to turn it on as a 'development default'. - Many templates, including those in the Admin site, rely upon the - silence of the template system when a non-existent variable is - encountered. If you assign a value other than ``''`` to - :setting:`TEMPLATE_STRING_IF_INVALID`, you will experience rendering - problems with these templates and sites. + Many templates, including those in the Admin site, rely upon the silence + of the template system when a non-existent variable is encountered. If you + assign a value other than ``''`` to ``string_if_invalid``, you will + experience rendering problems with these templates and sites. - Generally, :setting:`TEMPLATE_STRING_IF_INVALID` should only be enabled - in order to debug a specific template problem, then cleared - once debugging is complete. + Generally, ``string_if_invalid`` should only be enabled in order to debug + a specific template problem, then cleared once debugging is complete. Builtin variables ~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index bdf4e2f918..538394b2a3 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -233,7 +233,7 @@ Minor features PostgreSQL. * The :ttag:`blocktrans` template tag now respects - :setting:`TEMPLATE_STRING_IF_INVALID` for variables not present in the + ``TEMPLATE_STRING_IF_INVALID`` for variables not present in the context, just like other template constructs. * ``SimpleLazyObject``\s will now present more helpful representations in shell diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt index 8ce36fcb6c..d43ab2e51b 100644 --- a/docs/releases/1.8.txt +++ b/docs/releases/1.8.txt @@ -1021,6 +1021,7 @@ As a consequence of the multiple template engines refactor, several settings are deprecated in favor of :setting:`TEMPLATES`: * ``ALLOWED_INCLUDE_ROOTS`` +* ``TEMPLATE_STRING_IF_INVALID`` ``django.core.context_processors`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt index e245a7899e..dc145924c9 100644 --- a/docs/topics/templates.txt +++ b/docs/topics/templates.txt @@ -116,9 +116,9 @@ Use a dot (``.``) to access attributes of a variable. In the above example, ``{{ section.title }}`` will be replaced with the ``title`` attribute of the ``section`` object. -If you use a variable that doesn't exist, the template system will insert -the value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set -to ``''`` (the empty string) by default. +If you use a variable that doesn't exist, the template system will insert the +value of the ``string_if_invalid`` option, which is set to ``''`` (the empty +string) by default. Note that "bar" in a template expression like ``{{ foo.bar }}`` will be interpreted as a literal string and not using the value of the variable "bar", diff --git a/tests/template_tests/test_callables.py b/tests/template_tests/test_callables.py index 9a47a5b96f..5536b382ff 100644 --- a/tests/template_tests/test_callables.py +++ b/tests/template_tests/test_callables.py @@ -53,7 +53,7 @@ class CallableVariablesTests(TestCase): c = template.Context({"my_doodad": my_doodad}) # Since ``my_doodad.alters_data`` is True, the template system will not - # try to call our doodad but will use TEMPLATE_STRING_IF_INVALID + # try to call our doodad but will use string_if_invalid t = template.Template('{{ my_doodad.value }}') self.assertEqual(t.render(c), '') t = template.Template('{{ my_doodad.the_value }}') diff --git a/tests/template_tests/tests.py b/tests/template_tests/tests.py index 0466f91c7a..5128fd64d5 100644 --- a/tests/template_tests/tests.py +++ b/tests/template_tests/tests.py @@ -258,7 +258,13 @@ class TemplateRegressionTests(SimpleTestCase): with self.assertRaises(urlresolvers.NoReverseMatch): t.render(c) - @override_settings(TEMPLATE_STRING_IF_INVALID='%s is invalid', SETTINGS_MODULE='also_something') + @override_settings( + TEMPLATES=[{ + 'BACKEND': 'django.template.backends.django.DjangoTemplates', + 'OPTIONS': {'string_if_invalid': '%s is invalid'}, + }], + SETTINGS_MODULE='also_something', + ) def test_url_reverse_view_name(self): # Regression test for #19827 t = Template('{% url will_not_match %}') diff --git a/tests/template_tests/utils.py b/tests/template_tests/utils.py index 864cd7d044..3c37be18e4 100644 --- a/tests/template_tests/utils.py +++ b/tests/template_tests/utils.py @@ -22,14 +22,14 @@ def setup(templates, *args): """ Runs test method multiple times in the following order: - TEMPLATE_DEBUG CACHED TEMPLATE_STRING_IF_INVALID - -------------- ------ -------------------------- - False False - False True - False False INVALID - False True INVALID - True False - True True + debug cached string_if_invalid + ----- ------ ----------------- + False False + False True + False False INVALID + False True INVALID + True False + True True """ for arg in args: