Source code

Download source archive ↓

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)