justhtml

JustHTML uses a pipeline of transforms passed to the JustHTML constructor to modify the HTML tree in memory. Transforms can be categorized into built-in high-level transforms, core selector-based transforms, and advanced building blocks for custom pipelines.

Built-in Transforms

• Linkify(...): Converts URLs/emails in text nodes to <a> elements.
• CollapseWhitespace(...): Normalizes whitespace in text nodes.
• Sanitize(...): Runs a security-focused sanitization pipeline.
• PruneEmpty(...): Recursively removes empty elements.
• Stage([...]): Splits transforms into explicit passes.

Core Selector Transforms

These target specific elements using selectors:

• SetAttrs(selector, attributes=None, **attrs): Overwrites attributes.
• Drop(selector): Removes nodes and their children.
• Unwrap(selector): Removes the tag but keeps the children.
• Escape(selector): Turns tags into escaped text but keeps children.
• Empty(selector): Removes all children of the matching element.
• Edit(selector, func): Executes custom logic on matching nodes.

JustHTML uses a policy-driven sanitizer to render untrusted HTML safely. By default, it follows a conservative allowlist approach (DEFAULT_POLICY) that strips dangerous tags (like <script> or <style>) and removes event handlers (on*), srcdoc, and namespace-style attributes (containing :).

Key behaviors include:

• Tag Handling: Disallowed tags are removed, but their children may be kept depending on the policy.
• Content Stripping: Dangerous containers like <script> have their entire content dropped.
• Unicode Cleaning: Invisible Unicode characters used for obfuscation are stripped before sanitization.
• Foreign Namespaces: SVG and MathML are always dropped by the sanitizer, even if explicitly allowed in a custom policy.
• URL Safety: By default, a[href] allows common schemes, but img[src] only allows relative URLs to prevent remote resource loading unless configured otherwise.

JustHTML uses a transform pipeline that is applied once immediately after parsing. This replaces the html5lib filter pipeline used in Bleach. Use the following mapping to migrate your logic:

Example of composing transforms to linkify text and add rel="nofollow noopener" attributes:

from justhtml import JustHTML, Linkify, SetAttrs

doc = JustHTML(
    "<p>See example.com</p>",
    fragment=True,
    transforms=[
        Linkify(),
        SetAttrs("a", rel="nofollow noopener", target="_blank"),
    ],
)

# Still sanitized by default (construction time)
print(doc.to_html(pretty=False))

JustHTML supports both Unicode strings (str) and raw byte streams (bytes, bytearray, memoryview).

When you provide bytes, JustHTML automatically performs encoding sniffing and decoding to convert the input into a string before tokenization. The detected encoding is accessible via the doc.encoding attribute on the resulting document object.

Encoding Precedence Logic: JustHTML follows the standard HTML precedence for byte input:

1. Explicit override: The encoding= parameter passed to the constructor.
2. BOM: The Byte Order Mark.
3. Meta tags: <meta charset=...> or <meta http-equiv=... content=...> found in the initial bytes.
4. Fallback: Defaults to windows-1252 (cp1252) if no other information is found. Note that utf-7 is treated as unsafe and will trigger a fallback to windows-1252.

from justhtml import JustHTML
from pathlib import Path

data = Path("page.html").read_bytes()
doc = JustHTML(data)
print(doc.encoding)  # Access the detected encoding

JustHTML performs all operations (parsing, sanitizing, querying, and serializing) on a single DOM. This ensures that the behavior is consistent and easier to reason about, especially with untrusted input.

Key Behaviors:

• Safe-by-default: Sanitization occurs automatically during the process unless you explicitly disable it by passing sanitize=False.
• Sanitization Scope: The sanitizer emits HTML-only output. While SVG and MathML can be parsed when sanitization is disabled, sanitized output will drop foreign-namespace content to maintain a smaller, more secure model.
• Pipeline Integrity: Because everything happens on one DOM, you don't have to worry about the discrepancies that occur when passing data between different libraries (e.g., a parser and a separate sanitizer).

from justhtml import JustHTML

# By default, malicious tags like <script> and dangerous attributes are removed
doc = JustHTML("<p>Hello<script>alert(1)</script><a href='javascript:x'>link</a></p>", fragment=True)

print(doc.to_html(pretty=False))
# <p>Hello<a href='link'>link</a></p>
# Note: The exact output depends on the sanitizer's rules for the href attribute

JustHTML treats certain attributes (like href, src, srcset, action) as URL-like. Because these can trigger navigation or resource loading, they require explicit rules to be kept. Even if a tag and attribute are allowed in SanitizationPolicy, the URL-like attribute will be dropped unless a matching rule exists in UrlPolicy(allow_rules=...).

The URL cleaning lifecycle:

1. Tag Check: The tag must be in SanitizationPolicy.allowed_tags.
2. Attribute Check: The attribute must be in SanitizationPolicy.allowed_attributes.
3. Rule Match: An explicit matching rule must exist in UrlPolicy(allow_rules=...) for the (tag, attr) pair.
4. Filter (Optional): If UrlPolicy.url_filter is configured, it runs and can rewrite or drop the value.
5. Validation: The value is normalized and validated by the matching UrlRule (checking schemes, hosts, etc.).
6. Handling: If validation passes, the final action is applied based on UrlRule.handling or, if not set, UrlPolicy.default_handling.

The builder applies specific coercion rules to children to ensure valid HTML construction:

Children Coercion:

• Strings: Converted to text nodes.
• Iterables: Flattened into the parent node.
• None and False: Ignored (useful for conditional logic).
• Numbers: Rejected. Passing a number as a child will raise a TypeError.

Attribute Coercion:

• None: Represents a present boolean attribute (e.g., required).
• Other values: Converted to strings.

Example:

# Valid: string becomes text
element("p", "Hello") 

# Valid: None becomes boolean attribute
element("input", {"required": None}) # => <input required>

# Invalid: raises TypeError
element("p", 1)

from justhtml.dom.builder import element

# Boolean attribute example
print(element("input", {"maxlength": 10, "required": None}).to_html(pretty=False))
# => <input maxlength="10" required>

# This will raise TypeError
try:
    element("p", 1)
except TypeError:
    print("Numbers are not allowed as children")