Modern Python Standard Library Cookbook

How it works...

Whenever the HTMLFormatter has to replace a value in the format string, it will check whether the retrieved value has a __html__ method:

if hasattr(val, '__html__'):
    val = val.__html__()

If that method exists, it's expected to return the HTML representation of the value. And that's expected to be a perfectly valid and escaped HTML.

Otherwise, the value is expected to be a string that needs escaping:

elif isinstance(val, str):
    val = cgi.escape(val)

This makes it so that any value we provide to the HTMLFormatter gets escaped by default:

>>> html = HTMLFormatter().format('Hello {name}', 
                                  name='<strong>Name</strong>')
>>> print(html)
Hello &lt;strong&gt;Name&lt;/strong&gt;

If we want to avoid escaping, we can rely on the Markup ...