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

tornado.escape.xhtml_escape(value: Union[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.

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

tornado.escape.xhtml_unescape(value: Union[str, bytes]) → str

  Un-escapes an XML-escaped string.

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

  Returns a URL-encoded version of the given value.

  If `plus` is true (the default), spaces will be represented as “+” instead of “%20”. This is appropriate for query strings but not for the path component of a URL. Note that this default is the reverse of Python’s urllib module.

  New in version 3.1: The `plus` argument

tornado.escape.url_unescape(value: Union[str, bytes], encoding: None, plus: bool = True) → bytes
tornado.escape.url_unescape(value: Union[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. Otherwise, the result is a unicode string in the specified encoding.

  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.

  New in version 3.1: The `plus` argument

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

  JSON-encodes the given Python object.

tornado.escape.json_decode(value: Union[str, bytes]) → Any

  Returns Python objects for the given JSON string.

  Supports both `str` and `bytes` inputs.

## 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: Union[str, bytes], shorten: bool = False, extra_params: Union[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.