limits.toml

# The registry of limit codes (DESIGN.md section 9).
#
# Each table under `codes` is a limit that refuses an operation, and its key
# is the stable code that Python's `LimitError.code` carries. The fields are:
#
# - `message`: how a refusal with the code reads, in lowercase and without a
#   final period. A refusal that knows the amount and the limit appends them.
# - `unit`: what the limit counts, in the plural. A code without a unit
#   refuses without numbers.
# - `default`: the limit that applies unless `DocumentLimits` or the call's
#   `max_*` option sets another. A code without a default has no limit until
#   one is set.
# - `reached`: when the code is reached, as one Markdown sentence for the
#   documentation.
#
# Codes that pylopdf has keep its names and meanings. They come from
# pylopdf's src/pylopdf/_limits.py, rust/src/document/limits.rs, and the call
# sites of `limit_err` at 884af0dbf21973cfd434a9eca4e769de62fcc25c.
#
# tools/generate_limits.py writes the Rust enum, the Python mapping, and the
# table of the security guide from this file, and
# tests/test_limit_codes.py fails when they are stale. After a change, run:
#
#     uv run python tools/generate_limits.py

# Opening, and the structure of the document.

[codes.file_size]
message = "the input is too large"
unit = "bytes"
reached = "The input is larger than `DocumentLimits.max_file_size`."

[codes.page_count]
message = "the document has too many pages"
unit = "pages"
reached = "The document has more pages than `DocumentLimits.max_pages`."

[codes.object_count]
message = "the document has too many objects"
unit = "objects"
reached = "The document has more objects than `DocumentLimits.max_objects`."

[codes.object_depth]
message = "an object nests arrays and dictionaries too deeply"
unit = "levels"
reached = "An object nests arrays and dictionaries deeper than `DocumentLimits.max_object_depth`."

[codes.object_parse_size]
message = "an object is too large to parse"
unit = "bytes"
default = 268_435_456
reached = "The bytes of one object of the input, up to the next object or cross-reference section, exceed 256 MiB, which hayro-syntax would parse in one call that cannot be cancelled."

# Decoding streams.

[codes.decompressed_size]
message = "a stream decodes to too many bytes"
unit = "bytes"
reached = "A stream decodes to more than `DocumentLimits.max_decompressed_size`."

[codes.page_content_size]
message = "a page content stream decodes to too many bytes"
unit = "bytes"
reached = "A content stream of a page decodes to more than `DocumentLimits.max_page_content_size`."

[codes.total_decompressed_size]
message = "the streams of the operation decode to too many bytes"
unit = "bytes"
reached = "The streams that one operation decodes are larger together than `DocumentLimits.max_total_decompressed_size`."

[codes.decompression_unverifiable]
message = "the decoded size of a stream cannot be bounded"
reached = "A stream uses a filter whose decoded size cannot be bounded while a decoding limit applies."

[codes.stream_filter_count]
message = "a stream chains too many filters"
unit = "filters"
default = 16
reached = "A stream chains more filters than its limit."

# Interpretation.

[codes.interpretation_size]
message = "the data handed to the interpreter is too large"
unit = "bytes"
reached = "The PDF data handed to the interpreter is larger than `DocumentLimits.max_interpretation_size`."

[codes.interpretation_fuel]
message = "interpretation needs too much work"
unit = "units of fuel"
reached = "Interpretation uses more fuel than the operation allows."

# Content streams as operations.

[codes.content_operation_count]
message = "the content holds too many operations"
unit = "operations"
default = 1_048_576
reached = "Content holds more operations than the call's `max_operations`, or `Page.operations` reads more than 1,048,576."

[codes.content_stream_size]
message = "the page's content is too large"
unit = "bytes"
default = 67_108_864
reached = "A page's content streams, decoded and joined, are larger than 64 MiB when `Page.operations` reads them."

[codes.content_input_size]
message = "the content is too large to parse"
unit = "bytes"
default = 67_108_864
reached = "The content that `Operations.parse` reads is larger than the call's `max_size`, or the content that an assignment to `Page.operations` writes is larger than 64 MiB."

