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[source]¶ 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[source]¶ Un-escapes an XML-escaped string.
-
tornado.escape.
url_escape
(value: Union[str, bytes], plus: bool = True) → str[source]¶ 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: Optional[str] = 'utf-8', plus: bool = True) → Union[str, bytes][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.
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
Byte/unicode conversions¶
-
tornado.escape.
utf8
(value: Union[None, str, bytes]) → Optional[bytes][source]¶ 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: Union[None, str, bytes]) → Optional[str][source]¶ 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 forto_unicode
.
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[source]¶ Converts plain text into HTML with links.
For example:
linkify("Hello http://tornadoweb.org!")
would returnHello <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 asjavascript
.