trac.util.html – HTML transformations

Building HTML programmatically

With the introduction of the Genshi template engine in Trac 0.11, most of the (X)HTML content is produced directly using Genshi facilities, like the builder or snippet templates. The old html tag building facility is now not much more than an alias to the tag ElementFactory, and most of the code uses directly the latter.

trac.util.html.html

A TransposingElementFactory using str.lower transformation.

class trac.util.html.TransposingElementFactory(func, namespace=None)

A genshi.builder.ElementFactory which applies func to the named attributes before creating a genshi.builder.Element.

HTML clean-up and sanitization

class trac.util.html.TracHTMLSanitizer(safe_schemes=frozenset(['mailto', 'ftp', 'file', 'http', 'https', None]), safe_css=frozenset(['counter-reset', 'counter-increment', 'min-height', 'quotes', 'border-top', 'font', 'list-style-image', 'outline-width', 'border-right', 'border-radius', 'border-bottom', 'border-spacing', 'background', 'list-style-type', 'text-align', 'page-break-inside', 'orphans', 'page-break-before', 'border-bottom-right-radius', 'line-height', 'padding-left', 'font-size', 'right', 'word-spacing', 'padding-top', 'outline-style', 'bottom', 'content', 'border-right-style', 'padding-right', 'border-left-style', 'background-color', 'border-bottom-color', 'outline-color', 'unicode-bidi', 'max-width', 'font-family', 'caption-side', 'text-transform', 'border-right-width', 'border-top-style', 'color', 'border-collapse', 'border-bottom-width', 'float', 'height', 'max-height', 'margin-right', 'border-top-width', 'border-bottom-left-radius', 'top', 'border-width', 'min-width', 'width', 'font-variant', 'border-top-color', 'background-position', 'empty-cells', 'direction', 'border-left', 'visibility', 'padding', 'border-style', 'background-attachment', 'overflow', 'border-bottom-style', 'cursor', 'margin', 'display', 'border-left-width', 'letter-spacing', 'border-top-left-radius', 'vertical-align', 'clip', 'border-color', 'list-style', 'padding-bottom', 'margin-left', 'widows', 'border', 'font-style', 'border-left-color', 'background-repeat', 'table-layout', 'margin-bottom', 'border-top-right-radius', 'font-weight', 'opacity', 'border-right-color', 'page-break-after', 'white-space', 'text-indent', 'background-image', 'outline', 'clear', 'z-index', 'text-decoration', 'margin-top', 'position', 'left', 'list-style-position']))

Sanitize HTML constructions which are potentially vector of phishing or XSS attacks, in user-supplied HTML.

See also genshi.HTMLSanitizer.

class trac.util.html.Deuglifier

Help base class used for cleaning up HTML riddled with <FONT COLOR=...> tags and replace them with appropriate <span class="...">.

The subclass must define a rules() static method returning a list of regular expression fragments, each defining a capture group in which the name will be reused for the span’s class. Two special group names, font and endfont are used to emit <span> and </span>, respectively.

See some usage examples in tracopt.mimeview.enscript.EnscriptDeuglifier and tracopt.mimeview.php.PhpDeuglifier.

trac.util.html.escape()

Create a Markup instance from a string and escape special characters it may contain (<, >, & and ”).

>>> escape('"1 < 2"')
<Markup u'&#34;1 &lt; 2&#34;'>

If the quotes parameter is set to False, the ” character is left as is. Escaping quotes is generally only required for strings that are to be used in attribute values.

>>> escape('"1 < 2"', quotes=False)
<Markup u'"1 &lt; 2"'>

Parameters:

• text – the text to escape
• quotes – if True, double quote characters are escaped in addition to the other special characters

Returns:

the escaped Markup string

Return type:

Markup

trac.util.html.unescape(text)

Reverse-escapes &, <, >, and ” and returns a unicode object.

>>> unescape(Markup('1 < 2'))
u'1 < 2'

If the provided text object is not a Markup instance, it is returned unchanged.

>>> unescape('1 < 2')
'1 < 2'

Parameters:text – the text to unescape Returns:the unescsaped string Return type:unicode

class trac.util.html.FormTokenInjector(form_token, out)

Identify and protect forms from CSRF attacks.

This filter works by adding a input type=hidden field to POST forms.

Misc. HTML processing

trac.util.html.expand_markup(stream, ctxt=None)

A Genshi stream filter for expanding genshi.Markup events.

Note: Expansion may not be possible if the fragment is badly formed, or partial.

trac.util.html.find_element(frag, attr=None, cls=None, tag=None)

Return the first element in the fragment having the given attribute, class or tag, using a preorder depth-first search.

trac.util.html.plaintext(text, keeplinebreaks=True)

Extract the text elements from (X)HTML content

Parameters:

• text – unicode or genshi.builder.Fragment
• keeplinebreaks – optionally keep linebreaks