[codes.content_element_count]
message = "the page paints too many items"
unit = "elements"
default = 262_144
reached = "`Page.content` or `Page.paths` reads more glyphs, path and clip segments, dash lengths, and items than the call's `max_elements`, or `Pages.new_from_image` reads more than 4,096 frames or 256 million pixels of one image."

[codes.text_glyph_count]
message = "the page holds too many glyphs to read as text"
unit = "glyphs"
default = 262_144
reached = "`Page.text`, `Page.words`, `Page.layout`, or `Document.text` collects more glyphs of one page than the call's `max_glyphs`."

[codes.text_size]
message = "the text is too large"
unit = "bytes"
default = 67_108_864
reached = "The UTF-8 of a page's glyphs, of the text that `Page.text` or `Document.text` returns, or of the strings of the records that `Page.words` or `Page.layout` returns, is larger than the call's `max_size`."

[codes.search_input_size]
message = "the search text is too long"
unit = "bytes"
default = 4_096
reached = "The text that `Page.search` looks for is longer than 4,096 bytes in UTF-8."

[codes.search_hit_count]
message = "the search finds too many matches"
unit = "matches"
default = 4_096
reached = "`Page.search` finds more matches than the call's `max_hits`."

[codes.text_rule_count]
message = "the page has too many vector rules to read"
unit = "rules"
default = 4_096
reached = "Styled text or table extraction collects more than 4,096 vector rules, including inferred table dividers."

[codes.table_cell_count]
message = "the candidate table has too many cells"
unit = "cells"
default = 4_096
reached = "A candidate table needs more than 4,096 row-column slots."

[codes.table_span_candidate_count]
message = "the table needs too many cell span candidates"
unit = "candidates"
default = 65_536
reached = "Reconstructing merged cells in one table examines more than 65,536 candidate spans."

[codes.table_column_count]
message = "the text table has too many columns"
unit = "columns"
default = 32
reached = "Text table detection encounters a row with more than 32 separated columns."

[codes.ocr_layer_word_count]
message = "the OCR layer has too many words"
unit = "words"
default = 4_096
reached = "An invisible OCR layer has more than 4,096 words."

[codes.ocr_layer_text_size]
message = "the OCR layer text is too long"
unit = "bytes"
default = 1_048_576
reached = "An invisible OCR layer has more than 1 MiB of UTF-8 text."

[codes.ocr_layer_character_count]
message = "the OCR layer has too many distinct characters"
unit = "characters"
default = 65_534
reached = "An invisible OCR layer needs more than 65,534 distinct character IDs."

[codes.ocr_raster_size]
message = "the OCR raster is too large"
unit = "bytes"
default = 536_870_912
reached = "The raster expanded to RGBA for OCR exceeds 512 MiB."

[codes.ocr_detection_count]
message = "the OCR detector found too many text regions"
unit = "regions"
default = 4_096
reached = "OCR detection finds more than 4,096 candidate regions across its tiles before merging overlaps."

[codes.ocr_text_size]
message = "the recognized OCR text is too long"
unit = "bytes"
default = 33_554_432
reached = "OCR recognition produces more than 32 MiB of UTF-8 text before confidence filtering."

[codes.ocr_model_size]
message = "the OCR model set is too large"
unit = "bytes"
default = 67_108_864
reached = "The detector, recognizer, and dictionary that `OcrEngine` loads hold more bytes together than its `max_model_size`."

[codes.ocr_dictionary_entries]
message = "the OCR dictionary has too many entries"
unit = "entries"
default = 65_536
reached = "The dictionary that `OcrEngine` loads has more lines than the limit."

# The low-level object model.

[codes.stream_data_size]
message = "the stream is too large to read"
unit = "bytes"
default = 67_108_864
reached = "Reading a stream returns more bytes than the call's `max_size`."

[codes.object_value_depth]
message = "a written value nests arrays and dictionaries too deeply"
unit = "levels"
default = 32
reached = "A value written to the document nests arrays and dictionaries deeper than its limit."

# Output.

[codes.markdown_output_size]
message = "the Markdown is too large"
unit = "bytes"
default = 67_108_864
reached = "The UTF-8 of the Markdown that `Page.markdown`, `Document.markdown`, or `Table.markdown` returns is larger than the call's `max_size`."

