Deprecate format_html calls without args or kwargs

[Adam Johnson]

In my experience, a common misuse of format_html is to format the HTML before calling it:

format_html(f"<i>{name}</i>")

This makes it act like mark_safe, allowing data through without escaping. It provides a false sense of security since format_html is meant to be the "safe way".

I propose we deprecate calls to format_html that don’t pass args or kwargs, and eventually raise a TypeError for such cases.

(Following improvement to format_html docs in #34595.)

[Bhuvnesh]

django/utils/html.py

@@ -100 +100 @@
     and call mark_safe() on the result. This function should be used instead
     of str.format or % interpolation to build up small HTML fragments.
     """
+    if not (args or kwargs):
+        raise TypeError("Arguments are missing.")
     args_safe = map(conditional_escape, args)
     kwargs_safe = {k: conditional_escape(v) for (k, v) in kwargs.items()}
     return mark_safe(format_string.format(*args_safe, **kwargs_safe))

tests/utils_tests/test_html.py

@@ -65 +65 @@
             "&lt; Dangerous &gt; <b>safe</b> &lt; dangerous again <i>safe again</i>",
         )
 
+    def test_format_html_no_args(self):
+        msg = "Arguments are missing."
+        with self.assertRaisesMessage(TypeError, msg):
+            self.assertEqual(
+                format_html(
+                    "<i>{name}</i>",
+                ),
+                "<i>Adam</i>",
+            )
+
     def test_linebreaks(self):
         items = (
             ("para1\n\npara2\r\rpara3", "<p>para1</p>\n\n<p>para2</p>\n\n<p>para3</p>"),

Are these changes relevant? I don't have much experience with templates, still a lot to learn .😅

[Michael Howitz]

@Bhuvnesh The issues talks about deprecating that args resp. kwargs can be missing.
By raising an exception your suggested change make it impossible to call the function without these parameters. Maybe this is a bit too harsh.
See also ​https://docs.djangoproject.com/en/dev/internals/release-process/#internal-release-deprecation-policy for documentation how to deprecate a feature.

[Bhuvnesh]

OK, so instead of TypeError I should raise a RemovedInDjango60Warning warning? It will raise warnings in v5.x and completely removed in v6.0 .

[Bhuvnesh]

​PR

[Mariusz Felisiak <felisiak.mariusz@…>]

In 094b0be:

Fixed #34609 -- Deprecated calling format_html() without arguments.

[GitHub <noreply@…>]

In 2b71b2c:

Refs #34609 -- Fixed deprecation warning stack level in format_html().

Co-authored-by: Simon Charette <charette.s@…>

[Natalia <124304+nessita@…>]

In 03e0ab5:

[5.1.x] Refs #34609 -- Fixed deprecation warning stack level in format_html().

Co-authored-by: Simon Charette <charette.s@…>

Backport of 2b71b2c8dcd40f2604310bb3914077320035b399 from main.

[Sarah Boyce <42296566+sarahboyce@…>]

In 1e331911:

Refs #34609 -- Removed support for calling format_html() without arguments per deprecation timeline.