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