[codes.export_output_size]
message = "the exported text is too large"
unit = "bytes"
default = 67_108_864
reached = "The UTF-8 of the element text that `Document.to_json` or `Document.to_chunks` exports is larger than the call's `max_size`."

[codes.pdf_output_size]
message = "the PDF output is too large"
unit = "bytes"
default = 536_870_912
reached = "Saving writes more bytes than the call's `max_size`."

[codes.pixmap_output_size]
message = "the encoded image is too large"
unit = "bytes"
default = 67_108_864
reached = "Encoding a pixmap writes more bytes than the call's `max_size`."

[codes.clip_page_side]
message = "the transformed page is too large for clipped rendering"
unit = "pixels"
default = 524_288
reached = "With `clip`, either side of the page after applying the render matrix exceeds 524,288 pixels."

[codes.svg_output_size]
message = "the SVG document is too large"
unit = "bytes"
default = 67_108_864
reached = "A page's SVG holds more UTF-8 bytes than the call's `max_size`."

[codes.render_output_size]
message = "the rendered images are too large"
unit = "bytes"
default = 536_870_912
reached = "The images that `doc.render` encodes write more bytes in all than the call's `max_size`."

# Input to the API.

[codes.password_input_size]
message = "the password is too long"
unit = "bytes"
default = 127
reached = "A password is longer in UTF-8 than PDF 2.0 allows."

[codes.embedded_file_size]
message = "the attachment is too large"
unit = "bytes"
default = 67_108_864
reached = "An attachment that `Attachment.read`, `Attachment.write`, or `Attachments.add` handles is larger than the call's `max_size`."

[codes.embedded_file_input_size]
message = "the attachment's text is too long"
unit = "bytes"
default = 1_048_576
reached = "An attachment's name, file name, or description is longer in UTF-8 than 1 MiB."

[codes.annotation_count]
message = "the page has too many annotations"
unit = "entries"
default = 4_096
reached = "A page's Annots array, including popups, links, and widgets, or an annotation removal batch has more than 4,096 entries."

[codes.annotation_text_size]
message = "the annotation text is too long"
unit = "bytes"
default = 1_048_576
reached = "An annotation read returns more than 1 MiB of text, or its encoded text exceeds 1 MiB, counted across the page for a listing."

[codes.annotation_dash_count]
message = "the annotation border has too many dash lengths"
unit = "lengths"
default = 32
reached = "An annotation border has more than 32 dash lengths."

[codes.annotation_input_size]
message = "the annotation text is too long"
unit = "bytes"
default = 1_048_576
reached = "The texts that one edit of an annotation writes, such as its contents, author, subject, and name, are longer than 1 MiB in UTF-8 together."

[codes.form_field_input_size]
message = "the form field value is too long"
unit = "bytes"
default = 1_048_576
reached = "The value that setting `Field.value` writes is longer than 1 MiB in UTF-8."

[codes.form_default_appearance_size]
message = "the form default appearance is too long"
unit = "bytes"
default = 4_096
reached = "A form widget's inherited default appearance is longer than 4,096 bytes."

[codes.form_field_parent_depth]
message = "the form field parent chain is too deep"
unit = "levels"
default = 64
reached = "A form widget's field parent chain contains more than 64 existing fields."

[codes.script_size]
message = "the form script is too long"
unit = "bytes"
default = 1_048_576
reached = "A form script, or the scripts of one field or widget together, are longer than 1 MiB in UTF-8, read or written."

[codes.text_edit_forms]
message = "the text edit reaches too many form XObjects"
unit = "drawings"
default = 4_096
reached = "`Page.replace_text` reaches Form XObjects nested deeper than 16, or more than 4,096 drawings of them."

[codes.image_input_size]
message = "the image data is too large"
unit = "bytes"
default = 268_435_456
reached = "The encoded image that `Pages.new_from_image` reads is larger than 256 MiB."

[codes.text_line_count]
message = "the text has too many lines"
unit = "lines"
default = 4_096
reached = "The text that a form field's appearance draws, or that `Canvas.text`, `Canvas.textbox`, or `Font.text_height` lays out, takes more than 4,096 lines."

