← Back to docs

API Reference

Complete documentation for the JustHTML public API.

JustHTML

The main parser class.

from justhtml import JustHTML

Constructor

JustHTML(html, *, sanitize=True, safe=None, policy=None, collect_errors=False, track_node_locations=False, debug=False, encoding=None, fragment=False, fragment_context=None, iframe_srcdoc=False, strict=False, tokenizer_opts=None, tree_builder=None, transforms=None)

Properties

Methods

to_text()

Return the document’s concatenated text.

doc = JustHTML("<p>Hello <b>world</b></p>")
doc.to_text()  # => Hello world

Parameters:

• separator (default: " "): join string between text nodes
• strip (default: True): strip each text node and drop empties

Sanitization happens at construction time. Use JustHTML(..., sanitize=False) for trusted input or JustHTML(..., policy=...) to customize the policy.

to_markdown(html_passthrough=False)

Return a pragmatic subset of GitHub Flavored Markdown (GFM).

Tables (<table>) and images (<img>) are preserved as raw HTML. Raw HTML tags like <script>, <style>, and <textarea> are dropped by default; pass html_passthrough=True to preserve them (including their contents).

doc = JustHTML("<h1>Title</h1><p>Hello <b>world</b></p>")
doc.to_markdown()  # => # Title
# =>
# => Hello **world**
doc.to_markdown(html_passthrough=True)

Sanitization happens at construction time. Use JustHTML(..., sanitize=False) for trusted input or JustHTML(..., policy=...) to customize the policy.

query(selector)

Find all nodes matching a CSS selector.

doc.query("div.container > p")  # Returns list of matching nodes
doc.query(":comment")           # Returns comment nodes

Node

Base type for all DOM nodes.

Node types:

