tornado.escape — 转义和字符串操作

用于 HTML、JSON、URL 等的转义/反转义方法。

还包括一些随着时间的推移而逐渐增加的其他杂项字符串操作函数。

此模块中的许多函数在标准库中都有近似等效项（区别主要与字节和 Unicode 字符串的处理方式有关，在 Python 2 中更为相关）。在新的代码中，建议在适用情况下使用标准库函数而不是此模块。有关详细信息，请参见每个函数的文档字符串。

转义函数

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

转义字符串使其在 HTML 或 XML 中有效。

转义字符 <, >, ", ' 和 &。在属性值中使用时，转义字符串必须用引号括起来。

等效于 html.escape，除了此函数始终返回类型 str，而 html.escape 如果其输入是 bytes，则返回 bytes。

在版本 3.2 中更改: 将单引号添加到转义字符列表中。

在版本 6.4 中更改: 现在只包装 html.escape。这等效于旧的行为，除了单引号现在被转义为 ' 而不是 '，并且性能可能有所不同。

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

反转义 XML 转义字符串。

等效于 html.unescape，除了此函数始终返回类型 str，而 html.unescape 如果其输入是 bytes，则返回 bytes。

在版本 6.4 中更改: 现在只包装 html.unescape。这会根据 HTML 5 规范 https://html.whatwg.com.cn/multipage/parsing.html#numeric-character-reference-end-state 改变某些输入的行为

一些无效输入（如代理）现在会引发错误，并且对某些 ISO-8859-1 字符的数字引用现在可以正确处理。

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

返回给定值的 URL 编码版本。

等效于 urllib.parse.quote_plus 或 urllib.parse.quote，具体取决于 plus 参数。

如果 plus 为真（默认值），空格将用 + 表示，斜杠将用 %2F 表示。这适用于查询字符串。如果 plus 为假，空格将用 %20 表示，斜杠保持原样。这适用于 URL 的路径部分。请注意，plus=True 的默认值实际上与 Python 的 urllib 模块相反。

在版本 3.1 中添加: plus 参数

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

将给定的值从 URL 解码。

参数可以是字节字符串或 unicode 字符串。

如果 encoding 为 None，则结果将是字节字符串，此函数等效于 urllib.parse.unquote_to_bytes 如果 plus=False。否则，结果是在指定编码中的 unicode 字符串，此函数等效于 urllib.parse.unquote_plus 或 urllib.parse.unquote，区别在于此函数还接受 bytes 作为输入。

如果 plus 为真（默认值），则加号将被解释为空格（文字加号必须表示为“%2B”）。这适用于查询字符串和表单编码的值，但不适用于 URL 的路径部分。注意，此默认值与 Python 的 urllib 模块相反。

在版本 3.1 中添加: plus 参数

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

将给定的 Python 对象 JSON 编码。

等效于 json.dumps，额外保证输出将永远不会包含字符序列 </，这在 JSON 嵌入 HTML <script> 标签中时可能会有问题。

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

返回给定 JSON 字符串的 Python 对象。

支持 str 和 bytes 输入。等效于 json.loads.

字节/unicode 转换

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

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

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

将字符串参数转换为字节字符串。

如果参数已经是字节字符串或 None，则直接返回。否则，它必须是 unicode 字符串，并被编码为 utf8。

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

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

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

将字符串参数转换为 unicode 字符串。

如果参数已经是 unicode 字符串或 None，则直接返回。否则，它必须是字节字符串，并被解码为 utf8。

tornado.escape.native_str()

tornado.escape.to_basestring()

将字节字符串或 unicode 字符串转换为类型 str。这些函数用于帮助从 Python 2 过渡到 Python 3，但现在已弃用，它们是 to_unicode 的别名。

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

遍历简单的 数据结构，将字节字符串转换为 unicode。

支持列表、元组和字典。

杂项函数

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

将纯文本转换为包含链接的 HTML。

例如：linkify("Hello http://tornadoweb.org!") 将返回 Hello <a href="http://tornadoweb.org">http://tornadoweb.org</a>!

参数

• shorten: 长 URL 将被缩短以显示。

• extra_params: 要包含在链接标签中的额外文本，或者一个可调用函数，它接受链接作为参数并返回额外文本，例如 linkify(text, extra_params='rel="nofollow" class="external"')，或者

  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: 仅将包含协议的 URL 链接化。如果为 False，则诸如 www.facebook.com 之类的 URL 也会被链接化。

• permitted_protocols: 应链接化的协议列表（或集合），例如 linkify(text, permitted_protocols=["http", "ftp", "mailto"])。将诸如 javascript 之类的协议包含在内非常不安全。

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

将所有空格字符序列替换为单个空格。