Source code

Download source archive ↓

src/pypdf/_configuration.py

1"""Configuration value handling."""
2import dataclasses
3import functools
4import shutil
5from collections.abc import Iterator
6from contextlib import contextmanager
7from contextvars import ContextVar
8from typing import Any, Literal
9
10
11@functools.cache
12def _determine_jbig2dec_binary() -> str | None:
13    """
14    Small utility function to determine the `jbig2dec` binary path only once.
15
16    Returns:
17        The corresponding binary path if available.
18    """
19    return shutil.which("jbig2dec")
20
21
22@dataclasses.dataclass(frozen=True)
23class Configuration:
24    """
25    Configuration used while processing PDF files.
26
27    These limits mostly protect against excessive resource consumption caused by malformed or malicious PDF files.
28
29    .. note::
30
31        Avoid relying on specific implementation details of this class. The main public API consists of the values
32        being considered read-only for each instance with the overwrite method to create a new instance with the
33        specified values changed.
34    """
35
36    maximum_declared_stream_length: int = 75_000_000
37    """The maximum allowed declared ``/Length`` value for streams."""
38    array_based_stream_maximum_output_length: int = 75_000_000
39    """The maximum allowed output length for array-based streams."""
40    array_maximum_element_count: int = 100_000
41    """The maximum allowed number of elements inside an array."""
42    dictionary_maximum_element_count: int = 100_000
43    """The maximum allowed number of key-value pairs inside a dictionary."""
44
45    jbig2_maximum_output_length: int = 75_000_000
46    """
47    The maximum allowed number of uncompressed bytes during decompression when using the ``/JBIG2Decode`` filter
48    (JBIG2 images).
49    """
50    lzw_maximum_output_length: int = 75_000_000
51    """
52    The maximum allowed number of uncompressed bytes during decompression when using the ``/LZWDecode`` filter
53    (LZW compression).
54    """
55    run_length_maximum_output_length: int = 75_000_000
56    """
57    The maximum allowed number of uncompressed bytes during decompression when using the ``/RunLengthDecode`` filter
58    (run-length compression).
59    """
60    zlib_maximum_output_length: int = 75_000_000
61    """
62    The maximum allowed number of uncompressed bytes during decompression when using the ``/FlateDecode`` filter
63    (zlib compression).
64    """
65    zlib_maximum_recovery_input_length: int = 5_000_000
66    """
67    The maximum allowed number of bytes to attempt the recovery with when using the ``/FlateDecode`` filter
68    (zlib compression).
69    """
70    brotli_maximum_output_length: int = 75_000_000
71    """
72    The maximum allowed number of uncompressed bytes during decompression when using the ``/BrotliDecode`` filter
73    (Brotli compression).
74    """
75
76    flate_maximum_columns: int = 250_000
77    """The maximum allowed number of columns when using the ``/FlateDecode`` filter."""
78    flate_maximum_row_length: int = 4_000_000
79    """The maximum allowed row length when using the ``/FlateDecode`` filter."""
80
81    image_maximum_buffer_size: int = 75_000_000
82    """The maximum allowed number of bytes to allocate for images."""
83
84    stream_filters_maximum_length: int = 16
85    """The maximum allowed number of filters per stream."""
86    stream_decoding_work_maximum_length: int = 300_000_000
87    """The maximum allowed accumulated decoding work in bytes per stream."""
88    stream_parsing_work_maximum_count: int = 2_000_000
89    """
90    The maximum parsing budget for a content stream, including operands, operators, and elements in
91    nested arrays and dictionaries.
92    """
93
94    xmp_maximum_input_length: int = 5_000_000
95    """The maximum allowed actual decompressed stream length in bytes for XMP data."""
96    xmp_maximum_element_count: int = 100_000
97    """The maximum allowed number of elements for XMP data."""
98
99    outline_maximum_entries: int = 100_000
100    """The maximum allowed number of outline entries."""
101    outline_maximum_depth: int = 100
102    """The maximum allowed depth for outline entries."""
103
104    page_tree_maximum_entries: int = 100_000
105    """The maximum allowed number of entries in the page tree."""
106    page_tree_maximum_depth: int = 100
107    """The maximum allowed depth of the page tree."""
108    page_tree_maximum_page_entries: int = 2_000_000
109    """
110    The maximum allowed total number of page dictionary entries copied while flattening the page tree.
111    A page referenced multiple times is copied once per reference.
112    """
113
114    form_fields_maximum_entries: int = 100_000
115    """The maximum allowed number of form fields."""
116    form_fields_maximum_depth: int = 100
117    """The maximum allowed depth for form fields."""
118
119    named_destinations_maximum_entries: int = 100_000
120    """The maximum allowed number of named destination name tree nodes."""
121    named_destinations_maximum_depth: int = 100
122    """The maximum allowed depth for a named destination name tree."""
123
124    xform_maximum_invocations_per_extraction: int = 5_000
125    """The maximum allowed number of ``/XObject`` forms per page during text extraction."""
126
127    xfa_decoding_work_maximum_length: int = 300_000_000
128    """The maximum allowed accumulated decoding work in bytes for the XFA form."""
129
130    jbig2dec_binary: str | None = dataclasses.field(default_factory=_determine_jbig2dec_binary)
131    """
132    The location of the ``jbig2dec`` binary.
133
134    This either is a string holding the path to the binary, or ``None`` if the binary could not be found
135    or the binary should not be called.
136    """
137
138    page_merge_box: Literal["cropbox", "trimbox"] = "cropbox"  # pypdf <= 3.4.0 used "trimbox"
139    """The page box to use during merge."""
140
141    disable_legacy_handling: bool = False
142    """
143    Temporary configuration value for applications which do not rely on old overwrites and thus
144    are able to skip legacy handling.
145
146    This disables looking for changes of the old constants during each initialization of the reader
147    class. Please note that while this reduces the required overhead, it will disable all related
148    deprecation warnings/errors. Setting this flag while legacy constants are intentionally being
149    modified is unsupported/incorrect.
150
151    After the deprecation period, this configuration value will be removed with its own deprecation
152    period as well.
153    """
154
155    def with_overwrites(self, **kwargs: Any) -> "Configuration":
156        """
157        Creates a new configuration with the specified values overwritten.
158
159        Args:
160            **kwargs: Configuration field names and their new values.
161
162        Returns:
163            A new configuration with the specified values overwritten.
164        """
165        return dataclasses.replace(self, **kwargs)
166
167
168# A default configuration without any value changes.
169DEFAULT_CONFIGURATION = Configuration()
170
171# The current configuration.
172CURRENT_CONFIGURATION: ContextVar[Configuration] = ContextVar(
173    "pypdf_configuration",
174    default=DEFAULT_CONFIGURATION,
175)
176
177
178def get_configuration() -> Configuration:
179    """
180    Get the current configuration.
181
182    Returns:
183        The current configuration.
184    """
185    return CURRENT_CONFIGURATION.get()
186
187
188def _build_configuration(
189    configuration: Configuration | None,
190    overwrites: dict[str, Any],
191) -> Configuration:
192    """
193    Utility function to build a new configuration from the given values.
194
195    Args:
196        configuration: A possible explicit configuration to use instead of the current configuration.
197        overwrites: Entries to overwrite.
198
199    Returns:
200        The generated configuration.
201    """
202    base = configuration if configuration is not None else get_configuration()
203    # TODO: Remove when releasing 8.0.0
204    # if "disable_legacy_handling" in overwrites:
205    #     deprecate_no_replacement("disable_legacy_handling", "9.0.0")
206    return base.with_overwrites(**overwrites)
207
208
209def overwrite_configuration(
210    configuration: Configuration | None = None,
211    **overwrites: Any,
212) -> Configuration:
213    """
214    Overwrite the configuration for the current execution context.
215
216    Args:
217        configuration: A direct configuration instance to use.
218        **overwrites: Configuration parameters to overwrite in the current or given configuration.
219
220    Returns:
221        The new configuration.
222    """
223    new_configuration = _build_configuration(configuration, overwrites)
224    CURRENT_CONFIGURATION.set(new_configuration)
225    return new_configuration
226
227
228@contextmanager
229def apply_configuration(
230    configuration: Configuration | None = None,
231    **overwrites: Any,
232) -> Iterator[Configuration]:
233    """
234    Temporarily overwrite the configuration.
235
236    Args:
237        configuration: A direct configuration instance to use.
238        **overwrites: Configuration parameters to overwrite in the current or given configuration.
239
240    Returns:
241        The new configuration.
242    """
243    new_configuration = _build_configuration(configuration, overwrites)
244    token = CURRENT_CONFIGURATION.set(new_configuration)
245    try:
246        yield new_configuration
247    finally:
248        CURRENT_CONFIGURATION.reset(token)
249
250
251# Map the new field names to their legacy names.
252LEGACY_NAME_MAPPING = {
253    "maximum_declared_stream_length": "MAX_DECLARED_STREAM_LENGTH",
254    "array_based_stream_maximum_output_length": "MAX_ARRAY_BASED_STREAM_OUTPUT_LENGTH",
255    "jbig2_maximum_output_length": "JBIG2_MAX_OUTPUT_LENGTH",
256    "lzw_maximum_output_length": "LZW_MAX_OUTPUT_LENGTH",
257    "run_length_maximum_output_length": "RUN_LENGTH_MAX_OUTPUT_LENGTH",
258    "zlib_maximum_output_length": "ZLIB_MAX_OUTPUT_LENGTH",
259    "zlib_maximum_recovery_input_length": "ZLIB_MAX_RECOVERY_INPUT_LENGTH",
260    "flate_maximum_columns": "FLATE_MAX_COLUMNS",
261    "flate_maximum_row_length": "FLATE_MAX_ROW_LENGTH",
262    "image_maximum_buffer_size": "FLATE_MAX_BUFFER_SIZE",
263    "xmp_maximum_input_length": "XMP_MAX_INPUT_LENGTH",
264    "xmp_maximum_element_count": "XMP_MAX_ELEMENT_COUNT",
265    "jbig2dec_binary": "JBIG2DEC_BINARY",
266    "page_merge_box": "MERGE_CROP_BOX",
267}
268
269
270def apply_legacy_configuration() -> Configuration:
271    """
272    Overwrite the current configuration with the legacy configuration if it has been changed.
273
274    Returns:
275        The new configuration which has been applied.
276    """
277    configuration = get_configuration()
278    if configuration.disable_legacy_handling:
279        return configuration
280
281    from pypdf._page import MERGE_CROP_BOX  # noqa: PLC0415
282    from pypdf.filters import (  # noqa: PLC0415
283        FLATE_MAX_BUFFER_SIZE,
284        FLATE_MAX_COLUMNS,
285        FLATE_MAX_ROW_LENGTH,
286        JBIG2_MAX_OUTPUT_LENGTH,
287        JBIG2DEC_BINARY,
288        LZW_MAX_OUTPUT_LENGTH,
289        MAX_ARRAY_BASED_STREAM_OUTPUT_LENGTH,
290        MAX_DECLARED_STREAM_LENGTH,
291        RUN_LENGTH_MAX_OUTPUT_LENGTH,
292        ZLIB_MAX_OUTPUT_LENGTH,
293        ZLIB_MAX_RECOVERY_INPUT_LENGTH,
294    )
295    from pypdf.xmp import XMP_MAX_ELEMENT_COUNT, XMP_MAX_INPUT_LENGTH  # noqa: PLC0415
296
297    legacy_values = {
298        "MAX_DECLARED_STREAM_LENGTH": MAX_DECLARED_STREAM_LENGTH,
299        "MAX_ARRAY_BASED_STREAM_OUTPUT_LENGTH": MAX_ARRAY_BASED_STREAM_OUTPUT_LENGTH,
300        "JBIG2_MAX_OUTPUT_LENGTH": JBIG2_MAX_OUTPUT_LENGTH,
301        "LZW_MAX_OUTPUT_LENGTH": LZW_MAX_OUTPUT_LENGTH,
302        "RUN_LENGTH_MAX_OUTPUT_LENGTH": RUN_LENGTH_MAX_OUTPUT_LENGTH,
303        "ZLIB_MAX_OUTPUT_LENGTH": ZLIB_MAX_OUTPUT_LENGTH,
304        "ZLIB_MAX_RECOVERY_INPUT_LENGTH": ZLIB_MAX_RECOVERY_INPUT_LENGTH,
305        "FLATE_MAX_COLUMNS": FLATE_MAX_COLUMNS,
306        "FLATE_MAX_ROW_LENGTH": FLATE_MAX_ROW_LENGTH,
307        "FLATE_MAX_BUFFER_SIZE": FLATE_MAX_BUFFER_SIZE,
308        "XMP_MAX_INPUT_LENGTH": XMP_MAX_INPUT_LENGTH,
309        "XMP_MAX_ELEMENT_COUNT": XMP_MAX_ELEMENT_COUNT,
310        "JBIG2DEC_BINARY": JBIG2DEC_BINARY,
311        "MERGE_CROP_BOX": MERGE_CROP_BOX,
312    }
313
314    for field_name, legacy_name in LEGACY_NAME_MAPPING.items():
315        legacy_value = legacy_values[legacy_name]
316
317        if legacy_value != getattr(DEFAULT_CONFIGURATION, field_name):
318            from pypdf._utils import deprecation_with_replacement  # noqa: PLC0415
319
320            deprecation_with_replacement(
321                old_name=legacy_name,
322                new_name=f"Configuration.{field_name}",
323                removed_in="7.0.0",
324            )
325
326    return configuration