Module structure 

Logical structure tree / Tagged PDF (ISO 32000-1 §14.7–14.8). A tagged PDF carries, alongside its page content, a tree of structure elements that describes the document’s logical organization — its headings, paragraphs, lists, tables, figures and their reading order — independent of how that content happens to be laid out on the page. This is what makes a PDF accessible (a screen reader walks the structure tree, not the page) and what lets a consumer recover semantic structure rather than a bag of glyphs.

The catalog’s /StructTreeRoot roots the tree (§14.7.2). Each node is a structure element dictionary (/Type /StructElem) carrying:

• /S — the structure type (the role): a standard type such as P, H1, Table, Figure, or a producer-defined type mapped to a standard one by the root’s /RoleMap.
• /K — the element’s kids, a single value or an array mixing: nested structure elements (by reference or inline dict), bare integers (marked-content identifiers — MCIDs — pointing into a page’s content stream), marked-content reference dicts (/Type /MCR), and object reference dicts (/Type /OBJR, e.g. for an annotation).
• /Pg — the page whose content stream the element’s MCIDs index; inherited by descendants that don’t carry their own.
• /Alt, /ActualText, /E, /T, /Lang — accessibility text and metadata: an alternate description, the exact replacement text, an abbreviation expansion, a title, and a language tag.

This module reads /StructTreeRoot once into a navigable StructTree. Like the other document readers it only walks the object graph — nothing here renders — and it runs only when explicitly called, never during open or rendering. Every descent is bounded (depth cap, a per-reference visited set seeded with the tree-root reference, a shared node/entry budget, role-map resolution depth, and per-string length caps) so a malformed or adversarial tree cannot hang, recurse without bound, or exhaust memory.

Structs

StructElem

One structure element (/Type /StructElem): a node of the logical tree.

StructTree

The document’s logical structure tree (/StructTreeRoot). Present only when the catalog declares one.

Enums

StructKid

A kid of a structure element: a nested element, a marked-content sequence in a page’s content stream, or a whole referenced object (/OBJR).

StructRole

A standard structure type (ISO 32000-1 §14.8.4), the role of a structure element after resolving its /S through the document’s /RoleMap. A type outside the standard set (and not mapped onto it) is StructRole::Other.

Functions

is_tagged

Whether the document declares Tagged-PDF conformance via the catalog’s /MarkInfo dictionary (/Marked true). Independent of whether a /StructTreeRoot is actually present.

parse_struct_tree

Parse the document’s logical structure tree from the catalog’s /StructTreeRoot. Returns None when the document declares no structure tree (i.e. is not tagged in the structural sense).