Page Labels Reference

See also

Working with Page Labels

class pdfnaut.objects.page_labels.PageLabelRange

Bases: PdfDictionary

A page labelling range describing how page labels are displayed for a consecutive range of pages. See ISO 32000-2:2020 § 12.4.2 “Page labels and indices” for details.

__init__(style=None, prefix=None, start=1)

get_label(index: int) → str

Returns the page label, within this range, corresponding to relative page index index.

prefix: str | None

The label prefix for page labels in this range.

start: int

The integer value of the numeric portion for the first page label in the range. This value shall be greater than or equal to 1.

style: PageNumberingStyle | str | None

The numbering style to be used for the numeric portion of each page label.

If none, the numeric portion shall be omitted.

class pdfnaut.objects.page_labels.PageLabelTree

Bases: NumberTree[PageLabelRange]

A page label tree for a document.

Initializes a page label tree.

Parameters:

• data – The PdfDictionary object defining the page label tree.

• pdf – The PdfDocument object associated with the page label tree.

__init__(data: PdfDictionary, *, pdf: PdfDocument) → None

Initializes a page label tree.

Parameters:

• data – The PdfDictionary object defining the page label tree.

• pdf – The PdfDocument object associated with the page label tree.

get_all() → Generator[str]

Yields a list of all page labels in the document.

get_all() returns a page label for each of the document’s pages. If the document does not specify page labels, get_all() will return page labels in decimal Arabic numbering (1, 2, 3, 4, 5, …).

get_label_for(page: int) → str

Returns the page label corresponding to zero-based page index index.

Consistent with get_all(), get_label_for() will return the page label in decimal Arabic numbering if the document specifies no page labels.

Raises:

• IndexError – the page index is out of bounds.

• ValueError – the document has page labels but does not define them for all pages in the document, as required by the PDF spec.

get_labels_in_range(start: int) → Generator[str]

Yields a list of all page labels within the page labelling range defined at start.

Raises ValueError if no page labelling range was defined at start.

get_ranges() → Generator[tuple[PageLabelRange, int, int]]

Yields a list of all page label ranges in the document.

Yielded are tuples of (range, start, end) which, in order, include the page labelling range, the start page index (inclusive), and the end page index (exclusive).

new() → None

Clears the current page label tree.

class pdfnaut.objects.page_labels.PageNumberingStyle

Bases: str, Enum

The page numbering style.

DECIMAL_ARABIC = 'D'

Decimal Arabic numerals (1, 2, 3, 4, 5, …).

LOWERCASE_LETTER = 'a'

Lowercase letters / bijective base-26 (a, b, c, …, z, aa, ab, …).

LOWERCASE_ROMAN = 'r'

Lowercase Roman numerals (i, ii, iii, iv, v, …).

UPPERCASE_LETTER = 'A'

Uppercase letters / bijective base-26 (A, B, C, …, Z, AA, AB, …).

UPPERCASE_ROMAN = 'R'

Uppercase Roman numerals (I, II, III, IV, V, …).

__new__(value)