Explanation

These pages explain how turbohtml is built and why it makes the choices it does: where the C core earns its keep, how the parser, tree model, query engines, serializers, and the free-threaded build fit together, and which trade-offs each one accepts. Start here for the why; the Reference has the what.

When to reach for turbohtml, and when not

turbohtml parses, queries, edits, and serializes HTML through a fast, typed, WHATWG-conformant core. Reach for it when you parse real-world markup and want the tree a browser builds (the html5lib suite passes, so malformed input recovers the way it does in a browser rather than the way libxml2 guesses); when speed matters (the Performance page has the figures); when you want a modern typed API with one name per concept, __match_args__ on every node, and full type stubs, alongside the free-threaded build; or when you escape, unescape, or tokenize on a hot path and want a drop-in several times faster than the standard library.

It is the wrong tool in a few honest cases:

• You need DTD or Schematron validation. turbohtml gives CSS selectors, the find filter grammar, an XPath 1.0 engine, an XSLT 1.0 processor, C14N, and XSD / RELAX NG validation, but not lxml’s DTD or Schematron validation. Code that leans on those should stay on lxml.

• You depend on `BeautifulSoup <https://www.crummy.com/software/BeautifulSoup/>`_’s ecosystem or its forgiving, duck-typed API. bs4 swaps parser backends, integrates with a long tail of tools, and accepts almost any shape; turbohtml is one conformant parser with a sealed, typed hierarchy. Code written to bs4’s contract needs the Migrating to turbohtml guide, not a drop-in import.

• You need a decades-hardened dependency. lxml and BeautifulSoup have been battle-tested for years across every platform and corner case; turbohtml is young.

• HTML is not your bottleneck. If parsing is a rounding error in your workload, the library you already use is fine. turbohtml’s advantage is speed and a typed API; if you need neither, switching costs more than it saves.

• Foundations
  • Why a C core
  • Matching the standard library
  • Free-threading
• Parse & DOM
  • Parsing: from bytes to a navigable tree
  • The strict XML parsing mode
  • The event-driven parse
  • Retargeting the parser
  • The streaming rewrite model
  • Source locations
  • The node and tree model
  • Traversal objects
  • Ranges and boundary points
  • Shadow DOM
  • Mutating the tree
• Encoding detection
  • Why a chardetng port
  • The sniff pipeline
  • A name is a label, not a codec
  • Detection is opt-in
• Query
  • Querying the tree
  • The cascade and computed style
• Layered sanitizing
• XSLT
  • One evaluator, not two
  • Patterns by membership
  • Stripping and imports
  • Where it stops
  • Conformance basis
• Extract
  • Structured-data extraction
  • Finding the main content
• Building a tree
  • A real tree, not text
  • The factory shape
• Serialize
  • Serialization and export
  • Canonical XML (c14n)
• Validate
  • Validation
  • Conformance