src/pypdf/generic/_data_structures.py
1# Copyright (c) 2006, Mathieu Fenniak
2# All rights reserved.
3#
4# Redistribution and use in source and binary forms, with or without
5# modification, are permitted provided that the following conditions are
6# met:
7#
8# * Redistributions of source code must retain the above copyright notice,
9# this list of conditions and the following disclaimer.
10# * Redistributions in binary form must reproduce the above copyright notice,
11# this list of conditions and the following disclaimer in the documentation
12# and/or other materials provided with the distribution.
13# * The name of the author may not be used to endorse or promote products
14# derived from this software without specific prior written permission.
15#
16# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
20# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26# POSSIBILITY OF SUCH DAMAGE.
27
28__author__ = "Mathieu Fenniak"
29__author_email__ = "biziqe@mathieu.fenniak.net"
30
31import inspect
32import logging
33import os
34import re
35import sys
36from collections.abc import Callable, Iterable, Sequence
37from functools import cache
38from io import BytesIO
39from typing import (
40 Any,
41 NamedTuple,
42 Optional,
43 Union,
44 cast,
45)
46
47from .. import get_configuration
48from .._protocols import PdfReaderProtocol, PdfWriterProtocol, XmpInformationProtocol
49from .._utils import (
50 WHITESPACES,
51 BinaryStreamType,
52 StreamType,
53 logger_warning,
54 read_non_whitespace,
55 read_until_regex,
56 read_until_whitespace,
57 skip_over_comment,
58 skip_over_comments,
59)
60from ..constants import (
61 CheckboxRadioButtonAttributes,
62 FieldDictionaryAttributes,
63 FilterTypes,
64 OutlineFontFlag,
65 StreamAttributes,
66 TypArguments,
67 TypFitArguments,
68)
69from ..errors import STREAM_TRUNCATED_PREMATURELY, LimitReachedError, PdfReadError, PdfStreamError
70from ._base import (
71 BooleanObject,
72 ByteStringObject,
73 FloatObject,
74 IndirectObject,
75 NameObject,
76 NullObject,
77 NumberObject,
78 PdfObject,
79 TextStringObject,
80 is_null_or_none,
81)
82from ._fit import Fit
83from ._utils import StreamParsingBudget, read_hex_string_from_stream, read_string_from_stream
84
85if sys.version_info >= (3, 11):
86 from typing import Self
87else:
88 from typing_extensions import Self
89
90logger = logging.getLogger(__name__)
91
92IndirectPattern = re.compile(rb"[+-]?(\d+)\s+(\d+)\s+R[^a-zA-Z]")
93
94# Direct objects of these types are neither streams nor indirect objects.
95# Large arrays consist mostly of them, for example in the /ParentTree of the
96# structure tree, so the clone loops check the exact type first and skip the
97# slower isinstance() checks.
98_SCALAR_TYPES = frozenset(
99 (BooleanObject, ByteStringObject, FloatObject, NameObject, NullObject, NumberObject, TextStringObject)
100)
101
102
103class ArrayObject(list[Any], PdfObject):
104 def replicate(
105 self,
106 pdf_dest: PdfWriterProtocol,
107 ) -> "ArrayObject":
108 arr = cast(
109 "ArrayObject",
110 self._reference_clone(ArrayObject(), pdf_dest, False),
111 )
112 for data in self:
113 if hasattr(data, "replicate"):
114 arr.append(data.replicate(pdf_dest))
115 else:
116 arr.append(data)
117 return arr
118
119 def clone(
120 self,
121 pdf_dest: PdfWriterProtocol,
122 force_duplicate: bool = False,
123 ignore_fields: Sequence[str | int] | None = (),
124 ) -> "ArrayObject":
125 """Clone object into pdf_dest."""
126 try:
127 if self.indirect_reference.pdf == pdf_dest and not force_duplicate: # type: ignore[union-attr]
128 return self
129 except MemoryError: # pragma: no cover # TODO: BLE001
130 raise
131 except Exception:
132 pass
133 arr = cast(
134 "ArrayObject",
135 self._reference_clone(ArrayObject(), pdf_dest, force_duplicate=True),
136 )
137 for data in self:
138 if type(data) in _SCALAR_TYPES:
139 # Same as the generic case below, but without the isinstance() checks.
140 arr.append(data.clone(pdf_dest, force_duplicate, ignore_fields))
141 elif isinstance(data, StreamObject):
142 dup = data._reference_clone(
143 data.clone(pdf_dest, force_duplicate, ignore_fields),
144 pdf_dest,
145 force_duplicate,
146 )
147 arr.append(dup.indirect_reference)
148 elif isinstance(data, IndirectObject) and isinstance(resolved := data.get_object(), StreamObject):
149 dup = data._reference_clone(
150 resolved.clone(pdf_dest, force_duplicate=True, ignore_fields=ignore_fields),
151 pdf_dest,
152 force_duplicate,
153 )
154 arr.append(dup.indirect_reference)
155 elif hasattr(data, "clone"):
156 arr.append(data.clone(pdf_dest, force_duplicate, ignore_fields))
157 else:
158 arr.append(data)
159 return arr
160
161 def hash_bin(self) -> int:
162 """
163 Used to detect modified object.
164
165 Returns:
166 Hash considering type and value.
167
168 """
169 return hash((self.__class__, tuple(x.hash_bin() for x in self)))
170
171 def items(self) -> Iterable[Any]:
172 """Emulate DictionaryObject.items for a list (index, object)."""
173 return enumerate(self)
174
175 def _to_lst(self, lst: Any) -> list[Any]:
176 # Convert to list, internal
177 result: list[Any]
178 if isinstance(lst, (list, tuple, set)):
179 result = list(lst)
180 elif isinstance(lst, PdfObject):
181 result = [lst]
182 elif isinstance(lst, str):
183 if lst[0] == "/":
184 result = [NameObject(lst)]
185 else:
186 result = [TextStringObject(lst)]
187 elif isinstance(lst, bytes):
188 result = [ByteStringObject(lst)]
189 else: # for numbers,...
190 result = [lst]
191 return result
192
193 def __add__(self, lst: Any) -> "ArrayObject":
194 """
195 Allow extension by adding list or add one element only
196
197 Args:
198 lst: any list, tuples are extended the list.
199 other types(numbers,...) will be appended.
200 if str is passed it will be converted into TextStringObject
201 or NameObject (if starting with "/")
202 if bytes is passed it will be converted into ByteStringObject
203
204 Returns:
205 ArrayObject with all elements
206
207 """
208 temp = ArrayObject(self)
209 temp.extend(self._to_lst(lst))
210 return temp
211
212 def __iadd__(self, lst: Any) -> Self:
213 """
214 Allow extension by adding list or add one element only
215
216 Args:
217 lst: any list, tuples are extended the list.
218 other types(numbers,...) will be appended.
219 if str is passed it will be converted into TextStringObject
220 or NameObject (if starting with "/")
221 if bytes is passed it will be converted into ByteStringObject
222
223 """
224 self.extend(self._to_lst(lst))
225 return self
226
227 def __isub__(self, lst: Any) -> Self:
228 """Allow to remove items"""
229 for x in self._to_lst(lst):
230 try:
231 index = self.index(x)
232 del self[index]
233 except ValueError:
234 pass
235 return self
236
237 def write_to_stream(self, stream: StreamType) -> None:
238 stream.write(b"[")
239 for data in self:
240 stream.write(b" ")
241 data.write_to_stream(stream)
242 stream.write(b" ]")
243
244 @staticmethod
245 def _check_limits(*, remaining_elements: int, parsing_budget: StreamParsingBudget | None) -> int:
246 remaining_elements -= 1
247 if remaining_elements < 0:
248 raise LimitReachedError("Reached maximum array element count.")
249 if parsing_budget is not None:
250 parsing_budget.remaining_budget -= 1
251 if parsing_budget.remaining_budget < 0:
252 raise LimitReachedError("Reached maximum number of tokens.")
253 return remaining_elements
254
255 @staticmethod
256 def read_from_stream(
257 stream: StreamType,
258 pdf: PdfReaderProtocol | None,
259 forced_encoding: str | list[str] | dict[int, str] | None = None,
260 *,
261 parsing_budget: StreamParsingBudget | None = None,
262 ) -> "ArrayObject":
263 arr = ArrayObject()
264 tmp = stream.read(1)
265 if tmp != b"[":
266 raise PdfReadError("Could not read array")
267 remaining_elements = get_configuration().array_maximum_element_count
268 while True:
269 # skip leading whitespace
270 tok = stream.read(1)
271 while tok.isspace() or tok in WHITESPACES:
272 tok = stream.read(1)
273 if tok == b"":
274 break
275 if tok == b"%":
276 stream.seek(-1, 1)
277 skip_over_comment(stream)
278 continue
279 # check for array ending
280 if tok == b"]":
281 break
282
283 remaining_elements = ArrayObject._check_limits(
284 remaining_elements=remaining_elements, parsing_budget=parsing_budget
285 )
286 if tok == b"n":
287 # Shortcut for null, as some arrays consist mostly of nulls
288 rest = stream.read(3)
289 if rest == b"ull":
290 arr.append(NullObject())
291 continue
292 stream.seek(-len(rest), 1)
293 stream.seek(-1, 1)
294 # read and append object
295 arr.append(read_object(stream, pdf, forced_encoding, parsing_budget=parsing_budget))
296 return arr
297
298
299@cache
300def _requires_constructor_arguments(cls: type["DictionaryObject"]) -> bool:
301 """Report whether ``cls`` can only be instantiated with arguments."""
302 parameters = inspect.signature(cls.__init__).parameters
303 return any(
304 parameter.default is inspect.Parameter.empty
305 and parameter.kind
306 in (
307 inspect.Parameter.POSITIONAL_ONLY,
308 inspect.Parameter.POSITIONAL_OR_KEYWORD,
309 inspect.Parameter.KEYWORD_ONLY,
310 )
311 for parameter in list(parameters.values())[1:]
312 )
313
314
315class DictionaryObject(dict[Any, Any], PdfObject):
316 def _new_for_clone(self) -> "DictionaryObject":
317 """Create a blank instance of this class to receive cloned entries.
318
319 Most dictionary classes can be instantiated without arguments, but some
320 subclasses - the annotation dictionaries for instance - can only be
321 instantiated with arguments. Those arguments are not needed to receive a
322 clone, because every entry is copied from the source object afterwards,
323 so such classes are instantiated without calling ``__init__``.
324 """
325 if _requires_constructor_arguments(self.__class__):
326 return self.__class__.__new__(self.__class__)
327 return self.__class__()
328
329 def replicate(
330 self,
331 pdf_dest: PdfWriterProtocol,
332 ) -> "DictionaryObject":
333 d__ = cast(
334 "DictionaryObject",
335 self._reference_clone(self._new_for_clone(), pdf_dest, False),
336 )
337 for k, v in self.items():
338 d__[k.replicate(pdf_dest)] = (
339 v.replicate(pdf_dest) if hasattr(v, "replicate") else v
340 )
341 return d__
342
343 def clone(
344 self,
345 pdf_dest: PdfWriterProtocol,
346 force_duplicate: bool = False,
347 ignore_fields: Sequence[str | int] | None = (),
348 ) -> "DictionaryObject":
349 """Clone object into pdf_dest."""
350 try:
351 if self.indirect_reference.pdf == pdf_dest and not force_duplicate: # type: ignore[union-attr]
352 return self
353 except MemoryError: # pragma: no cover # TODO: BLE001
354 raise
355 except Exception:
356 pass
357
358 visited: set[tuple[int, int]] = set() # (idnum, generation)
359 d__ = cast(
360 "DictionaryObject",
361 self._reference_clone(self._new_for_clone(), pdf_dest, force_duplicate),
362 )
363 if ignore_fields is None:
364 ignore_fields = []
365 if len(d__.keys()) == 0:
366 d__._clone(self, pdf_dest, force_duplicate, ignore_fields, visited)
367 return d__
368
369 def _clone(
370 self,
371 src: "DictionaryObject",
372 pdf_dest: PdfWriterProtocol,
373 force_duplicate: bool,
374 ignore_fields: Sequence[str | int] | None,
375 visited: set[tuple[int, int]], # (idnum, generation)
376 ) -> None:
377 """
378 Update the object from src.
379
380 Args:
381 src: "DictionaryObject":
382 pdf_dest:
383 force_duplicate:
384 ignore_fields:
385
386 """
387 # First we remove the ignore_fields
388 # that are for a limited number of levels
389 assert ignore_fields is not None
390 ignore_fields = list(ignore_fields)
391 x = 0
392 while x < len(ignore_fields):
393 if isinstance(ignore_fields[x], int):
394 if cast(int, ignore_fields[x]) <= 0:
395 del ignore_fields[x]
396 del ignore_fields[x]
397 continue
398 ignore_fields[x] -= 1 # type: ignore[operator]
399 x += 1
400 # Check if this is a chain list, we need to loop to prevent recur
401 if any(
402 field not in ignore_fields
403 and field in src
404 and isinstance(src.raw_get(field), IndirectObject)
405 and isinstance(src[field], DictionaryObject)
406 and (
407 src.get("/Type", None) is None
408 or cast(DictionaryObject, src[field]).get("/Type", None) is None
409 or src.get("/Type", None)
410 == cast(DictionaryObject, src[field]).get("/Type", None)
411 )
412 for field in ["/Next", "/Prev", "/N", "/V"]
413 ):
414 ignore_fields = list(ignore_fields)
415 for lst in (("/Next", "/Prev"), ("/N", "/V")):
416 for k in lst:
417 objs = []
418 if (
419 k in src
420 and k not in self
421 and isinstance(src.raw_get(k), IndirectObject)
422 and isinstance(src[k], DictionaryObject)
423 # If need to go further the idea is to check
424 # that the types are the same
425 and (
426 src.get("/Type", None) is None
427 or cast(DictionaryObject, src[k]).get("/Type", None) is None
428 or src.get("/Type", None)
429 == cast(DictionaryObject, src[k]).get("/Type", None)
430 )
431 ):
432 cur_obj: DictionaryObject | None = cast(
433 "DictionaryObject", src[k]
434 )
435 prev_obj: DictionaryObject | None = self
436 while cur_obj is not None:
437 source_reference = getattr(cur_obj, "indirect_reference", None)
438 clon = cast(
439 "DictionaryObject",
440 cur_obj._reference_clone(
441 cur_obj._new_for_clone(), pdf_dest, force_duplicate
442 ),
443 )
444 # Check to see if we've previously processed our item
445 if source_reference is not None:
446 source_idnum = source_reference.idnum
447 source_generation = source_reference.generation
448 if (source_idnum, source_generation) in visited:
449 cur_obj = None
450 break
451 visited.add((source_idnum, source_generation))
452 objs.append((cur_obj, clon))
453 assert prev_obj is not None
454 clone_reference = getattr(clon, "indirect_reference", None)
455 prev_obj[NameObject(k)] = clone_reference if clone_reference is not None else clon
456 prev_obj = clon
457 try:
458 if cur_obj == src:
459 cur_obj = None
460 else:
461 next_obj = cur_obj[k]
462 if isinstance(next_obj, DictionaryObject):
463 cur_obj = next_obj
464 else:
465 cur_obj = None
466 except MemoryError: # pragma: no cover # TODO: BLE001
467 raise
468 except Exception:
469 cur_obj = None
470 for s, c in objs:
471 c._clone(
472 s, pdf_dest, force_duplicate, ignore_fields, visited
473 )
474
475 for k, v in src.items():
476 if k not in ignore_fields:
477 # The type check does not change the result. It only skips the
478 # slower isinstance() check for the most common values.
479 if type(v) not in _SCALAR_TYPES and isinstance(v, StreamObject):
480 if not hasattr(v, "indirect_reference"):
481 v.indirect_reference = None
482 vv = v.clone(pdf_dest, force_duplicate, ignore_fields)
483 assert vv.indirect_reference is not None
484 self[k.clone(pdf_dest)] = vv.indirect_reference
485 elif k not in self:
486 self[NameObject(k)] = (
487 v.clone(pdf_dest, force_duplicate, ignore_fields)
488 if hasattr(v, "clone")
489 else v
490 )
491
492 def hash_bin(self) -> int:
493 """
494 Used to detect modified object.
495
496 Returns:
497 Hash considering type and value.
498
499 """
500 return hash(
501 (self.__class__, tuple(((k, v.hash_bin()) for k, v in self.items())))
502 )
503
504 def raw_get(self, key: Any) -> Any:
505 return dict.__getitem__(self, key)
506
507 def get_inherited(self, key: str, default: Any = None) -> Any:
508 """
509 Returns the value of a key or from the parent if not found.
510 If not found returns default.
511
512 Args:
513 key: string identifying the field to return
514
515 default: default value to return
516
517 Returns:
518 Current key or inherited one, otherwise default value.
519
520 """
521 current = self
522 visited: set[int] = set()
523
524 while True:
525 # Detect cyclic parent references
526 obj_id = id(current)
527 if obj_id in visited:
528 raise LimitReachedError(f"Detected cycle in /Parent hierarchy when retrieving value for key {key!r}.")
529 visited.add(obj_id)
530
531 if key in current:
532 return current[key]
533
534 if "/Parent" not in current:
535 return default
536
537 # Walk upward
538 parent = current["/Parent"].get_object()
539 if not isinstance(parent, DictionaryObject):
540 # A malformed /Parent that does not resolve to a dictionary
541 # terminates the inheritance walk (the key was not found).
542 return default
543 current = parent
544
545 def __setitem__(self, key: Any, value: Any) -> Any:
546 if not isinstance(key, PdfObject):
547 raise ValueError("Key must be a PdfObject")
548 if not isinstance(value, PdfObject):
549 raise ValueError("Value must be a PdfObject")
550 return dict.__setitem__(self, key, value)
551
552 def setdefault(self, key: Any, value: Any | None = None) -> Any:
553 if not isinstance(key, PdfObject):
554 raise ValueError("Key must be a PdfObject")
555 if not isinstance(value, PdfObject):
556 raise ValueError("Value must be a PdfObject")
557 return dict.setdefault(self, key, value)
558
559 def __getitem__(self, key: Any) -> PdfObject:
560 return cast(PdfObject, dict.__getitem__(self, key).get_object())
561
562 @property
563 def xmp_metadata(self) -> XmpInformationProtocol | None:
564 """
565 Retrieve XMP (Extensible Metadata Platform) data relevant to this
566 object, if available.
567
568 See Table 347 — Additional entries in a metadata stream dictionary.
569
570 Returns:
571 Returns a :class:`~pypdf.xmp.XmpInformation` instance
572 that can be used to access XMP metadata from the document. Can also
573 return None if no metadata was found on the document root.
574
575 """
576 from ..xmp import XmpInformation # noqa: PLC0415
577
578 metadata = self.get("/Metadata", None)
579 if is_null_or_none(metadata):
580 return None
581 assert metadata is not None, "mypy"
582 metadata = metadata.get_object()
583 return XmpInformation(metadata)
584
585 def write_to_stream(self, stream: StreamType) -> None:
586 stream.write(b"<<\n")
587 for key, value in self.items():
588 if len(key) > 2 and key[1] == "%" and key[-1] == "%":
589 continue
590 key.write_to_stream(stream)
591 stream.write(b" ")
592 value.write_to_stream(stream)
593 stream.write(b"\n")
594 stream.write(b">>")
595
596 @classmethod
597 def _get_next_object_position(
598 cls, position_before: int, position_end: int, generations: list[int], pdf: PdfReaderProtocol
599 ) -> int:
600 out = position_end
601 for generation in generations:
602 for x in pdf.xref[generation].values():
603 if position_before < x <= position_end:
604 out = min(out, x)
605 return out
606
607 @classmethod
608 def _read_unsized_from_stream(
609 cls, *, stream: BinaryStreamType, pdf: PdfReaderProtocol, length: int,
610 ) -> bytes:
611 current_position = stream.tell()
612
613 # Determine stream size.
614 try:
615 stream.seek(0, os.SEEK_END)
616 stream_length = stream.tell()
617 finally:
618 stream.seek(current_position)
619
620 object_position = cls._get_next_object_position(
621 position_before=current_position, position_end=stream_length, generations=list(pdf.xref), pdf=pdf
622 )
623
624 bytes_to_read = object_position - current_position
625 if bytes_to_read >= length:
626 raise LimitReachedError(f"Requested length of {bytes_to_read} exceeds maximum allowed length.")
627
628 # Read until the next object position.
629 read_value = stream.read(bytes_to_read)
630 endstream_position = read_value.find(b"endstream")
631 if endstream_position < 0:
632 raise PdfReadError(
633 f"Unable to find 'endstream' marker for obj starting at {current_position}."
634 )
635 # 9 = len(b"endstream")
636 stream.seek(current_position + endstream_position + 9)
637 return read_value[: endstream_position - 1]
638
639 @staticmethod
640 def read_from_stream(
641 stream: StreamType,
642 pdf: PdfReaderProtocol | None,
643 forced_encoding: str | list[str] | dict[int, str] | None = None,
644 *,
645 parsing_budget: StreamParsingBudget | None = None,
646 ) -> "DictionaryObject":
647 tmp = stream.read(2)
648 if tmp != b"<<":
649 raise PdfReadError(
650 f"Dictionary read error at byte {hex(stream.tell())}: "
651 "stream must begin with '<<'"
652 )
653 data: dict[Any, Any] = {}
654 remaining_count = get_configuration().dictionary_maximum_element_count
655 while True:
656 tok = read_non_whitespace(stream)
657 if tok == b"%":
658 stream.seek(-1, 1)
659 skip_over_comment(stream)
660 continue
661 if not tok:
662 raise PdfStreamError(STREAM_TRUNCATED_PREMATURELY)
663
664 if tok == b">":
665 stream.read(1)
666 break
667 stream.seek(-1, 1)
668
669 remaining_count -= 1
670 if remaining_count < 0:
671 raise LimitReachedError("Reached maximum number of dictionary entries.")
672 if parsing_budget is not None:
673 parsing_budget.remaining_budget -= 2
674 if parsing_budget.remaining_budget < 0:
675 raise LimitReachedError("Reached maximum number of tokens.")
676
677 try:
678 try:
679 key = read_object(stream, pdf, parsing_budget=parsing_budget)
680 if isinstance(key, NullObject):
681 break
682 if not isinstance(key, NameObject):
683 raise PdfReadError(
684 f"Expecting a NameObject for key but found {key!r}"
685 )
686 except PdfReadError as exc:
687 if pdf is not None and pdf.strict:
688 raise
689 logger_warning("%(exception)r", source=__name__, exception=exc)
690 continue
691 tok = read_non_whitespace(stream)
692 stream.seek(-1, 1)
693 value = read_object(stream, pdf, forced_encoding, parsing_budget=parsing_budget)
694 except LimitReachedError:
695 # Always propagate security issues.
696 raise
697 except (MemoryError, RecursionError) as exc:
698 raise PdfReadError("Error reading PDF file.") from exc
699 except Exception as exc:
700 if pdf is not None and pdf.strict:
701 raise PdfReadError("Error reading PDF file.") from exc
702 logger_warning("%(exception)s", source=__name__, exception=repr(exc)[:500])
703 retval = DictionaryObject()
704 retval.update(data)
705 return retval # return partial data
706
707 if key not in data:
708 data[key] = value
709 else:
710 # multiple definitions of key not permitted
711 msg = (
712 "Multiple definitions in dictionary at byte "
713 "%(position)s for key %(key)s"
714 )
715 values = {"position": hex(stream.tell()), "key": key}
716 if pdf is not None and pdf.strict:
717 raise PdfReadError(msg % values)
718 logger_warning(msg, source=__name__, **values)
719
720 DictionaryObject._read_stream_data(stream=stream, pdf=pdf, data=data)
721 if "__streamdata__" in data:
722 return StreamObject.initialize_from_dictionary(data)
723 retval = DictionaryObject()
724 retval.update(data)
725 return retval
726
727 @staticmethod
728 def _read_stream_data(
729 *,
730 stream: StreamType,
731 pdf: PdfReaderProtocol | None,
732 data: dict[Any, Any]
733 ) -> None:
734 pos = stream.tell()
735 s = read_non_whitespace(stream)
736 if s == b"s" and stream.read(5) == b"tream":
737 eol = stream.read(1)
738 # Occasional PDF file output has spaces after 'stream' keyword but before EOL.
739 # patch provided by Danial Sandler
740 while eol == b" ":
741 eol = stream.read(1)
742 if eol not in (b"\n", b"\r"):
743 raise PdfStreamError("Stream data must be followed by a newline")
744 if eol == b"\r" and stream.read(1) != b"\n":
745 stream.seek(-1, 1)
746 # this is a stream object, not a dictionary
747 if StreamAttributes.LENGTH not in data:
748 if pdf is not None and pdf.strict:
749 raise PdfStreamError("Stream length not defined")
750 logger_warning(
751 "Stream length not defined @pos=%(position)d",
752 source=__name__,
753 position=stream.tell(),
754 )
755 data[NameObject(StreamAttributes.LENGTH)] = NumberObject(-1)
756 length = data[StreamAttributes.LENGTH]
757 if isinstance(length, IndirectObject):
758 t = stream.tell()
759 assert pdf is not None, "mypy"
760 length = pdf.get_object(length)
761 stream.seek(t, 0)
762 if length is None: # if the PDF is damaged
763 length = -1
764 pstart = stream.tell()
765
766 from .._configuration import get_configuration # noqa: PLC0415
767 configuration = get_configuration()
768 if length >= 0:
769 if length > configuration.maximum_declared_stream_length:
770 raise LimitReachedError(f"Declared stream length of {length} exceeds maximum allowed length.")
771
772 data["__streamdata__"] = stream.read(length)
773 else:
774 data["__streamdata__"] = read_until_regex(
775 stream=stream, regex=re.compile(b"endstream"), length=configuration.maximum_declared_stream_length,
776 )
777 e = read_non_whitespace(stream)
778 ndstream = stream.read(8)
779 if (e + ndstream) != b"endstream":
780 # the odd PDF file has a length that is too long, so
781 # we need to read backwards to find the "endstream" ending.
782 # ReportLab (unknown version) generates files with this bug,
783 # and Python users into PDF files tend to be our audience.
784 # we need to do this to correct the streamdata and chop off
785 # an extra character.
786 pos = stream.tell()
787 stream.seek(-10, 1)
788 end = stream.read(9)
789 if end == b"endstream":
790 # we found it by looking back one character further.
791 data["__streamdata__"] = data["__streamdata__"][:-1]
792 elif pdf is not None and not pdf.strict:
793 stream.seek(pstart, 0)
794 data["__streamdata__"] = DictionaryObject._read_unsized_from_stream(
795 stream=stream, pdf=pdf, length=configuration.maximum_declared_stream_length
796 )
797 pos = stream.tell()
798 else:
799 stream.seek(pos, 0)
800 raise PdfReadError(
801 "Unable to find 'endstream' marker after stream at byte "
802 f"{hex(stream.tell())} (nd='{ndstream!r}', end='{end!r}')."
803 )
804 else:
805 stream.seek(pos, 0)
806
807
808class TreeObject(DictionaryObject):
809 def __init__(self, dct: DictionaryObject | None = None) -> None:
810 DictionaryObject.__init__(self)
811 if dct:
812 self.update(dct)
813
814 def has_children(self) -> bool:
815 return "/First" in self
816
817 def __iter__(self) -> Any:
818 return self.children()
819
820 def children(self) -> Iterable[Any]:
821 if not self.has_children():
822 return
823
824 child_ref = self[NameObject("/First")]
825 last = self[NameObject("/Last")]
826 child = child_ref.get_object()
827 visited: set[int] = set()
828 while True:
829 child_id = id(child)
830 if child_id in visited:
831 logger_warning("Detected cycle in outline structure for %(child)s", source=__name__, child=child)
832 return
833 visited.add(child_id)
834
835 yield child
836
837 if child == last:
838 return
839 child_ref = child.get(NameObject("/Next")) # type: ignore[union-attr]
840 if is_null_or_none(child_ref):
841 return
842 child = child_ref.get_object()
843
844 def add_child(self, child: Any, pdf: PdfWriterProtocol) -> None:
845 self.insert_child(child, None, pdf)
846
847 def inc_parent_counter_default(
848 self, parent: Union[IndirectObject, "TreeObject", None], n: int
849 ) -> None:
850 if is_null_or_none(parent):
851 return
852 assert parent is not None, "mypy"
853 parent = cast("TreeObject", parent.get_object())
854 if "/Count" in parent:
855 parent[NameObject("/Count")] = NumberObject(
856 max(0, cast(int, parent[NameObject("/Count")]) + n)
857 )
858 self.inc_parent_counter_default(parent.get("/Parent", None), n)
859
860 def inc_parent_counter_outline(
861 self, parent: Union[IndirectObject, "TreeObject", None], n: int
862 ) -> None:
863 if is_null_or_none(parent):
864 return
865 assert parent is not None, "mypy"
866 parent = cast("TreeObject", parent.get_object())
867 # BooleanObject requires comparison with == not is
868 opn = parent.get("/%is_open%", True) == True # noqa: E712
869 c = cast(int, parent.get("/Count", 0))
870 if c < 0:
871 c = abs(c)
872 parent[NameObject("/Count")] = NumberObject((c + n) * (1 if opn else -1))
873 if not opn:
874 return
875 self.inc_parent_counter_outline(parent.get("/Parent", None), n)
876
877 def insert_child(
878 self,
879 child: Any,
880 before: Any,
881 pdf: PdfWriterProtocol,
882 inc_parent_counter: Callable[..., Any] | None = None,
883 ) -> IndirectObject:
884 if inc_parent_counter is None:
885 inc_parent_counter = self.inc_parent_counter_default
886 child_obj = child.get_object()
887 assert child.indirect_reference is not None, "mypy"
888 child_reference: IndirectObject = child.indirect_reference
889
890 prev: DictionaryObject | None
891 if "/First" not in self: # no child yet
892 self[NameObject("/First")] = child_reference
893 self[NameObject("/Count")] = NumberObject(0)
894 self[NameObject("/Last")] = child_reference
895 child_obj[NameObject("/Parent")] = self.indirect_reference
896 inc_parent_counter(self, child_obj.get("/Count", 1))
897 if "/Next" in child_obj:
898 del child_obj["/Next"]
899 if "/Prev" in child_obj:
900 del child_obj["/Prev"]
901 return child_reference
902 prev = cast("DictionaryObject", self["/Last"])
903
904 visited: set[int] = set()
905 while prev.indirect_reference != before:
906 prev_id = id(prev)
907 if prev_id in visited:
908 raise LimitReachedError("Detected cycle in tree structure.")
909 visited.add(prev_id)
910 if "/Next" in prev:
911 prev = cast("TreeObject", prev["/Next"])
912 continue
913
914 # append at the end
915 prev[NameObject("/Next")] = cast("TreeObject", child_reference)
916 child_obj[NameObject("/Prev")] = prev.indirect_reference
917 child_obj[NameObject("/Parent")] = self.indirect_reference
918 if "/Next" in child_obj:
919 del child_obj["/Next"]
920 self[NameObject("/Last")] = child_reference
921 inc_parent_counter(self, child_obj.get("/Count", 1))
922 return child_reference
923 try: # insert as first or in the middle
924 assert isinstance(prev["/Prev"], DictionaryObject)
925 prev["/Prev"][NameObject("/Next")] = child_reference
926 child_obj[NameObject("/Prev")] = prev["/Prev"]
927 except MemoryError: # pragma: no cover # TODO: BLE001
928 raise
929 except Exception: # it means we are inserting in first position
930 child_obj.pop("/Next", None)
931 child_obj[NameObject("/Next")] = prev
932 prev[NameObject("/Prev")] = child_reference
933 child_obj[NameObject("/Parent")] = self.indirect_reference
934 inc_parent_counter(self, child_obj.get("/Count", 1))
935 return child_reference
936
937 def _remove_node_from_tree(
938 self, *, previous: Any, previous_reference: Any, current: Any, last: Any
939 ) -> None:
940 """Adjust the pointers of the linked list and tree node count."""
941 next_reference = current.get("/Next", None)
942 if previous is None:
943 if next_reference:
944 # Removing first tree node
945 next_object = next_reference.get_object()
946 del next_object["/Prev"]
947 self[NameObject("/First")] = next_reference
948 self[NameObject("/Count")] = NumberObject(
949 self[NameObject("/Count")] - 1 # type: ignore[operator]
950 )
951
952 else:
953 # Removing only tree node
954 self[NameObject("/Count")] = NumberObject(0)
955 del self["/First"]
956 if NameObject("/Last") in self:
957 del self[NameObject("/Last")]
958 else:
959 if next_reference:
960 # Removing middle tree node
961 next_object = next_reference.get_object()
962 next_object[NameObject("/Prev")] = previous_reference
963 previous[NameObject("/Next")] = next_reference
964 else:
965 # Removing last tree node
966 assert current == last
967 del previous["/Next"]
968 self[NameObject("/Last")] = previous_reference
969 self[NameObject("/Count")] = NumberObject(self["/Count"] - 1) # type: ignore[operator]
970
971 def remove_child(self, child: Any) -> None:
972 child_object = child.get_object()
973
974 if "/Parent" not in child_object:
975 raise ValueError("Removed child does not appear to be a tree item")
976 if child_object["/Parent"] != self:
977 raise ValueError("Removed child is not a member of this tree")
978
979 found = False
980 previous_reference = None
981 previous = None
982 current_reference: Any | None = self["/First"]
983 current: dict[str, Any] | None = current_reference.get_object() # type: ignore[union-attr]
984 last_reference = self["/Last"]
985 last = last_reference.get_object()
986 visited: set[int] = set()
987 while current is not None:
988 if current == child_object:
989 TreeObject._remove_node_from_tree(
990 self, previous=previous, previous_reference=previous_reference, current=current, last=last
991 )
992 found = True
993 break
994 current_id = id(current)
995 if current_id in visited:
996 raise LimitReachedError("Detected cyclic /Next hierarchy.")
997 visited.add(current_id)
998
999 # Go to the next node.
1000 previous_reference = current_reference
1001 previous = current
1002 if "/Next" not in current:
1003 break
1004 current_reference = current["/Next"]
1005 current = current_reference.get_object()
1006
1007 if not found:
1008 raise ValueError("Removal couldn't find item in tree")
1009
1010 _reset_node_tree_relationship(child_object)
1011
1012 def remove_from_tree(self) -> None:
1013 """Remove the object from the tree it is in."""
1014 if "/Parent" not in self:
1015 raise ValueError("Removed child does not appear to be a tree item")
1016 cast("TreeObject", self["/Parent"]).remove_child(self)
1017
1018 def empty_tree(self) -> None:
1019 for child in self:
1020 child_obj = child.get_object()
1021 _reset_node_tree_relationship(child_obj)
1022
1023 if NameObject("/Count") in self:
1024 del self[NameObject("/Count")]
1025 if NameObject("/First") in self:
1026 del self[NameObject("/First")]
1027 if NameObject("/Last") in self:
1028 del self[NameObject("/Last")]
1029
1030
1031def _reset_node_tree_relationship(child_obj: Any) -> None:
1032 """
1033 Call this after a node has been removed from a tree.
1034
1035 This resets the nodes attributes in respect to that tree.
1036
1037 Args:
1038 child_obj:
1039
1040 """
1041 del child_obj[NameObject("/Parent")]
1042 if NameObject("/Next") in child_obj:
1043 del child_obj[NameObject("/Next")]
1044 if NameObject("/Prev") in child_obj:
1045 del child_obj[NameObject("/Prev")]
1046
1047
1048class _FontFileCharacterMap(NamedTuple):
1049 """The character map pypdf._cmap derived from an embedded font program. See #4156."""
1050
1051 digest: bytes
1052 """SHA-256 digest of the decoded font data the map was derived from."""
1053 map_dict: dict[Any, Any]
1054 int_entry: list[int]
1055
1056
1057class StreamObject(DictionaryObject):
1058 _font_file_character_map: _FontFileCharacterMap | None = None
1059 """
1060 The character map pypdf._cmap derived from this stream as an embedded font program. Parsing a CFF font
1061 program with fontTools is expensive, and the same program is reached from every font resource and page
1062 referencing it. See #4156.
1063 """
1064
1065 def __init__(self) -> None:
1066 self._data: bytes = b""
1067 self.decoded_self: DecodedStreamObject | None = None
1068
1069 def replicate(
1070 self,
1071 pdf_dest: PdfWriterProtocol,
1072 ) -> "StreamObject":
1073 d__ = cast(
1074 "StreamObject",
1075 self._reference_clone(self.__class__(), pdf_dest, False),
1076 )
1077 d__._data = self._data
1078 try:
1079 decoded_self = self.decoded_self
1080 if decoded_self is None:
1081 self.decoded_self = None
1082 else:
1083 self.decoded_self = cast(
1084 "DecodedStreamObject", decoded_self.replicate(pdf_dest)
1085 )
1086 except MemoryError: # pragma: no cover # TODO: BLE001
1087 raise
1088 except Exception:
1089 pass
1090 for k, v in self.items():
1091 d__[k.replicate(pdf_dest)] = (
1092 v.replicate(pdf_dest) if hasattr(v, "replicate") else v
1093 )
1094 return d__
1095
1096 def _clone(
1097 self,
1098 src: DictionaryObject,
1099 pdf_dest: PdfWriterProtocol,
1100 force_duplicate: bool,
1101 ignore_fields: Sequence[str | int] | None,
1102 visited: set[tuple[int, int]],
1103 ) -> None:
1104 """
1105 Update the object from src.
1106
1107 Args:
1108 src:
1109 pdf_dest:
1110 force_duplicate:
1111 ignore_fields:
1112
1113 """
1114 self._data = cast("StreamObject", src)._data
1115 try:
1116 decoded_self = cast("StreamObject", src).decoded_self
1117 if decoded_self is None:
1118 self.decoded_self = None
1119 else:
1120 self.decoded_self = cast(
1121 "DecodedStreamObject",
1122 decoded_self.clone(pdf_dest, force_duplicate, ignore_fields),
1123 )
1124 except MemoryError: # pragma: no cover # TODO: BLE001
1125 raise
1126 except Exception:
1127 pass
1128 super()._clone(src, pdf_dest, force_duplicate, ignore_fields, visited)
1129
1130 def hash_bin(self) -> int:
1131 """
1132 Used to detect modified object.
1133
1134 Returns:
1135 Hash considering type and value.
1136
1137 """
1138 # Use _data to prevent errors on non-decoded streams.
1139 return hash((super().hash_bin(), self._data))
1140
1141 def get_data(self) -> bytes:
1142 return self._data
1143
1144 def set_data(self, data: bytes) -> None:
1145 self._data = data
1146
1147 def hash_value_data(self) -> bytes:
1148 data = super().hash_value_data()
1149 data += self.get_data()
1150 return data
1151
1152 def write_to_stream(self, stream: StreamType) -> None:
1153 self[NameObject(StreamAttributes.LENGTH)] = NumberObject(len(self._data))
1154 DictionaryObject.write_to_stream(self, stream)
1155 del self[StreamAttributes.LENGTH]
1156 stream.write(b"\nstream\n")
1157 stream.write(self._data)
1158 stream.write(b"\nendstream")
1159
1160 @staticmethod
1161 def initialize_from_dictionary(
1162 data: dict[str, Any]
1163 ) -> Union["EncodedStreamObject", "DecodedStreamObject"]:
1164 retval: EncodedStreamObject | DecodedStreamObject
1165 if StreamAttributes.FILTER in data:
1166 retval = EncodedStreamObject()
1167 else:
1168 retval = DecodedStreamObject()
1169 retval._data = data["__streamdata__"]
1170 del data["__streamdata__"]
1171 if StreamAttributes.LENGTH in data:
1172 del data[StreamAttributes.LENGTH]
1173 retval.update(data)
1174 return retval
1175
1176 def flate_encode(self, level: int = -1) -> "EncodedStreamObject":
1177 from ..filters import FlateDecode # noqa: PLC0415
1178
1179 if StreamAttributes.FILTER in self:
1180 f = self[StreamAttributes.FILTER]
1181 if isinstance(f, ArrayObject):
1182 f = ArrayObject([NameObject(FilterTypes.FLATE_DECODE), *f])
1183 try:
1184 params = ArrayObject(
1185 [NullObject(), *self.get(StreamAttributes.DECODE_PARMS, ArrayObject())]
1186 )
1187 except TypeError:
1188 # case of error where the * operator is not working (not an array
1189 params = ArrayObject(
1190 [NullObject(), self.get(StreamAttributes.DECODE_PARMS, ArrayObject())]
1191 )
1192 else:
1193 f = ArrayObject([NameObject(FilterTypes.FLATE_DECODE), f])
1194 params = ArrayObject(
1195 [NullObject(), self.get(StreamAttributes.DECODE_PARMS, NullObject())]
1196 )
1197 else:
1198 f = NameObject(FilterTypes.FLATE_DECODE)
1199 params = None
1200 retval = EncodedStreamObject()
1201 retval.update(self)
1202 retval[NameObject(StreamAttributes.FILTER)] = f
1203 if params is not None:
1204 retval[NameObject(StreamAttributes.DECODE_PARMS)] = params
1205 retval._data = FlateDecode.encode(self._data, level)
1206 return retval
1207
1208 def decode_as_image(self, pillow_parameters: dict[str, Any] | None = None) -> Any:
1209 """
1210 Try to decode the stream object as an image
1211
1212 Args:
1213 pillow_parameters: parameters provided to Pillow Image.save() method,
1214 cf. <https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.save>
1215
1216 Returns:
1217 a PIL image if proper decoding has been found
1218 Raises:
1219 Exception: Errors during decoding will be reported.
1220 It is recommended to catch exceptions to prevent
1221 stops in your program.
1222
1223 """
1224 from ._image_xobject import _xobj_to_image # noqa: PLC0415
1225
1226 if self.get("/Subtype", "") != "/Image":
1227 try:
1228 logger_warning( # pragma: no cover
1229 "%(indirect_reference)s does not seem to be an Image",
1230 source=__name__,
1231 indirect_reference=self.indirect_reference,
1232 )
1233 except AttributeError:
1234 logger_warning( # pragma: no cover
1235 "%(obj)r object does not seem to be an Image",
1236 source=__name__,
1237 obj=self,
1238 )
1239 extension, _, img = _xobj_to_image(self, pillow_parameters)
1240 if extension is None:
1241 return None # pragma: no cover
1242 return img
1243
1244
1245class DecodedStreamObject(StreamObject):
1246 pass
1247
1248
1249class EncodedStreamObject(StreamObject):
1250 def __init__(self) -> None:
1251 self.decoded_self: DecodedStreamObject | None = None
1252
1253 def hash_value_data(self) -> bytes:
1254 # Hash the encoded bytes instead of the decoded data: decoding is slow,
1255 # it keeps a decoded copy of every stream in memory, and it fails for
1256 # streams that cannot be decoded.
1257 #
1258 # Streams with equal dictionaries and equal encoded bytes still get the
1259 # same hash, so PdfWriter.compress_identical_objects() merges them.
1260 # Streams whose decoded data is equal but whose encoded bytes differ,
1261 # for example the same data compressed with two zlib levels, now get
1262 # different hashes and are no longer merged. The output stays correct;
1263 # it is only not as small as it could be. If users want maximum
1264 # compression at the cost of execution time, a parameter such as
1265 # compare_decoded_streams of compress_identical_objects() could add
1266 # back the comparison of the decoded data.
1267 return DictionaryObject.hash_value_data(self) + self._data
1268
1269 # This overrides the parent method
1270 def get_data(self) -> bytes:
1271 from ..filters import decode_stream_data # noqa: PLC0415
1272
1273 if self.decoded_self is not None:
1274 # Cached version of decoded object
1275 return self.decoded_self.get_data()
1276
1277 # Create decoded object
1278 decoded = DecodedStreamObject()
1279 decoded.set_data(decode_stream_data(self))
1280 for key, value in self.items():
1281 if key not in (StreamAttributes.LENGTH, StreamAttributes.FILTER, StreamAttributes.DECODE_PARMS):
1282 decoded[key] = value
1283 self.decoded_self = decoded
1284 return decoded.get_data()
1285
1286 # This overrides the parent method:
1287 def set_data(self, data: bytes) -> None:
1288 from ..filters import FlateDecode # noqa: PLC0415
1289
1290 if self.get(StreamAttributes.FILTER, "") in (FilterTypes.FLATE_DECODE, [FilterTypes.FLATE_DECODE]):
1291 if not isinstance(data, bytes):
1292 raise TypeError("Data must be bytes")
1293 if self.decoded_self is None:
1294 self.get_data() # to create self.decoded_self
1295 assert self.decoded_self is not None, "mypy"
1296 self.decoded_self.set_data(data)
1297 super().set_data(FlateDecode.encode(data))
1298 else:
1299 raise PdfReadError(
1300 "Streams encoded with a filter different from FlateDecode are not supported"
1301 )
1302
1303
1304CONTENT_STREAM_ARRAY_MAX_LENGTH = 10_000
1305
1306
1307class ContentStream(DecodedStreamObject):
1308 """
1309 In order to be fast, this data structure can contain either:
1310
1311 * raw data in ._data
1312 * parsed stream operations in ._operations.
1313
1314 At any time, ContentStream object can either have both of those fields defined,
1315 or one field defined and the other set to None.
1316
1317 These fields are "rebuilt" lazily, when accessed:
1318
1319 * when .get_data() is called, if ._data is None, it is rebuilt from ._operations.
1320 * when .operations is called, if ._operations is None, it is rebuilt from ._data.
1321
1322 Conversely, these fields can be invalidated:
1323
1324 * when .set_data() is called, ._operations is set to None.
1325 * when .operations is set, ._data is set to None.
1326 """
1327 _OPERATOR_LENGTH_LIMIT = 128
1328
1329 def __init__(
1330 self,
1331 stream: Any,
1332 pdf: Any,
1333 forced_encoding: str | list[str] | dict[int, str] | None = None,
1334 ) -> None:
1335 self.pdf = pdf
1336 self._operations: list[tuple[Any, bytes]] = []
1337
1338 # stream may be a StreamObject or an ArrayObject containing
1339 # StreamObjects to be concatenated together.
1340 if stream is None:
1341 super().set_data(b"")
1342 else:
1343 stream = stream.get_object()
1344 if isinstance(stream, ArrayObject):
1345 from pypdf._configuration import get_configuration # noqa: PLC0415
1346 configuration = get_configuration()
1347
1348 if (stream_length := len(stream)) > CONTENT_STREAM_ARRAY_MAX_LENGTH:
1349 raise LimitReachedError(
1350 f"Array-based stream has {stream_length} > {CONTENT_STREAM_ARRAY_MAX_LENGTH} elements."
1351 )
1352 data = bytearray()
1353 length = 0
1354 for s in stream:
1355 s_resolved = s.get_object()
1356 if isinstance(s_resolved, NullObject):
1357 continue
1358 if not isinstance(s_resolved, StreamObject):
1359 # No need to emit an exception here for now - the PDF structure
1360 # seems to already be broken beforehand in these cases.
1361 logger_warning(
1362 "Expected StreamObject, got %(type_name)s instead. Data might be wrong.",
1363 source=__name__,
1364 type_name=type(s_resolved).__name__,
1365 )
1366 else:
1367 new_data = s_resolved.get_data()
1368 length += len(new_data)
1369 if length > configuration.array_based_stream_maximum_output_length:
1370 raise LimitReachedError(
1371 f"Array-based stream has at least {length} > "
1372 f"{configuration.array_based_stream_maximum_output_length} output bytes."
1373 )
1374 data += new_data
1375 if len(data) == 0 or data[-1:] != b"\n":
1376 # There should be no direct need to check for a change of one byte.
1377 length += 1
1378 data += b"\n"
1379 super().set_data(bytes(data))
1380 else:
1381 stream_data = stream.get_data()
1382 assert stream_data is not None
1383 super().set_data(stream_data)
1384 self.forced_encoding = forced_encoding
1385
1386 def replicate(
1387 self,
1388 pdf_dest: PdfWriterProtocol,
1389 ) -> "ContentStream":
1390 d__ = cast(
1391 "ContentStream",
1392 self._reference_clone(self.__class__(None, None), pdf_dest, False),
1393 )
1394 d__._data = self._data
1395 try:
1396 decoded_self = self.decoded_self
1397 if decoded_self is None:
1398 self.decoded_self = None
1399 else:
1400 self.decoded_self = cast(
1401 "DecodedStreamObject", decoded_self.replicate(pdf_dest)
1402 )
1403 except MemoryError: # pragma: no cover # TODO: BLE001
1404 raise
1405 except Exception:
1406 pass
1407 for k, v in self.items():
1408 d__[k.replicate(pdf_dest)] = (
1409 v.replicate(pdf_dest) if hasattr(v, "replicate") else v
1410 )
1411 d__.pdf = pdf_dest
1412 d__._operations = list(self._operations)
1413 d__.forced_encoding = self.forced_encoding
1414 return d__
1415
1416 def clone(
1417 self,
1418 pdf_dest: Any,
1419 force_duplicate: bool = False,
1420 ignore_fields: Sequence[str | int] | None = (),
1421 ) -> "ContentStream":
1422 """
1423 Clone object into pdf_dest.
1424
1425 Args:
1426 pdf_dest:
1427 force_duplicate:
1428 ignore_fields:
1429
1430 Returns:
1431 The cloned ContentStream
1432
1433 """
1434 try:
1435 if self.indirect_reference.pdf == pdf_dest and not force_duplicate: # type: ignore[union-attr]
1436 return self
1437 except MemoryError: # pragma: no cover # TODO: BLE001
1438 raise
1439 except Exception:
1440 pass
1441
1442 visited: set[tuple[int, int]] = set()
1443 d__ = cast(
1444 "ContentStream",
1445 self._reference_clone(
1446 self.__class__(None, None), pdf_dest, force_duplicate
1447 ),
1448 )
1449 if ignore_fields is None:
1450 ignore_fields = []
1451 d__._clone(self, pdf_dest, force_duplicate, ignore_fields, visited)
1452 return d__
1453
1454 def _clone(
1455 self,
1456 src: DictionaryObject,
1457 pdf_dest: PdfWriterProtocol,
1458 force_duplicate: bool,
1459 ignore_fields: Sequence[str | int] | None,
1460 visited: set[tuple[int, int]],
1461 ) -> None:
1462 """
1463 Update the object from src.
1464
1465 Args:
1466 src:
1467 pdf_dest:
1468 force_duplicate:
1469 ignore_fields:
1470
1471 """
1472 src_cs = cast("ContentStream", src)
1473 super().set_data(src_cs._data)
1474 self.pdf = pdf_dest
1475 self._operations = list(src_cs._operations)
1476 self.forced_encoding = src_cs.forced_encoding
1477 # no need to call DictionaryObjection or anything
1478 # like super(DictionaryObject,self)._clone(src, pdf_dest, force_duplicate, ignore_fields, visited)
1479
1480 @staticmethod
1481 def _check_limits(
1482 *,
1483 remaining_elements: int | None = None,
1484 parsing_budget: StreamParsingBudget,
1485 token_decrement: int
1486 ) -> int | None:
1487 if remaining_elements is not None:
1488 remaining_elements -= 1
1489 if remaining_elements < 0:
1490 raise LimitReachedError("Reached maximum number of tokens.")
1491 parsing_budget.remaining_budget -= token_decrement
1492 if parsing_budget.remaining_budget < 0:
1493 raise LimitReachedError("Reached maximum number of tokens per stream.")
1494 return remaining_elements
1495
1496 def _parse_content_stream(self, stream: StreamType) -> None:
1497 # 7.8.2 Content Streams
1498 stream.seek(0, 0)
1499 operands: list[int | str | PdfObject] = []
1500 parsing_budget = StreamParsingBudget(remaining_budget=get_configuration().stream_parsing_work_maximum_count)
1501 while True:
1502 peek = read_non_whitespace(stream)
1503 if peek in (b"", 0):
1504 break
1505 stream.seek(-1, 1)
1506 if peek.isalpha() or peek in (b"'", b'"'):
1507 operator = read_until_regex(
1508 stream=stream, regex=NameObject.delimiter_pattern, length=self._OPERATOR_LENGTH_LIMIT
1509 )
1510 if operator == b"BI":
1511 # begin inline image - a completely different parsing
1512 # mechanism is required, of course... thanks buddy...
1513 assert operands == []
1514 self._check_limits(parsing_budget=parsing_budget, token_decrement=2)
1515
1516 from ._image_inline import read_inline_image # noqa: PLC0415
1517 ii = read_inline_image(content_stream=self, stream=stream, parsing_budget=parsing_budget)
1518 self._operations.append((ii, b"INLINE IMAGE"))
1519 else:
1520 self._check_limits(parsing_budget=parsing_budget, token_decrement=1)
1521 self._operations.append((operands, operator))
1522 operands = []
1523 elif peek == b"%":
1524 # If we encounter a comment in the content stream, we have to
1525 # handle it here. Typically, read_object will handle
1526 # encountering a comment -- but read_object assumes that
1527 # following the comment must be the object we're trying to
1528 # read. In this case, it could be an operator instead.
1529 while peek not in (b"\r", b"\n", b""):
1530 peek = stream.read(1)
1531 else:
1532 self._check_limits(parsing_budget=parsing_budget, token_decrement=1)
1533 operands.append(read_object(stream, None, self.forced_encoding, parsing_budget=parsing_budget))
1534
1535 # This overrides the parent method
1536 def get_data(self) -> bytes:
1537 if not self._data:
1538 new_data = BytesIO()
1539 for operands, operator in self._operations:
1540 if operator == b"INLINE IMAGE":
1541 new_data.write(b"BI")
1542 dict_text = BytesIO()
1543 operands["settings"].write_to_stream(dict_text)
1544 new_data.write(dict_text.getvalue()[2:-2])
1545 new_data.write(b"ID ")
1546 new_data.write(operands["data"])
1547 new_data.write(b"EI")
1548 else:
1549 for op in operands:
1550 op.write_to_stream(new_data)
1551 new_data.write(b" ")
1552 new_data.write(operator)
1553 new_data.write(b"\n")
1554 self._data = new_data.getvalue()
1555 return self._data
1556
1557 # This overrides the parent method
1558 def set_data(self, data: bytes) -> None:
1559 super().set_data(data)
1560 self._operations = []
1561
1562 @property
1563 def operations(self) -> list[tuple[Any, bytes]]:
1564 if not self._operations and self._data:
1565 self._parse_content_stream(BytesIO(self._data))
1566 self._data = b""
1567 return self._operations
1568
1569 @operations.setter
1570 def operations(self, operations: list[tuple[Any, bytes]]) -> None:
1571 self._operations = operations
1572 self._data = b""
1573
1574 def isolate_graphics_state(self) -> None:
1575 if self._operations:
1576 self._operations.insert(0, ([], b"q"))
1577 self._operations.append(([], b"Q"))
1578 elif self._data:
1579 self._data = b"q\n" + self._data + b"\nQ\n"
1580
1581 # This overrides the parent method
1582 def write_to_stream(
1583 self, stream: StreamType, encryption_key: str | bytes | None = None
1584 ) -> None:
1585 if not self._data and self._operations:
1586 self.get_data() # this ensures ._data is rebuilt
1587 super().write_to_stream(stream)
1588
1589
1590# Bound comment scanning without consuming Python recursion depth.
1591_MAX_LEADING_COMMENTS = 1000
1592
1593
1594def read_object( # noqa: PLR0911
1595 stream: StreamType,
1596 pdf: PdfReaderProtocol | None,
1597 forced_encoding: str | list[str] | dict[int, str] | None = None,
1598 *,
1599 parsing_budget: StreamParsingBudget | None = None,
1600) -> PdfObject:
1601 """
1602 Read the next object from the stream.
1603
1604 Args:
1605 stream: The stream to read from.
1606 pdf: The corresponding PDF file.
1607 forced_encoding: The encoding to enforce, if any.
1608 parsing_budget: The allowed parsing budget, optional. If set, only applies to dictionaries,
1609 arrays and content streams.
1610
1611 Returns:
1612 The parsed object.
1613 """
1614 tok = stream.read(1)
1615 stream.seek(-1, 1) # reset to start
1616 if tok == b"%":
1617 # Skip consecutive comments in a loop instead of recursing per comment.
1618 skip_over_comments(stream, limit=_MAX_LEADING_COMMENTS)
1619 tok = stream.read(1)
1620 stream.seek(-1, 1) # reset to start
1621 if tok == b"/":
1622 return NameObject.read_from_stream(stream, pdf)
1623 if tok == b"<":
1624 # hexadecimal string OR dictionary
1625 peek = stream.read(2)
1626 stream.seek(-2, 1) # reset to start
1627 if peek == b"<<":
1628 return DictionaryObject.read_from_stream(stream, pdf, forced_encoding, parsing_budget=parsing_budget)
1629 return read_hex_string_from_stream(stream, forced_encoding)
1630 if tok == b"[":
1631 return ArrayObject.read_from_stream(stream, pdf, forced_encoding, parsing_budget=parsing_budget)
1632 if tok in (b"t", b"f"):
1633 return BooleanObject.read_from_stream(stream)
1634 if tok == b"(":
1635 return read_string_from_stream(stream, forced_encoding)
1636 if tok == b"e" and stream.read(6) == b"endobj":
1637 return NullObject()
1638 if tok == b"n":
1639 return NullObject.read_from_stream(stream)
1640 if tok in b"0123456789+-.":
1641 # number object OR indirect reference
1642 peek = stream.read(20)
1643 match = IndirectPattern.match(peek)
1644 if match is not None:
1645 assert pdf is not None, "mypy"
1646 # Continue after the "R", the match includes the character following it
1647 stream.seek(match.end() - 1 - len(peek), 1)
1648 # The object number includes an optional sign
1649 return IndirectObject(int(peek[: match.end(1)]), int(match[2]), pdf)
1650 number_end = NumberObject.NumberPattern.search(peek)
1651 if number_end is not None:
1652 # The whole number is in the peek, there is no need to read it again
1653 num = peek[: number_end.start()]
1654 stream.seek(len(num) - len(peek), 1)
1655 if b"." in num:
1656 return FloatObject(num)
1657 return NumberObject(num)
1658 stream.seek(-len(peek), 1) # reset to start
1659 return NumberObject.read_from_stream(stream)
1660 pos = stream.tell()
1661 stream.seek(-20, 1)
1662 stream_extract = stream.read(80)
1663 stream.seek(pos)
1664 read_until_whitespace(stream)
1665 raise PdfReadError(
1666 f"Invalid Elementary Object starting with {tok!r} @{pos}: {stream_extract!r}"
1667 )
1668
1669
1670class Field(TreeObject):
1671 """
1672 A class representing a field dictionary.
1673
1674 This class is accessed through
1675 :meth:`get_fields()<pypdf.PdfReader.get_fields>`
1676 """
1677
1678 def __init__(self, data: DictionaryObject) -> None:
1679 DictionaryObject.__init__(self)
1680 field_attributes = (
1681 FieldDictionaryAttributes.attributes()
1682 + CheckboxRadioButtonAttributes.attributes()
1683 )
1684 self.indirect_reference = data.indirect_reference
1685 for attr in field_attributes:
1686 try:
1687 self[NameObject(attr)] = data[attr]
1688 except KeyError:
1689 pass
1690 if isinstance(self.get("/V"), EncodedStreamObject):
1691 d = cast(EncodedStreamObject, self[NameObject("/V")]).get_data()
1692 if isinstance(d, bytes):
1693 d_str = d.decode()
1694 elif d is None:
1695 d_str = ""
1696 else:
1697 raise Exception("Should never happen")
1698 self[NameObject("/V")] = TextStringObject(d_str)
1699
1700 # TABLE 8.69 Entries common to all field dictionaries
1701 @property
1702 def field_type(self) -> NameObject | None:
1703 """Read-only property accessing the type of this field."""
1704 return self.get(FieldDictionaryAttributes.FT)
1705
1706 @property
1707 def parent(self) -> DictionaryObject | None:
1708 """Read-only property accessing the parent of this field."""
1709 return self.get(FieldDictionaryAttributes.Parent)
1710
1711 @property
1712 def kids(self) -> Optional["ArrayObject"]:
1713 """Read-only property accessing the kids of this field."""
1714 return self.get(FieldDictionaryAttributes.Kids)
1715
1716 @property
1717 def name(self) -> str | None:
1718 """Read-only property accessing the name of this field."""
1719 return self.get(FieldDictionaryAttributes.T)
1720
1721 @property
1722 def alternate_name(self) -> str | None:
1723 """Read-only property accessing the alternate name of this field."""
1724 return self.get(FieldDictionaryAttributes.TU)
1725
1726 @property
1727 def mapping_name(self) -> str | None:
1728 """
1729 Read-only property accessing the mapping name of this field.
1730
1731 This name is used by pypdf as a key in the dictionary returned by
1732 :meth:`get_fields()<pypdf.PdfReader.get_fields>`
1733 """
1734 return self.get(FieldDictionaryAttributes.TM)
1735
1736 @property
1737 def flags(self) -> int | None:
1738 """
1739 Read-only property accessing the field flags, specifying various
1740 characteristics of the field (see Table 8.70 of the PDF 1.7 reference).
1741 """
1742 return self.get(FieldDictionaryAttributes.Ff)
1743
1744 @property
1745 def value(self) -> Any | None:
1746 """
1747 Read-only property accessing the value of this field.
1748
1749 Format varies based on field type.
1750 """
1751 return self.get(FieldDictionaryAttributes.V)
1752
1753 @property
1754 def default_value(self) -> Any | None:
1755 """Read-only property accessing the default value of this field."""
1756 return self.get(FieldDictionaryAttributes.DV)
1757
1758 @property
1759 def additional_actions(self) -> DictionaryObject | None:
1760 """
1761 Read-only property accessing the additional actions dictionary.
1762
1763 This dictionary defines the field's behavior in response to trigger
1764 events. See Section 8.5.2 of the PDF 1.7 reference.
1765 """
1766 return self.get(FieldDictionaryAttributes.AA)
1767
1768
1769class Destination(TreeObject):
1770 """
1771 A class representing a destination within a PDF file.
1772
1773 See section 12.3.2 of the PDF 2.0 reference.
1774
1775 Args:
1776 title: Title of this destination.
1777 page: Reference to the page of this destination. Should
1778 be an instance of :class:`IndirectObject<pypdf.generic.IndirectObject>`.
1779 fit: How the destination is displayed.
1780
1781 Raises:
1782 PdfReadError: If destination type is invalid.
1783
1784 """
1785
1786 node: DictionaryObject | None = None # node provide access to the original Object
1787
1788 def remove_from_tree(self) -> None:
1789 """
1790 Remove the outline item this destination was built from.
1791
1792 `reader.outline` and `writer.outline` yield detached copies rather than
1793 the nodes themselves, so the copy never has a `/Parent` and removing it
1794 would be a no-op. `node` is the dictionary in the document.
1795 """
1796 if self.node is None:
1797 super().remove_from_tree()
1798 elif "/Parent" not in self.node:
1799 raise ValueError("Removed child does not appear to be a tree item")
1800 else:
1801 TreeObject.remove_child(
1802 cast("TreeObject", self.node["/Parent"]), self.node
1803 )
1804
1805 def __init__(
1806 self,
1807 title: str | bytes,
1808 page: NumberObject | IndirectObject | NullObject | DictionaryObject,
1809 fit: Fit,
1810 ) -> None:
1811 self._filtered_children: list[Any] = [] # used in PdfWriter
1812
1813 typ = fit.fit_type
1814 args = fit.fit_args
1815
1816 DictionaryObject.__init__(self)
1817 self[NameObject("/Title")] = TextStringObject(title)
1818 self[NameObject("/Page")] = page
1819 self[NameObject("/Type")] = typ
1820
1821 # from table 8.2 of the PDF 1.7 reference.
1822 if typ == "/XYZ":
1823 if len(args) < 1: # left is missing : should never occur
1824 args.append(NumberObject(0.0))
1825 if len(args) < 2: # top is missing
1826 args.append(NumberObject(0.0))
1827 if len(args) < 3: # zoom is missing
1828 args.append(NumberObject(0.0))
1829 # surplus arguments are ignored rather than failing the unpacking
1830 (
1831 self[NameObject(TypArguments.LEFT)],
1832 self[NameObject(TypArguments.TOP)],
1833 self[NameObject("/Zoom")],
1834 ) = args[:3]
1835 elif len(args) == 0:
1836 pass
1837 elif typ == TypFitArguments.FIT_R:
1838 if len(args) == 4: # a wrong number of arguments degrades to null
1839 (
1840 self[NameObject(TypArguments.LEFT)],
1841 self[NameObject(TypArguments.BOTTOM)],
1842 self[NameObject(TypArguments.RIGHT)],
1843 self[NameObject(TypArguments.TOP)],
1844 ) = args
1845 else:
1846 (
1847 self[NameObject(TypArguments.LEFT)],
1848 self[NameObject(TypArguments.BOTTOM)],
1849 self[NameObject(TypArguments.RIGHT)],
1850 self[NameObject(TypArguments.TOP)],
1851 ) = (NullObject(), NullObject(), NullObject(), NullObject())
1852 elif typ in [TypFitArguments.FIT_H, TypFitArguments.FIT_BH]:
1853 try: # Prefer to be more robust not only to null parameters
1854 (self[NameObject(TypArguments.TOP)],) = args
1855 except MemoryError: # pragma: no cover # TODO: BLE001
1856 raise
1857 except Exception:
1858 (self[NameObject(TypArguments.TOP)],) = (NullObject(),)
1859 elif typ in [TypFitArguments.FIT_V, TypFitArguments.FIT_BV]:
1860 try: # Prefer to be more robust not only to null parameters
1861 (self[NameObject(TypArguments.LEFT)],) = args
1862 except MemoryError: # pragma: no cover # TODO: BLE001
1863 raise
1864 except Exception:
1865 (self[NameObject(TypArguments.LEFT)],) = (NullObject(),)
1866 elif typ in [TypFitArguments.FIT, TypFitArguments.FIT_B]:
1867 pass
1868 else:
1869 raise PdfReadError(f"Unknown Destination Type: {typ!r}")
1870
1871 @property
1872 def dest_array(self) -> "ArrayObject":
1873 return ArrayObject(
1874 [self.raw_get("/Page"), self["/Type"]]
1875 + [
1876 self[x]
1877 for x in ["/Left", "/Bottom", "/Right", "/Top", "/Zoom"]
1878 if x in self
1879 ]
1880 )
1881
1882 def write_to_stream(self, stream: StreamType) -> None:
1883 stream.write(b"<<\n")
1884 key = NameObject("/D")
1885 key.write_to_stream(stream)
1886 stream.write(b" ")
1887 value = self.dest_array
1888 value.write_to_stream(stream)
1889
1890 key = NameObject("/S")
1891 key.write_to_stream(stream)
1892 stream.write(b" ")
1893 value_s = NameObject("/GoTo")
1894 value_s.write_to_stream(stream)
1895
1896 stream.write(b"\n")
1897 stream.write(b">>")
1898
1899 @property
1900 def title(self) -> str | None:
1901 """Read-only property accessing the destination title."""
1902 return self.get("/Title")
1903
1904 @property
1905 def page(self) -> IndirectObject | None:
1906 """Read-only property accessing the IndirectObject of the destination page."""
1907 return self.get("/Page")
1908
1909 @property
1910 def typ(self) -> str | None:
1911 """Read-only property accessing the destination type."""
1912 return self.get("/Type")
1913
1914 @property
1915 def zoom(self) -> int | None:
1916 """Read-only property accessing the zoom factor."""
1917 return self.get("/Zoom", None)
1918
1919 @property
1920 def left(self) -> FloatObject | None:
1921 """Read-only property accessing the left horizontal coordinate."""
1922 return self.get("/Left", None)
1923
1924 @property
1925 def right(self) -> FloatObject | None:
1926 """Read-only property accessing the right horizontal coordinate."""
1927 return self.get("/Right", None)
1928
1929 @property
1930 def top(self) -> FloatObject | None:
1931 """Read-only property accessing the top vertical coordinate."""
1932 return self.get("/Top", None)
1933
1934 @property
1935 def bottom(self) -> FloatObject | None:
1936 """Read-only property accessing the bottom vertical coordinate."""
1937 return self.get("/Bottom", None)
1938
1939 @property
1940 def color(self) -> Optional["ArrayObject"]:
1941 """Read-only property accessing the color in (R, G, B) with values 0.0-1.0."""
1942 return cast(
1943 "ArrayObject",
1944 self.get("/C", ArrayObject([FloatObject(0), FloatObject(0), FloatObject(0)])),
1945 )
1946
1947 @property
1948 def font_format(self) -> OutlineFontFlag | None:
1949 """
1950 Read-only property accessing the font type.
1951
1952 1=italic, 2=bold, 3=both
1953 """
1954 return OutlineFontFlag(self.get("/F", 0))
1955
1956 @property
1957 def outline_count(self) -> int | None:
1958 """
1959 Read-only property accessing the outline count.
1960
1961 positive = expanded
1962 negative = collapsed
1963 absolute value = number of visible descendants at all levels
1964 """
1965 return self.get("/Count", None)