• Document: the root for full-document parses
• DocumentFragment: the root for fragment parses
• Element: normal HTML/SVG/MathML elements
• Text: text nodes (#text)
• Comment: comment nodes (#comment)
• Template: <template> elements with template_content

Template nodes expose a template_content document fragment (HTML namespace only), which holds the template’s children.

Recommended mutation path

Direct DOM edits are supported, but transforms are the preferred way to make changes because they preserve ordering semantics and make sanitization explicit. See Transforms for the recommended workflow. If you mutate the DOM after construction, sanitization has already happened; re-sanitize by using sanitize_dom(...) or rebuild the document with a Sanitize(...) transform in the construction pipeline.

Properties

Methods

to_html(indent=0, indent_size=2, pretty=True)

Serialize the node to HTML string.

node.to_html()                      # Pretty-printed HTML
node.to_html(pretty=False)          # Compact HTML
node.to_html(indent_size=4)         # 4-space indent
node.to_html(indent=2, indent_size=4)  # Start with 2 indents

# Safety happens at construction time:
# - default: JustHTML(..., sanitize=True)
# - raw/trusted: JustHTML(..., sanitize=False)
# - custom policy: JustHTML(..., policy=policy)

query(selector)

Find descendants matching a CSS selector.

div.query("p.intro")  # Search within this node

to_text()

Return the node’s concatenated text.

node.to_text()

Text extraction is safe-by-default when you build documents with JustHTML(..., sanitize=True) (the default). Use sanitize=False at construction for trusted input.

to_markdown(html_passthrough=False)

Return a pragmatic subset of GitHub Flavored Markdown (GFM) for this subtree.

node.to_markdown()
node.to_markdown(html_passthrough=True)

Markdown output is safe-by-default when you build documents with JustHTML(..., sanitize=True) (the default). Use sanitize=False at construction for trusted input.

append_child(node)

Append a child node to this node.

insert_before(node, reference_node)

Insert node before reference_node (or append if reference_node is None).

remove_child(node)

Remove a direct child node.

replace_child(new_node, old_node)

Replace a direct child node with a new node.

clone_node(deep=False, override_attrs=None)

Clone this node. If deep=True, children are cloned recursively.

has_child_nodes()

Return True if this node has children.

Sanitization

JustHTML includes a built-in, policy-driven HTML sanitizer.

Guides:

• Sanitization overview
• HTML Cleaning
• URL Cleaning
• Unsafe Handling

from justhtml import DEFAULT_POLICY, SanitizationPolicy, UrlPolicy, UrlProxy, UrlRule, sanitize_dom

Sanitizing output vs sanitizing the DOM

• Construction sanitization is the default: JustHTML(..., sanitize=True) sanitizes once, right after parsing.
• If you want to sanitize after other transforms or direct DOM edits, add Sanitize(...) to your transform pipeline.
  • If you care about explicit transform passes, group transforms using Stage([...]).
  • For details on how Sanitize(...) works (and why it’s reviewable), see Transforms.

from justhtml import JustHTML, Sanitize

doc = JustHTML(user_html, fragment=True, transforms=[Sanitize()])
clean_root = doc.root

sanitize_dom(node, *, policy=None, errors=None)

Re-sanitize a DOM tree after direct edits. For document roots (#document or #document-fragment), this mutates the tree in place. For other nodes, the node is sanitized as if it were the only child of a document fragment; the returned node may need to be reattached by the caller.

from justhtml import sanitize_dom

sanitize_dom(doc.root)  # In-place for document roots

DEFAULT_POLICY

Conservative built-in policy used for safe-by-default sanitization.

DEFAULT_DOCUMENT_POLICY

Conservative built-in policy used when sanitizing full documents (preserves <html>, <head>, and <body> wrappers).

SanitizationPolicy

Defines allowlists for tags and attributes, URL validation rules, and optional inline-style allowlisting.

Notable options:

• unsafe_handling: “strip” (default), “raise”, or “collect”
• disallowed_tag_handling: “unwrap” (default), “escape”, or “drop”
• url_policy: controls URL validation and URL handling (“allow”, “strip”, or “proxy”)

UrlPolicy

Wraps URL rules and controls what happens to URL-valued attributes.

UrlPolicy(
    default_handling="strip",  # or "allow" / "proxy"
    default_allow_relative=True,
    allow_rules={},
    url_filter=None,
    proxy=None,
)

UrlProxy

Proxy rewrite configuration used when default_handling="proxy".

UrlProxy(
    url="/proxy",
    param="url",
)

UrlRule

Controls how URL-valued attributes like a[href] and img[src] are validated.

UrlRule(
    allow_fragment=True,
    resolve_protocol_relative="https",
    allowed_schemes=set(),
    allowed_hosts=None,
    proxy=None,
)

stream

Memory-efficient streaming parser.

from justhtml import stream

for event, data in stream(html):
    ...

stream() accepts the same input types as JustHTML. If you pass bytes, it will decode using HTML encoding sniffing. To override the encoding for byte input, pass encoding=....

Events

FragmentContext

Specifies the context element for fragment parsing. See Fragment Parsing for detailed usage.

from justhtml.context import FragmentContext

Constructor

FragmentContext(tag_name, namespace=None)

Example

from justhtml import JustHTML
from justhtml.context import FragmentContext

# Parse table rows in correct context
ctx = FragmentContext("tbody")
doc = JustHTML("<tr><td>cell</td></tr>", fragment_context=ctx)

ParseError

Represents a parse error with location information.

from justhtml import ParseError

Properties

Methods

as_exception()

Convert to a SyntaxError with source highlighting (Python 3.11+).

error.as_exception()  # Returns SyntaxError

StrictModeError

Exception raised when parsing with strict=True.

from justhtml import StrictModeError

Inherits from SyntaxError, so it displays source location in tracebacks.

Standalone Functions

query(node, selector)

Query a node without using the method syntax.

from justhtml import query
results = query(doc.root, "div.main")

matches(node, selector)

Check if a node matches a selector.

from justhtml import matches
if matches(node, "div.active"):
    ...

to_html(node, indent=0, indent_size=2, pretty=True)

Serialize a node to HTML.

from justhtml import to_html
html_string = to_html(node)

SelectorError

Exception raised for invalid CSS selectors.

from justhtml import SelectorError

try:
    doc.query("div[invalid")
except SelectorError as e:
    print(e)