Module page_labels 

Page labels (ISO 32000-1 §12.4.2): the printed page “numbers” a viewer shows and a user types to navigate — which are not the physical 0-based page indices. A document commonly numbers front matter with lowercase roman numerals (i, ii, iii …), the body with decimals (1, 2, 3 …), and an appendix with a prefix (A-1, A-2 …). The catalog’s /PageLabels entry is a number tree mapping the 0-based index of the first page of each labeling range to a label dictionary describing how that range is numbered.

A label dictionary (Table 159) carries:

• /S — the numbering style of the numeric portion: /D decimal, /R / /r upper/lower roman, /A / /a upper/lower letters (A…Z, AA…ZZ, AAA…). Absent /S means the label has no numeric portion (only the prefix).
• /P — a label prefix string prepended to the numeric portion.
• /St — the numeric value of the first page in the range (default 1, and ≥ 1); subsequent pages count up from it.

This module reads /PageLabels once into the sorted set of ranges and answers “what is page i’s label?” (PageLabels::label). It only reads the object graph; nothing here renders, and (like the other navigation readers) it runs only when explicitly called — never during open or rendering.

Structs

PageLabels

The document’s page labels, parsed from /PageLabels. Built only when the document declares at least one well-formed labeling range.

Enums

PageLabelStyle

The numbering style of a label’s numeric portion (ISO 32000-1 Table 159).

Functions

parse_page_labels

Parse the catalog’s /PageLabels number tree. Returns None when the document declares no page labels, or the tree yields no usable range.