# `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.

Many functions in this module have near-equivalents in the standard library (the differences mainly relate to handling of bytes and unicode strings, and were more relevant in Python 2). In new code, the standard library functions are encouraged instead of this module where applicable. See the docstrings on each function for details.

## Escaping functions

tornado.escape.xhtml_escape(value: str | bytes) → str

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

  Escapes the characters `<`, `>`, `"`, `'`, and `&`. When used in attribute values the escaped strings must be enclosed in quotes.

  Equivalent to `html.escape` except that this function always returns type `str` while `html.escape` returns `bytes` if its input is `bytes`.

  Changed in version 3.2: Added the single quote to the list of escaped characters.

  Changed in version 6.4: Now simply wraps `html.escape`. This is equivalent to the old behavior except that single quotes are now escaped as `&#x27;` instead of `&#39;` and performance may be different.

tornado.escape.xhtml_unescape(value: str | bytes) → str

  Un-escapes an XML-escaped string.

  Equivalent to `html.unescape` except that this function always returns type `str` while `html.unescape` returns `bytes` if its input is `bytes`.

  Changed in version 6.4: Now simply wraps `html.unescape`. This changes behavior for some inputs as required by the HTML 5 specification https://html.spec.whatwg.org/multipage/parsing.html#numeric-character-reference-end-state

  Some invalid inputs such as surrogates now raise an error, and numeric references to certain ISO-8859-1 characters are now handled correctly.

tornado.escape.url_escape(value: str | bytes, plus: bool = True) → str

  Returns a URL-encoded version of the given value.

  Equivalent to either `urllib.parse.quote_plus` or `urllib.parse.quote` depending on the `plus` argument.

  If `plus` is true (the default), spaces will be represented as `+` and slashes will be represented as `%2F`. This is appropriate for query strings. If `plus` is false, spaces will be represented as `%20` and slashes are left as-is. This is appropriate for the path component of a URL. Note that the default of `plus=True` is effectively the reverse of Python’s urllib module.

  Added in version 3.1: The `plus` argument

tornado.escape.url_unescape(value: str | bytes, encoding: None, plus: bool = True) → bytes
tornado.escape.url_unescape(value: str | bytes, encoding: str = 'utf-8', plus: bool = True) → str

  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 and this function is equivalent to `urllib.parse.unquote_to_bytes` if `plus=False`. Otherwise, the result is a unicode string in the specified encoding and this function is equivalent to either `urllib.parse.unquote_plus` or `urllib.parse.unquote` except that this function also accepts `bytes` as input.

  If `plus` is true (the default), plus signs will be interpreted as spaces (literal plus signs must be represented as “%2B”). This is appropriate for query strings and form-encoded values but not for the path component of a URL. Note that this default is the reverse of Python’s urllib module.

  Added in version 3.1: The `plus` argument

tornado.escape.json_encode(value: Any) → str

  JSON-encodes the given Python object.

  Equivalent to `json.dumps` with the additional guarantee that the output will never contain the character sequence `</` which can be problematic when JSON is embedded in an HTML `<script>` tag.

tornado.escape.json_decode(value: str | bytes) → Any

  Returns Python objects for the given JSON string.

  Supports both `str` and `bytes` inputs. Equvalent to `json.loads`.

## Byte/unicode conversions

tornado.escape.utf8(value: bytes) → bytes
tornado.escape.utf8(value: str) → bytes
tornado.escape.utf8(value: None) → None

  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.

tornado.escape.to_unicode(value: str) → str
tornado.escape.to_unicode(value: bytes) → str
tornado.escape.to_unicode(value: None) → None

  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.

tornado.escape.native_str()

tornado.escape.to_basestring()

  Converts a byte or unicode string into type `str`. These functions were used to help transition from Python 2 to Python 3 but are now deprecated aliases for `to_unicode`.

tornado.escape.recursive_unicode(obj: Any) → Any

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

  Supports lists, tuples, and dictionaries.

## Miscellaneous functions

tornado.escape.linkify(text: str | bytes, shorten: bool = False, extra_params: str | Callable[[str], str] = '', require_protocol: bool = False, permitted_protocols: List[str] = ['http', 'https']) → str

  Converts plain text into HTML with links.

  For example: `linkify("Hello http://tornadoweb.org!")` would return `Hello <a href="http://tornadoweb.org">http://tornadoweb.org</a>!`

  Parameters:

  - `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("http://example.com"):
                return 'class="internal"'
            else:
                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 www.facebook.com 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`.

tornado.escape.squeeze(value: str) → str

  Replace all sequences of whitespace chars with a single space.