tornado.escape — Escaping and string manipulation

Escaping/unescaping methods for HTML, JSON, URLs, and others.

Also includes a few other miscellaneous string manipulation functions that have crept in over time.

Escaping functions


Escapes a string so it is valid within XML or XHTML.


Un-escapes an XML-escaped string.


Returns a valid URL-encoded version of the given value.

tornado.escape.url_unescape(value, encoding='utf-8')[source]

Decodes the given value from a URL.

The argument may be either a byte or unicode string.

If encoding is None, the result will be a byte string. Otherwise, the result is a unicode string in the specified encoding.


JSON-encodes the given Python object.


Returns Python objects for the given JSON string.

Byte/unicode conversions

These functions are used extensively within Tornado itself, but should not be directly needed by most applications. Note that much of the complexity of these functions comes from the fact that Tornado supports both Python 2 and Python 3.


Converts a string argument to a byte string.

If the argument is already a byte string or None, it is returned unchanged. Otherwise it must be a unicode string and is encoded as utf8.


Converts a string argument to a unicode string.

If the argument is already a unicode string or None, it is returned unchanged. Otherwise it must be a byte string and is decoded as utf8.


Converts a byte or unicode string into type str. Equivalent to utf8 on Python 2 and to_unicode on Python 3.


Converts a string argument to a subclass of basestring.

In python2, byte and unicode strings are mostly interchangeable, so functions that deal with a user-supplied argument in combination with ascii string constants can use either and should return the type the user supplied. In python3, the two types are not interchangeable, so this method is needed to convert byte strings to unicode.


Walks a simple data structure, converting byte strings to unicode.

Supports lists, tuples, and dictionaries.

Miscellaneous functions

tornado.escape.linkify(text, shorten=False, extra_params='', require_protocol=False, permitted_protocols=['http', 'https'])[source]

Converts plain text into HTML with links.

For example: linkify("Hello!") would return Hello <a href=""></a>!


shorten: Long urls will be shortened for display.

extra_params: Extra text to include in the link tag, or a callable

taking the link as an argument and returning the extra text e.g. linkify(text, extra_params='rel="nofollow" class="external"'), or:

def extra_params_cb(url):
    if url.startswith(""):
        return 'class="internal"'
        return 'class="external" rel="nofollow"'
linkify(text, extra_params=extra_params_cb)
require_protocol: Only linkify urls which include a protocol. If this is
False, urls such as will also be linkified.
permitted_protocols: List (or set) of protocols which should be linkified,
e.g. linkify(text, permitted_protocols=[“http”, “ftp”, “mailto”]). It is very unsafe to include protocols such as “javascript”.

Replace all sequences of whitespace chars with a single space.