← Back to docs

Unsafe handling

The sanitizer can strip unsafe content, collect findings, or raise an error.

For tag/attribute allowlists and inline styles, see HTML Cleaning. For URL validation and URL handling, see URL Cleaning.

Choose the behavior with SanitizationPolicy(unsafe_handling=...).

Strip (default): unsafe_handling=”strip”

The sanitizer removes unsafe constructs and continues processing.

Use this mode when you want best-effort cleaned output and don’t need a list of what was removed.

Collect (optional): unsafe_handling=”collect”

If you want to keep sanitizing but also get a list of what was removed, set unsafe_handling="collect".

Collected findings are exposed as parse-style errors with category == "security" and are available in doc.errors after construction.

To include line/column information in collected findings, pass track_node_locations=True to JustHTML(...). Otherwise, locations may be missing. Location tracking adds some processing time and is disabled by default.

from justhtml import JustHTML, SanitizationPolicy, UrlPolicy

policy = SanitizationPolicy(
    allowed_tags=["p"],
    allowed_attributes={"*": []},
    url_policy=UrlPolicy(allow_rules={}),
    unsafe_handling="collect",
)

doc = JustHTML(
    "<p>ok</p><script>alert(1)</script>",
    fragment=True,
    track_node_locations=True,
    policy=policy,
)
for e in doc.errors:
    if e.category == "security":
        print(e.message)

Unsafe tag 'script' (dropped content)

Raise (optional): unsafe_handling=”raise”

If you want to treat unsafe HTML as an error instead of stripping it, set unsafe_handling="raise".

In this mode, the sanitizer raises UnsafeHtmlError at the first unsafe construct it encounters.

from justhtml import JustHTML, SanitizationPolicy, UnsafeHtmlError, UrlPolicy

doc = JustHTML("<p>ok</p><script>alert(1)</script>", fragment=True)

policy = SanitizationPolicy(
    allowed_tags=["p"],
    allowed_attributes={"*": []},
    url_policy=UrlPolicy(allow_rules={}),
    unsafe_handling="raise",
)

try:
    _ = JustHTML("<p>ok</p><script>alert(1)</script>", fragment=True, policy=policy)
except UnsafeHtmlError as e:
    print(e)

Unsafe tag 'script' (dropped content)