[codes.text_input_size]
message = "the text is too large"
unit = "bytes"
default = 1_048_576
reached = "The text that `Canvas.text`, `Canvas.textbox`, or a `Font` measurement takes is larger than 1 MiB of UTF-8."

[codes.shaped_glyph_count]
message = "the text shapes into too many glyphs"
unit = "glyphs"
default = 1_048_576
reached = "Shaping one string in an embedded face takes more characters, or gives more glyphs, than the limit."

[codes.font_input_size]
message = "the font file is too large"
unit = "bytes"
default = 67_108_864
reached = "The font data that `Font.from_file` or `Font.from_bytes` loads is larger than 64 MiB."

[codes.named_destination_count]
message = "the named destinations are too many"
unit = "entries"
default = 65_536
reached = "The document's named destinations, its `/Names /Dests` tree and its legacy `/Dests` dictionary, hold more than 65,536 entries or tree nodes."

[codes.named_destination_edge_count]
message = "the named-destination tree has too many edges"
unit = "edges"
default = 131_072
reached = "The named-destination tree has more than 131,072 child edges."

[codes.named_destination_depth]
message = "the named-destination tree is too deep"
unit = "levels"
default = 32
reached = "The named-destination tree has more than 32 levels."

[codes.named_destination_text_size]
message = "the names of the named destinations are too long"
unit = "bytes"
default = 16_777_216
reached = "The names of the document's named destinations are longer than 16 MiB together."

[codes.toc_entry_count]
message = "the outline has too many items"
unit = "entries"
default = 65_536
reached = "The outline holds more than 65,536 items or 131,072 links between them, a list of items holds more than 65,536 children, or `doc.outline` is set to more than 65,536 entries."

[codes.toc_text_size]
message = "the outline text is too long"
unit = "bytes"
default = 16_777_216
reached = "The titles and target texts of the outline are longer than 16 MiB together, as the document encodes them or as they are returned."

[codes.toc_input_size]
message = "the outline input text is too long"
unit = "bytes"
default = 16_777_216
reached = "The titles and target texts that setting `doc.outline` or editing an item writes are longer than 16 MiB together in UTF-8 or as PDF text strings, or leave the outline's text above that."

[codes.structure_tree_count]
message = "the structure tree is too deep"
unit = "levels"
default = 256
reached = "A structural edit of pages walks a structure tree deeper than 256 levels including its root, a parent tree or ID tree deeper than 32 levels, or an acyclic reference chain longer than 32 references."

[codes.page_entry_count]
message = "the list of pages is too long"
unit = "entries"
reached = "A list of pages, such as the `pages` of `doc.render`, holds more entries than the larger of the page count and 4,096."

# The operation as a whole.

[codes.memory_size]
message = "the operation needs too much memory"
unit = "bytes"
reached = "The collections of one operation would hold more memory than `DocumentLimits.max_memory_size` allows, or the allocator refuses it."

[codes.deadline]
message = "the operation ran past its deadline"
unit = "milliseconds"
reached = "The operation runs past its deadline, which `DocumentLimits.max_duration` or the call sets."

[codes.cancelled]
message = "the operation was cancelled"
reached = "A cancellation token of the operation is cancelled."

[codes.annotation_quad_count]
message = "the annotation has too many quadrilaterals"
unit = "quadrilaterals"
default = 4_096
reached = "A text-markup annotation has more than 4,096 quadrilaterals."

[codes.annotation_point_count]
message = "the annotation has too many points"
unit = "points"
default = 65_536
reached = "An annotation's geometry, including generated squiggly points, has more than 65,536 points."

[codes.annotation_appearance_size]
message = "the annotation appearance is too large"
unit = "bytes"
default = 16_777_216
reached = "One generated annotation appearance contains more than 16 MiB of content."

[codes.annotation_synthesis_count]
message = "the render needs too many annotation appearances"
unit = "appearances"
default = 4_096
reached = "One render synthesizes more than 4,096 missing annotation appearances across the document."

[codes.annotation_synthesis_point_count]
message = "the render needs too many annotation path points"
unit = "points"
default = 262_144
reached = "Missing annotation appearances generated for one render contain more than 262,144 path points together."