html-sanitizer 2.4.4

目标

• 使用非常受限的允许标签和属性集清理HTML片段。

• 将一些标签（例如<span style="...">、<b>和<i>）转换为<strong>或<em>（但永远不两者都是）。

• 绝对不允许所有内联样式。

• 通过删除重复的换行符、空段落和其他空元素来规范化空白。

• 合并相邻的同类型标签（例如几个连续的 <strong> 或 <h3> 标签）。

• 自动删除 <li> 标签内的冗余列表标记。

• 清理一些不美观的地方，例如段落中的段落或列表元素等。

• 规范化 Unicode。

用法

>>> from html_sanitizer import Sanitizer
>>> sanitizer = Sanitizer()  # default configuration
>>> sanitizer.sanitize('<span style="font-weight:bold">some text</span>')
'<strong>some text</strong>'

设置

• 将加粗跨度或 b 标签转换为 strong 标签，斜体跨度或 i 标签转换为 em 标签（如果允许使用 strong 和 em）

• 内联样式和脚本始终会被删除。

• 使用 div 元素包裹解析器中的 HTML 片段，因此不允许 div 标签。

默认设置是

DEFAULT_SETTINGS = {
    "tags": {
        "a", "h1", "h2", "h3", "strong", "em", "p", "ul", "ol",
        "li", "br", "sub", "sup", "hr",
    },
    "attributes": {"a": ("href", "name", "target", "title", "id", "rel")},
    "empty": {"hr", "a", "br"},
    "separate": {"a", "p", "li"},
    "whitespace": {"br"},
    "keep_typographic_whitespace": False,
    "add_nofollow": False,
    "autolink": False,
    "sanitize_href": sanitize_href,
    "element_preprocessors": [
        # convert span elements into em/strong if a matching style rule
        # has been found. strong has precedence, strong & em at the same
        # time is not supported
        bold_span_to_strong,
        italic_span_to_em,
        tag_replacer("b", "strong"),
        tag_replacer("i", "em"),
        tag_replacer("form", "p"),
        target_blank_noopener,
    ],
    "element_postprocessors": [],
    "is_mergeable": lambda e1, e2: True,
}

键的意义如下

• tags：允许的标签的 set()。

• attributes：将标签映射到其允许的属性的 dict()。

• empty：允许为空的标签。默认情况下，空标签（不包含文本或仅包含空格）会被删除。

• separate：如果作为兄弟出现则不允许合并的标签。默认情况下，相同类型的标签会被合并。

• whitespace：被视为空白并从其他标签内容的首尾删除的标签。

• keep_typographic_whitespace：保留排版使用的空格字符，如非断行空格等。

• add_nofollow：是否向所有链接添加 rel="nofollow"。

• autolink：启用 lxml 的 autolinker。可以是布尔值或字典；字典作为 autolink 的关键字参数传递。

• sanitize_href：一个可调用对象，它获取锚点的 href 值并返回一个净化版本。默认实现检查链接是否以一些允许的前缀开始，如果不是，则返回单个哈希（#）。

• element_preprocessors 和 element_postprocessors：在树中的所有元素上调用的附加过滤器。树以反向深度优先顺序处理。在特定情况下，元素可能被处理多次（在代码中搜索 backlog.append）。在空白规范化之前运行预处理器，在之后运行后处理器。

• is_mergeable：相邻的元素默认合并，但不保留 separate。此可调用对象可用于防止相邻元素合并，例如当它们的类不匹配时（lambda e1, e2: e1.get('class') == e2.get('class')）

可以在初始化净化器实例时部分指定设置，但仍然会检查一致性。例如，不允许在 empty 中有不在 tags 中的标签，即允许为空但同时又不允许的标签。当 Sanitizer 构造函数检测到不一致性时，会引发 TypeError 异常。

更受限制的配置示例可能如下

>>> from html_sanitizer import Sanitizer
>>> sanitizer = Sanitizer({
...     'tags': ('h1', 'h2', 'p'),
...     'attributes': {},
...     'empty': set(),
...     'separate': set(),
... })

对允许的标签集（例如不允许图片）的限制原因在 设计决策 部分中有记录，这部分可以在 django-content-editor 的文档中找到。

Django

HTML净化器不依赖于 Django，但它附带了一个模块，该模块使使用 Django 设置配置净化器变得更容易。用法如下

>>> from html_sanitizer.django import get_sanitizer
>>> sanitizer = get_sanitizer([name=...])

可以配置不同的消毒剂。默认配置被恰当地命名为'default'。以下是一些示例设置

HTML_SANITIZERS = {
    'default': {
      'tags': ...,
    },
    ...
}

'default'配置是特殊的：如果它没有明确定义，则使用上述默认配置。不存在的配置将导致ImproperlyConfigured异常。

get_sanitizer函数缓存消毒剂实例，所以您可以随时调用它。

安全问题

请直接向我报告安全问题：mk@feinheit.ch。