twisted.web._flatten.writeWithAttributeEscaping(write) function documentation

Decorate a write callable so that all output written is properly quoted for inclusion within an XML attribute value.

If a Tag x is flattened within the context of the contents of another Tag y, the metacharacters (<>&") delimiting x should be passed through unchanged, but the textual content of x should still be quoted, as usual. For example: <y><x>&amp;</x></y>. That is the default behavior of _flattenElement when escapeForContent is passed as the dataEscaper.

However, when a Tag x is flattened within the context of an attribute of another Tag y, then the metacharacters delimiting x should be quoted so that it can be parsed from the attribute's value. In the DOM itself, this is not a valid thing to do, but given that renderers and slots may be freely moved around in a twisted.web.template template, it is a condition which may arise in a document and must be handled in a way which produces valid output. So, for example, you should be able to get <y attr="&lt;x /&gt;" />. This should also be true for other XML/HTML meta-constructs such as comments and CDATA, so if you were to serialize a comment in an attribute you should get <y attr="&lt;-- comment --&gt;" />. Therefore in order to capture these meta-characters, flattening is done with write callable that is wrapped with writeWithAttributeEscaping.

The final case, and hopefully the much more common one as compared to serializing Tag and arbitrary IRenderable objects within an attribute, is to serialize a simple string, and those should be passed through for writeWithAttributeEscaping to quote without applying a second, redundant level of quoting.