Source code

Download source archive ↓

src/pypdf/_reader.py

1# Copyright (c) 2006, Mathieu Fenniak
2# Copyright (c) 2007, Ashish Kulkarni <kulkarni.ashish@gmail.com>
3#
4# All rights reserved.
5#
6# Redistribution and use in source and binary forms, with or without
7# modification, are permitted provided that the following conditions are
8# met:
9#
10# * Redistributions of source code must retain the above copyright notice,
11# this list of conditions and the following disclaimer.
12# * Redistributions in binary form must reproduce the above copyright notice,
13# this list of conditions and the following disclaimer in the documentation
14# and/or other materials provided with the distribution.
15# * The name of the author may not be used to endorse or promote products
16# derived from this software without specific prior written permission.
17#
18# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
22# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28# POSSIBILITY OF SUCH DAMAGE.
29
30import os
31import re
32import sys
33from collections.abc import Callable, Iterable
34from io import BytesIO, UnsupportedOperation
35from operator import itemgetter
36from pathlib import Path
37from types import TracebackType
38from typing import (
39    TYPE_CHECKING,
40    Any,
41    cast,
42)
43
44if sys.version_info >= (3, 11):
45    from typing import Self
46else:
47    from typing_extensions import Self
48
49from ._configuration import apply_legacy_configuration
50from ._doc_common import PdfDocCommon, convert_to_int
51from ._encryption import Encryption, PasswordType
52from ._utils import (
53    WHITESPACES_AS_BYTES,
54    StrByteType,
55    StreamType,
56    _TraversalState,
57    get_stream_data,
58    get_stream_size,
59    logger_warning,
60    read_non_whitespace,
61    read_previous_line,
62    read_until_whitespace,
63    skip_over_comment,
64    skip_over_whitespace,
65)
66from .constants import TrailerKeys
67from .errors import (
68    EmptyFileError,
69    FileNotDecryptedError,
70    LimitReachedError,
71    PdfReadError,
72    PdfStreamError,
73    WrongPasswordError,
74)
75from .generic import (
76    ArrayObject,
77    ByteStringObject,
78    Destination,
79    DictionaryObject,
80    EncodedStreamObject,
81    IndirectObject,
82    NameObject,
83    NullObject,
84    NumberObject,
85    PdfObject,
86    StreamObject,
87    TextStringObject,
88    is_null_or_none,
89    read_object,
90)
91from .xmp import XmpInformation
92
93if TYPE_CHECKING:
94    from ._page import PageObject
95
96
97class PdfReader(PdfDocCommon):
98    """
99    Initialize a PdfReader object.
100
101    This operation can take some time, as the PDF stream's cross-reference
102    tables are read into memory.
103
104    Args:
105        stream: A File object or an object that supports the standard read
106            and seek methods similar to a File object. Could also be a
107            string representing a path to a PDF file.
108        strict: Determines whether user should be warned of all
109            problems and also causes some correctable problems to be fatal.
110            Defaults to ``False``.
111        password: Decrypt PDF file at initialization. If the
112            password is None, the file will not be decrypted.
113            Defaults to ``None``.
114        root_object_recovery_limit: The maximum number of objects to query
115            for recovering the Root object in non-strict mode. To disable
116            this security measure, pass ``None``.
117        xref_stream_maximum_entries: The maximum number of entries which are
118            allowed inside a stream-based cross-reference stream.
119
120    """
121
122    xref: dict[int, dict[Any, Any]]
123    trailer: DictionaryObject
124
125    def __init__(
126        self,
127        stream: StrByteType | Path,
128        strict: bool = False,
129        password: str | bytes | None = None,
130        *,
131        root_object_recovery_limit: int | None = 10_000,
132        xref_stream_maximum_entries: int = 2_000_000,
133    ) -> None:
134        self.strict = strict
135        self.flattened_pages: list[PageObject] | None = None
136
137        #: Storage of parsed PDF objects.
138        self.resolved_objects: dict[tuple[Any, Any], PdfObject | None] = {}
139
140        self._startxref: int = 0
141        self.xref_index = 0
142        self.xref = {}
143        self.xref_free_entry: dict[int, dict[Any, Any]] = {}
144        self.xref_objStm: dict[int, tuple[Any, Any]] = {}
145        self.trailer = DictionaryObject()
146
147        # Security parameters.
148        self._root_object_recovery_limit = (
149            root_object_recovery_limit if isinstance(root_object_recovery_limit, int) else sys.maxsize
150        )
151        self._xref_stream_maximum_entries = xref_stream_maximum_entries
152        self._xref_stream_entry_count = 0
153        apply_legacy_configuration()
154
155        # Map page indirect_reference number to page number
156        self._page_id2num: dict[Any, Any] | None = None
157
158        self._validated_root: DictionaryObject | None = None
159
160        self._initialize_stream(stream)
161        self._known_objects: set[tuple[int, int]] = set()
162
163        self._override_encryption = False
164        self._encryption: Encryption | None = None
165        if self.is_encrypted:
166            self._handle_encryption(password)
167        elif password is not None:
168            raise PdfReadError("Not an encrypted file")
169
170        self._named_destinations_cache: dict[str, Destination] | None = None
171        self._object_stream_resolution_stack: list[int] = []
172
173    def _initialize_stream(self, stream: StrByteType | Path) -> None:
174        if hasattr(stream, "mode") and "b" not in stream.mode:
175            logger_warning(
176                "PdfReader stream/file object is not in binary mode. "
177                "It may not be read correctly.",
178                source=__name__,
179            )
180        self._stream_opened = False
181        if isinstance(stream, (str, Path)):
182            with open(stream, "rb") as fh:
183                stream = BytesIO(fh.read())
184            self._stream_opened = True
185        self.read(stream)
186        self.stream = stream
187
188    def _handle_encryption(self, password: str | bytes | None) -> None:
189        self._override_encryption = True
190        # Some documents may not have a /ID, use two empty
191        # byte strings instead. Solves
192        # https://github.com/py-pdf/pypdf/issues/608
193        id_entry = self.trailer.get(TrailerKeys.ID, NullObject()).get_object()
194        id1_entry = b""
195        if isinstance(id_entry, ArrayObject) and id_entry:
196            first_id_entry = id_entry[0].get_object()
197            if isinstance(first_id_entry, (ByteStringObject, TextStringObject)):
198                id1_entry = first_id_entry.original_bytes
199            else:
200                logger_warning("Ignoring non-string first /ID entry of the trailer", source=__name__)
201        elif not isinstance(id_entry, NullObject):
202            logger_warning("Ignoring malformed /ID entry of the trailer", source=__name__)
203        encrypt_entry = self.trailer[TrailerKeys.ENCRYPT]
204        if not isinstance(encrypt_entry, DictionaryObject):
205            raise PdfReadError("/Encrypt entry of the trailer is not a dictionary")
206        self._encryption = Encryption.read(encrypt_entry, id1_entry)
207
208        # try empty password if no password provided
209        pwd = password if password is not None else b""
210        if (
211            self._encryption.verify(pwd, strict=self.strict) == PasswordType.NOT_DECRYPTED
212            and password is not None
213        ):
214            # raise if password provided
215            raise WrongPasswordError("Wrong password")
216        self._override_encryption = False
217
218    def __enter__(self) -> Self:
219        return self
220
221    def __exit__(
222        self,
223        exc_type: type[BaseException] | None,
224        exc_val: BaseException | None,
225        exc_tb: TracebackType | None,
226    ) -> None:
227        self.close()
228
229    def close(self) -> None:
230        """Close the stream if opened in __init__ and clear memory."""
231        if self._stream_opened:
232            self.stream.close()
233        self.flattened_pages = []
234        self.resolved_objects = {}
235        self.trailer = DictionaryObject()
236        self.xref = {}
237        self.xref_free_entry = {}
238        self.xref_objStm = {}
239
240    @property
241    def root_object(self) -> DictionaryObject:
242        """Provide access to "/Root". Standardized with PdfWriter."""
243        if self._validated_root:
244            return self._validated_root
245        root = self.trailer.get(TrailerKeys.ROOT, NullObject()).get_object()
246        root_dictionary: DictionaryObject
247        if isinstance(root, DictionaryObject):
248            root_dictionary = root
249        else:
250            # The catalog has to be a dictionary. Anything else cannot be used,
251            # thus treat it like an empty one and attempt the recovery below.
252            root_dictionary = DictionaryObject()
253        if is_null_or_none(root):
254            logger_warning('Cannot find "/Root" key in trailer', source=__name__)
255        elif root_dictionary.get("/Type") == "/Catalog":
256            self._validated_root = root_dictionary
257        else:
258            logger_warning("Invalid Root object in trailer", source=__name__)
259        if self._validated_root is None:
260            logger_warning('Searching object with "/Catalog" key', source=__name__)
261            number_of_objects = cast(int, self.trailer.get("/Size", 0))
262            if not isinstance(number_of_objects, int):
263                # the trailer may be corrupted and carry a non-integer /Size;
264                # treat it like a missing one and fail with the regular
265                # PdfReadError for an unrecoverable root
266                number_of_objects = 0
267            for i in range(number_of_objects):
268                if i >= self._root_object_recovery_limit:
269                    raise LimitReachedError("Maximum Root object recovery limit reached.")
270                try:
271                    obj = self.get_object(i + 1)
272                except MemoryError:  # pragma: no cover  # TODO: BLE001
273                    raise
274                except Exception:  # to be sure to capture all errors
275                    obj = None
276                if isinstance(obj, DictionaryObject) and obj.get("/Type") == "/Catalog":
277                    self._validated_root = obj
278                    logger_warning(
279                        "Root found at %(obj_reference)r",
280                        source=__name__,
281                        obj_reference=obj.indirect_reference,
282                    )
283                    break
284        if self._validated_root is None:
285            if "/Pages" in root_dictionary:
286                logger_warning(
287                    "Possible root found at %(root_ref)r, but missing /Catalog key",
288                    source=__name__,
289                    root_ref=root_dictionary.indirect_reference,
290                )
291                self._validated_root = root_dictionary
292            else:
293                raise PdfReadError("Cannot find Root object in pdf")
294        return self._validated_root
295
296    @property
297    def _info(self) -> DictionaryObject | None:
298        """
299        Provide access to "/Info". Standardized with PdfWriter.
300
301        Returns:
302            /Info Dictionary; None if the entry does not exist
303
304        """
305        info = self.trailer.get(TrailerKeys.INFO, None)
306        if is_null_or_none(info):
307            return None
308        assert info is not None, "mypy"
309        info = info.get_object()
310        if not isinstance(info, DictionaryObject):
311            raise PdfReadError(
312                "Trailer not found or does not point to a document information dictionary"
313            )
314        return info
315
316    @property
317    def _ID(self) -> ArrayObject | None:
318        """
319        Provide access to "/ID". Standardized with PdfWriter.
320
321        Returns:
322            /ID array; None if the entry does not exist
323
324        """
325        file_identifiers = self.trailer.get(TrailerKeys.ID, None)
326        if is_null_or_none(file_identifiers):
327            return None
328        assert file_identifiers is not None, "mypy"
329        return cast(ArrayObject, file_identifiers.get_object())
330
331    @property
332    def pdf_header(self) -> str:
333        """
334        The first 8 bytes of the file.
335
336        This is typically something like ``'%PDF-1.6'`` and can be used to
337        detect if the file is actually a PDF file and which version it is.
338        """
339        # TODO: Make this return a bytes object for consistency
340        #       but that needs a deprecation
341        loc = self.stream.tell()
342        self.stream.seek(0, 0)
343        pdf_file_version = self.stream.read(8).decode("utf-8", "backslashreplace")
344        self.stream.seek(loc, 0)  # return to where it was
345        return pdf_file_version
346
347    @property
348    def xmp_metadata(self) -> XmpInformation | None:
349        """XMP (Extensible Metadata Platform) data."""
350        try:
351            # The document-level metadata stream is exempt from encryption
352            # only if /EncryptMetadata is false (ISO 32000-2, Table 21).
353            self._override_encryption = (
354                self._encryption is not None and not self._encryption.EncryptMetadata
355            )
356            return cast(XmpInformation, self.root_object.xmp_metadata)
357        finally:
358            self._override_encryption = False
359
360    def _get_page_number_by_indirect(
361        self, indirect_reference: int | NullObject | IndirectObject | None
362    ) -> int | None:
363        """
364        Retrieve the page number from an indirect reference.
365
366        Args:
367            indirect_reference: The indirect reference to locate.
368
369        Returns:
370            Page number or None.
371
372        """
373        if self._page_id2num is None:
374            self._page_id2num = {
375                x.indirect_reference.idnum: i for i, x in enumerate(self.pages)  # type: ignore[union-attr]
376            }
377
378        if is_null_or_none(indirect_reference):
379            return None
380        assert isinstance(indirect_reference, (int, IndirectObject)), "mypy"
381        if isinstance(indirect_reference, int):
382            idnum = indirect_reference
383        else:
384            idnum = indirect_reference.idnum
385        assert self._page_id2num is not None, "hint for mypy"
386        return self._page_id2num.get(idnum, None)
387
388    def _get_object_from_stream(
389        self, indirect_reference: IndirectObject
390    ) -> PdfObject:
391        obj_id = indirect_reference.idnum
392        if obj_id in self._object_stream_resolution_stack:
393            start = self._object_stream_resolution_stack.index(obj_id)
394            cycle = [*self._object_stream_resolution_stack[start:], obj_id]
395            raise PdfReadError(
396                "Circular object-stream reference detected: " + " -> ".join(map(str, cycle))
397            )
398        self._object_stream_resolution_stack.append(obj_id)
399
400        try:
401            # indirect reference to object in object stream
402            # read the entire object stream into memory
403            stmnum, _idx = self.xref_objStm[indirect_reference.idnum]
404            obj_stm: EncodedStreamObject = IndirectObject(stmnum, 0, self).get_object()  # type: ignore[assignment]
405            # This is an xref to a stream, so its type better be a stream
406            assert cast(str, obj_stm["/Type"]) == "/ObjStm"
407            # Parse ALL objects in this stream in one pass and cache them.
408            # This avoids O(N²) behavior when many objects from the same stream
409            # are resolved individually (each call would re-parse the header).
410            stream_data = BytesIO(obj_stm.get_data())
411            n_value = obj_stm.get("/N")
412            first_value = obj_stm.get("/First")
413            if not isinstance(n_value, NumberObject) or not isinstance(
414                first_value, NumberObject
415            ):
416                raise PdfReadError(
417                    f"Invalid /ObjStm header for object {stmnum}: "
418                    "/N or /First missing or not a number"
419                )
420            n = int(n_value)
421            first_offset = int(first_value)
422
423            stream_length = get_stream_size(stream_data)
424            if n < 0 or not 0 <= first_offset <= stream_length:
425                # A negative /N, or a /First outside the stream, cannot
426                # describe a valid object stream; treating it as empty
427                # avoids leaking a ValueError/OverflowError from a bad seek.
428                if self.strict:
429                    raise PdfReadError(
430                        f"Invalid /N ({n}) or /First ({first_offset}) in object stream {stmnum}."
431                    )
432                logger_warning(
433                    (
434                        "Invalid /N (%(n)d) or /First (%(first)d) in object stream "
435                        "%(stmnum)d; ignoring the stream."
436                    ),
437                    source=__name__,
438                    n=n,
439                    first=first_offset,
440                    stmnum=stmnum,
441                )
442                return NullObject()
443
444            # ObjStm header format: "objnum offset objnum offset ..."
445            # smallest possible entry: "0 0" = 3 bytes (1 digit + 1 space + 1 digit)
446            # using // 4 would reject a valid 3-byte single entry (3 // 4 = 0)
447            max_n = stream_length // 3
448            stream_data.seek(0)
449            if n > max_n:
450                if self.strict:
451                    raise LimitReachedError(f"Value /N {n} for object {stmnum} exceeds maximum allowed value {max_n}.")
452                logger_warning(
453                    (
454                        "Value /N %(n)d for object %(stmnum)d exceeds maximum allowed value %(max_n)d. "
455                        "Limiting to %(max_n)d."
456                    ),
457                    source=__name__,
458                    n=n,
459                    stmnum=stmnum,
460                    max_n=max_n,
461                )
462                n = max_n
463
464            # Phase 1: Read the index (objnum, offset) pairs from the header.
465            obj_index: list[tuple[int, int]] = []
466            last_offset: int = -1
467            for _i in range(n):
468                read_non_whitespace(stream_data)
469                stream_data.seek(-1, 1)
470                objnum = NumberObject.read_from_stream(stream_data)
471                read_non_whitespace(stream_data)
472                stream_data.seek(-1, 1)
473                offset = NumberObject.read_from_stream(stream_data)
474                read_non_whitespace(stream_data)
475                stream_data.seek(-1, 1)
476                if objnum < 0 or offset < 0 or first_offset + offset > stream_length:
477                    # An object number or target position outside the stream
478                    # cannot be valid; skipping the entry avoids leaking a
479                    # ValueError/OverflowError from a bad seek while keeping
480                    # the other entries.
481                    if self.strict:
482                        raise PdfReadError(
483                            f"Invalid object number ({objnum}) or offset ({offset}) "
484                            f"in object stream {stmnum}."
485                        )
486                    logger_warning(
487                        (
488                            "Invalid object number (%(objnum)d) or offset (%(offset)d) "
489                            "in object stream %(stmnum)d; skipping the entry."
490                        ),
491                        source=__name__,
492                        objnum=objnum,
493                        offset=offset,
494                        stmnum=stmnum,
495                    )
496                    continue
497                int_offset = int(offset)
498                if int_offset <= last_offset:
499                    raise PdfReadError(f"Invalid offset {offset} in object stream {stmnum}.")
500                last_offset = int_offset
501                obj_index.append((int(objnum), int_offset))
502
503            # Phase 2: Parse each object and cache it.
504            target_obj: PdfObject = NullObject()
505            found = False
506            for i, (obj_num, obj_offset) in enumerate(obj_index):
507                # Skip objects already in the cache.
508                cached = self.cache_get_indirect_object(0, obj_num)
509                if cached is not None:
510                    if obj_num == indirect_reference.idnum:
511                        target_obj = cached
512                        found = True
513                    continue
514
515                stream_data.seek(first_offset + obj_offset, 0)
516
517                # To cope with case where the 'pointer' is on a white space
518                read_non_whitespace(stream_data)
519                stream_data.seek(-1, 1)
520
521                try:
522                    obj = read_object(stream_data, self)
523                except PdfStreamError as exc:
524                    # Stream object cannot be read. Normally, a critical error, but
525                    # Adobe Reader doesn't complain, so continue (in strict mode?)
526                    logger_warning(
527                        "Invalid stream (index %(index)d) within object %(obj_num)d 0: %(exc)s",
528                        source=__name__,
529                        index=i,
530                        obj_num=obj_num,
531                        exc=exc,
532                    )
533                    if self.strict:  # pragma: no cover
534                        raise PdfReadError(
535                            f"Cannot read object stream: {exc}"
536                        ) from exc  # pragma: no cover
537                    obj = NullObject()  # pragma: no cover
538
539                # Only cache if this stream is the authoritative source for the object.
540                # Incremental updates may override objects originally in the stream;
541                # caching those stale versions would shadow the newer xref entry.
542                authoritative_stm, _idx = self.xref_objStm.get(obj_num, (None, None))
543                if authoritative_stm == stmnum:
544                    self.cache_indirect_object(0, obj_num, obj)
545
546                if obj_num == indirect_reference.idnum:
547                    target_obj = obj
548                    found = True
549
550            if not found and self.strict:  # pragma: no cover
551                raise PdfReadError(
552                    "This is a fatal error in strict mode."
553                )  # pragma: no cover
554            return target_obj
555        finally:
556            self._object_stream_resolution_stack.pop()
557
558    def get_object(
559        self, indirect_reference: int | IndirectObject
560    ) -> PdfObject | None:
561        if isinstance(indirect_reference, int):
562            indirect_reference = IndirectObject(indirect_reference, 0, self)
563
564        retval = self.cache_get_indirect_object(
565            indirect_reference.generation, indirect_reference.idnum
566        )
567        key = (
568            indirect_reference.generation,
569            indirect_reference.idnum,
570        )
571        if key in self.resolved_objects:
572            return retval
573
574        if (
575            indirect_reference.generation == 0
576            and indirect_reference.idnum in self.xref_objStm
577        ):
578            retval = self._get_object_from_stream(indirect_reference)
579        elif (
580            indirect_reference.generation in self.xref
581            and indirect_reference.idnum in self.xref[indirect_reference.generation]
582        ):
583            if self.xref_free_entry.get(indirect_reference.generation, {}).get(
584                indirect_reference.idnum, False
585            ):
586                return NullObject()
587            start = self.xref[indirect_reference.generation][indirect_reference.idnum]
588            self.stream.seek(start, 0)
589            try:
590                idnum, generation = self.read_object_header(self.stream)
591                if (
592                    idnum != indirect_reference.idnum
593                    or generation != indirect_reference.generation
594                ):
595                    raise PdfReadError("Not matching, we parse the file for it")
596            except MemoryError:  # pragma: no cover  # TODO: BLE001
597                raise
598            except Exception:
599                buf = get_stream_data(self.stream)
600                m = re.search(
601                    rf"\s{indirect_reference.idnum}\s+{indirect_reference.generation}\s+obj".encode(),
602                    buf,
603                )
604                if m is not None:
605                    logger_warning(
606                        "Object ID %(idnum)d,%(generation)d ref repaired",
607                        source=__name__,
608                        idnum=indirect_reference.idnum,
609                        generation=indirect_reference.generation,
610                    )
611                    self.xref[indirect_reference.generation][
612                        indirect_reference.idnum
613                    ] = (m.start(0) + 1)
614                    self.stream.seek(m.start(0) + 1)
615                    idnum, generation = self.read_object_header(self.stream)
616                else:
617                    idnum = -1
618                    generation = -1  # exception will be raised below
619            if idnum != indirect_reference.idnum and self.xref_index:
620                # xref table probably had bad indexes due to not being zero-indexed
621                if self.strict:
622                    raise PdfReadError(
623                        f"Expected object ID ({indirect_reference.idnum} {indirect_reference.generation}) "
624                        f"does not match actual ({idnum} {generation}); "
625                        "xref table not zero-indexed."
626                    )
627                # xref table is corrected in non-strict mode
628            elif idnum != indirect_reference.idnum and self.strict:
629                # some other problem
630                raise PdfReadError(
631                    f"Expected object ID ({indirect_reference.idnum} {indirect_reference.generation}) "
632                    f"does not match actual ({idnum} {generation})."
633                )
634            if self.strict:
635                assert generation == indirect_reference.generation
636
637            current_object = (indirect_reference.idnum, indirect_reference.generation)
638            if current_object in self._known_objects:
639                raise LimitReachedError(f"Detected loop with self reference for {indirect_reference!r}.")
640            self._known_objects.add(current_object)
641            retval = read_object(self.stream, self)
642            self._known_objects.remove(current_object)
643
644            # override encryption is used for the /Encrypt dictionary
645            if not self._override_encryption and self._encryption is not None:
646                # if we don't have the encryption key:
647                if not self._encryption.is_decrypted():
648                    raise FileNotDecryptedError("File has not been decrypted")
649                # otherwise, decrypt here...
650                retval = self._encryption.decrypt_object(
651                    retval, indirect_reference.idnum, indirect_reference.generation,
652                    strict=self.strict,
653                )
654        else:
655            buf = get_stream_data(self.stream)
656            m = re.search(
657                rf"\s{indirect_reference.idnum}\s+{indirect_reference.generation}\s+obj".encode(),
658                buf,
659            )
660            if m is not None:
661                logger_warning(
662                    "Object %(idnum)d %(generation)d found",
663                    source=__name__,
664                    idnum=indirect_reference.idnum,
665                    generation=indirect_reference.generation,
666                )
667                if indirect_reference.generation not in self.xref:
668                    self.xref[indirect_reference.generation] = {}
669                self.xref[indirect_reference.generation][indirect_reference.idnum] = (
670                    m.start(0) + 1
671                )
672                self.stream.seek(m.end(0) + 1)
673                skip_over_whitespace(self.stream)
674                self.stream.seek(-1, 1)
675                retval = read_object(self.stream, self)
676
677                # override encryption is used for the /Encrypt dictionary
678                if not self._override_encryption and self._encryption is not None:
679                    # if we don't have the encryption key:
680                    if not self._encryption.is_decrypted():
681                        raise FileNotDecryptedError("File has not been decrypted")
682                    # otherwise, decrypt here...
683                    retval = self._encryption.decrypt_object(
684                        retval, indirect_reference.idnum, indirect_reference.generation,
685                        strict=self.strict,
686                    )
687            else:
688                logger_warning(
689                    "Object %(idnum)d %(generation)d not defined.",
690                    source=__name__,
691                    idnum=indirect_reference.idnum,
692                    generation=indirect_reference.generation,
693                )
694                if self.strict:
695                    raise PdfReadError("Could not find object.")
696        # For ObjStm objects, _get_object_from_stream already cached
697        # the result during batch parsing; skip the redundant cache write
698        # to avoid "Overwriting cache" warnings. For non-ObjStm objects
699        # (including encrypted ones that need decrypted values cached),
700        # always write.
701        if not (
702            indirect_reference.generation == 0
703            and indirect_reference.idnum in self.xref_objStm
704        ):
705            self.cache_indirect_object(
706                indirect_reference.generation, indirect_reference.idnum, retval
707            )
708        return retval
709
710    def read_object_header(self, stream: StreamType) -> tuple[int, int]:
711        # Should never be necessary to read out whitespace, since the
712        # cross-reference table should put us in the right spot to read the
713        # object header. In reality some files have stupid cross-reference
714        # tables that are off by whitespace bytes.
715        skip_over_comment(stream)
716        extra = skip_over_whitespace(stream)
717        stream.seek(-1, 1)
718        idnum = read_until_whitespace(stream, max_bytes=IndirectObject._MAXIMUM_PART_LENGTH, strict=self.strict)
719        extra |= skip_over_whitespace(stream)
720        stream.seek(-1, 1)
721        generation = read_until_whitespace(stream, max_bytes=IndirectObject._MAXIMUM_PART_LENGTH, strict=self.strict)
722        extra |= skip_over_whitespace(stream)
723        stream.seek(-1, 1)
724
725        # although it's not used, it might still be necessary to read
726        _obj = stream.read(3)
727
728        read_non_whitespace(stream)
729        stream.seek(-1, 1)
730        if extra and self.strict:
731            logger_warning(
732                "Superfluous whitespace found in object header %(idnum)r %(generation)r",
733                source=__name__,
734                idnum=idnum,
735                generation=generation,
736            )
737
738        try:
739            return int(idnum), int(generation)
740        except (ValueError, OverflowError) as exception:
741            # Only raise a ValueError here as other types would break future processing.
742            raise ValueError(
743                f"Invalid indirect object reference ({idnum!r} {generation!r} R): {exception}"
744            ) from exception
745
746    def cache_get_indirect_object(
747        self, generation: int, idnum: int
748    ) -> PdfObject | None:
749        try:
750            return self.resolved_objects.get((generation, idnum))
751        except RecursionError as exception:  # pragma: no cover
752            raise PdfReadError("Maximum recursion depth reached.") from exception  # pragma: no cover
753
754    def cache_indirect_object(
755        self, generation: int, idnum: int, obj: PdfObject | None
756    ) -> PdfObject | None:
757        if (generation, idnum) in self.resolved_objects:
758            msg = "Overwriting cache for %(generation)d %(idnum)d"
759            values = {"generation": generation, "idnum": idnum}
760            if self.strict:
761                raise PdfReadError(msg % values)
762            logger_warning(msg, source=__name__, **values)
763        self.resolved_objects[(generation, idnum)] = obj
764        if obj is not None:
765            obj.indirect_reference = IndirectObject(idnum, generation, self)
766        return obj
767
768    def _replace_object(self, indirect_reference: IndirectObject, obj: PdfObject) -> PdfObject:
769        # function reserved for future development
770        if indirect_reference.pdf != self:
771            raise ValueError("Cannot update PdfReader with external object")
772        if (indirect_reference.generation, indirect_reference.idnum) not in self.resolved_objects:
773            raise ValueError("Cannot find referenced object")
774        self.resolved_objects[(indirect_reference.generation, indirect_reference.idnum)] = obj
775        obj.indirect_reference = indirect_reference
776        return obj
777
778    def read(self, stream: StreamType) -> None:
779        """
780        Read and process the PDF stream, extracting necessary data.
781
782        Args:
783            stream: The PDF file stream.
784
785        """
786        self._basic_validation(stream)
787        self._find_eof_marker(stream)
788        startxref = self._find_startxref_pos(stream)
789        if startxref < 0:
790            # A negative offset cannot point into the file. Treat it like the
791            # zero case (#3157) so the xref table is repaired instead of
792            # leaking a ValueError from a negative seek.
793            logger_warning(
794                "Negative startxref pointer (%(startxref)d), treating it as zero.",
795                source=__name__,
796                startxref=startxref,
797            )
798            startxref = 0
799        self._startxref = startxref
800
801        # check and eventually correct the startxref only if not strict
802        xref_issue_nr = self._get_xref_issues(stream, startxref)
803        if xref_issue_nr != 0:
804            if self.strict and xref_issue_nr:
805                raise PdfReadError("Broken xref table")
806            logger_warning(
807                "incorrect startxref pointer(%(xref_issue_nr)d)",
808                source=__name__,
809                xref_issue_nr=xref_issue_nr,
810            )
811
812        # read all cross-reference tables and their trailers
813        self._read_xref_tables_and_trailers(stream, startxref, xref_issue_nr)
814
815        # if not zero-indexed, verify that the table is correct; change it if necessary
816        if self.xref_index and not self.strict:
817            loc = stream.tell()
818            for gen, xref_entry in self.xref.items():
819                if gen == 65535:
820                    continue
821                xref_k = sorted(
822                    xref_entry.keys()
823                )  # ensure ascending to prevent damage
824                for xref_id in xref_k:
825                    stream.seek(xref_entry[xref_id], 0)
826                    try:
827                        pid, _pgen = self.read_object_header(stream)
828                    except ValueError:
829                        self._rebuild_xref_table(stream)
830                        break
831                    if pid == xref_id - self.xref_index:
832                        # fixing index item per item is required for revised PDF.
833                        self.xref[gen][pid] = self.xref[gen][xref_id]
834                        del self.xref[gen][xref_id]
835                    # if not, then either it's just plain wrong, or the
836                    # non-zero-index is actually correct
837            stream.seek(loc, 0)  # return to where it was
838
839        # remove wrong objects (not pointing to correct structures) - cf #2326
840        if not self.strict:
841            loc = stream.tell()
842            for gen, xref_entry in self.xref.items():
843                if gen == 65535:
844                    continue
845                ids = list(xref_entry.keys())
846                for xref_id in ids:
847                    stream.seek(xref_entry[xref_id], 0)
848                    try:
849                        self.read_object_header(stream)
850                    except ValueError:
851                        logger_warning(
852                            "Ignoring wrong pointing object %(id)d %(gen)d (offset %(offset)d)",
853                            source=__name__,
854                            id=xref_id,
855                            gen=gen,
856                            offset=xref_entry[xref_id],
857                        )
858                        del xref_entry[xref_id]  # we can delete the id, we are parsing ids
859            stream.seek(loc, 0)  # return to where it was
860
861    def _basic_validation(self, stream: StreamType) -> None:
862        """Ensure the stream is valid and not empty."""
863        stream.seek(0, os.SEEK_SET)
864        try:
865            header_byte = stream.read(5)
866        except UnicodeDecodeError as exception:
867            raise UnsupportedOperation("cannot read header") from exception
868        if header_byte == b"":
869            raise EmptyFileError("Cannot read an empty file")
870        if header_byte != b"%PDF-":
871            if self.strict:
872                raise PdfReadError(
873                    f"PDF starts with '{header_byte.decode('utf8')}', "
874                    "but '%PDF-' expected"
875                )
876            logger_warning("invalid pdf header: %(header_byte)r", source=__name__, header_byte=header_byte)
877        stream.seek(0, os.SEEK_END)
878
879    def _find_eof_marker(self, stream: StreamType) -> None:
880        """
881        Jump to the %%EOF marker.
882
883        According to the specs, the %%EOF marker should be at the very end of
884        the file. Hence for standard-compliant PDF documents this function will
885        read only the last part (DEFAULT_BUFFER_SIZE).
886
887        Producers that omit the line break before the marker (``startxref
888        256%%EOF`` or ``256%%EOF``) are accepted as well (#4127).
889        """
890        header_size = 8  # to parse whole file, Header is e.g. '%PDF-1.6'
891        line = b""
892        first = True
893        # Bytes of `line` end at this position. An inline %%EOF therefore
894        # begins at end_position - len(line) + marker_index.
895        end_position = stream.tell()
896        while True:
897            marker_index = line.find(b"%%EOF")
898            if marker_index == 0:
899                break
900            if marker_index > 0 and first:
901                # Only the trailing line is allowed to carry an inline marker.
902                # Earlier lines keep the historical "starts with %%EOF" rule so
903                # a %%EOF buried in stream data is not treated as the trailer.
904                # Leading whitespace in front of the marker is ignored.
905                if line[:marker_index].lstrip(WHITESPACES_AS_BYTES):
906                    logger_warning(
907                        "EOF marker not at start of line",
908                        source=__name__,
909                    )
910                    stream.seek(end_position - len(line) + marker_index)
911                break
912            if line != b"" and first:
913                if any(
914                    line.strip().endswith(tr) for tr in (b"%%EO", b"%%E", b"%%", b"%")
915                ):
916                    # Consider the file as truncated while
917                    # having enough confidence to carry on.
918                    logger_warning("EOF marker seems truncated", source=__name__)
919                    break
920                first = False
921            if b"startxref" in line:
922                logger_warning(
923                    "CAUTION: startxref found while searching for %%EOF. "
924                    "The file might be truncated and some data might not be read.",
925                    source=__name__,
926                )
927            if stream.tell() < header_size:
928                if self.strict:
929                    raise PdfReadError("EOF marker not found")
930                logger_warning("EOF marker not found", source=__name__)
931            end_position = stream.tell()
932            line = read_previous_line(stream)
933
934    def _find_startxref_pos(self, stream: StreamType) -> int:
935        """
936        Find startxref entry - the location of the xref table.
937
938        Args:
939            stream:
940
941        Returns:
942            The bytes offset
943
944        """
945        line = read_previous_line(stream)
946        # Some producers append further %%EOF markers below the one that
947        # closes the last revision (#4008). _find_eof_marker() stops at the
948        # very last of them, so the line above it is another marker rather
949        # than the offset. Skip that trailing run to reach the real offset;
950        # the revision being read is unchanged, only the marker padding is
951        # ignored.
952        duplicate_markers = 0
953        while line.startswith(b"%%EOF") and stream.tell() > 0:
954            if duplicate_markers == self._MAX_STARTXREF_RECOVERY_LINES:
955                break
956            line = read_previous_line(stream)
957            duplicate_markers += 1
958        if duplicate_markers:
959            logger_warning(
960                "Duplicate %%EOF marker(s) found, skipping them", source=__name__
961            )
962        try:
963            startxref = int(line)
964        except ValueError as exception:  # pragma: no cover
965            # 'startxref' may be on the same line as the location
966            if not line.startswith(b"startxref"):
967                raise PdfReadError("startxref not found") from exception
968            value = line[9:].strip()
969            if not self._is_valid_startxref_value(value):
970                raise PdfReadError("startxref not found") from exception
971            startxref = int(value)
972            logger_warning("startxref on same line as offset", source=__name__)
973        else:
974            line = read_previous_line(stream)
975            if not line.startswith(b"startxref"):
976                # The 'startxref' keyword expected just above the offset is
977                # missing or corrupt (for example a truncated 'tartxref').
978                # Some producers append a broken trailing cross-reference
979                # pointer while an earlier, intact 'startxref' from a previous
980                # revision is still present. Recovering from this violates the
981                # standard, so only attempt it in non-strict mode (#3238).
982                if self.strict:
983                    raise PdfReadError("startxref not found")
984                startxref = self._find_previous_startxref_pos(stream)
985        return startxref
986
987    # Upper bound on the number of lines _find_previous_startxref_pos scans
988    # backwards while recovering a corrupt trailing startxref pointer. Kept
989    # fixed and non-configurable so a crafted file cannot trigger an unbounded
990    # backwards scan.
991    _MAX_STARTXREF_RECOVERY_LINES = 1000
992
993    @staticmethod
994    def _is_valid_startxref_value(value: bytes) -> bool:
995        if re.fullmatch(rb"[+-]?[0-9]+(?:_[0-9]+)*", value) is None:
996            return False
997        # Respect Python's integer conversion limit without attempting int().
998        max_digits = getattr(sys, "get_int_max_str_digits", lambda: 0)()
999        digits = value.lstrip(b"+-").replace(b"_", b"")
1000        return not max_digits or len(digits) <= max_digits
1001
1002    @classmethod
1003    def _find_previous_startxref_pos(cls, stream: StreamType) -> int:
1004        """
1005        Recover the most recent intact ``startxref`` pointer by scanning
1006        backwards from the current position.
1007
1008        This is used as a fallback when the ``startxref`` keyword belonging to
1009        the final ``%%EOF`` is corrupt (#3238). The offset always appears on
1010        the line directly below the keyword, so the value read immediately
1011        before encountering ``startxref`` (while moving backwards) is returned.
1012        At most ``_MAX_STARTXREF_RECOVERY_LINES`` lines are inspected.
1013
1014        Args:
1015            stream: The PDF byte stream, positioned just above the corrupt
1016                trailing pointer.
1017
1018        Returns:
1019            The bytes offset of the recovered ``startxref``.
1020
1021        """
1022        offset: int | None = None
1023        for _ in range(cls._MAX_STARTXREF_RECOVERY_LINES):
1024            if stream.tell() <= 0:
1025                break
1026            line = read_previous_line(stream)
1027            if not line.startswith(b"startxref"):
1028                try:
1029                    offset = int(line)
1030                except ValueError:
1031                    offset = None
1032                continue
1033            if len(line) > 9:
1034                # 'startxref' on the same line as the offset
1035                value = line[9:].strip()
1036                if not cls._is_valid_startxref_value(value):
1037                    continue
1038                return int(value)
1039            if offset is not None:
1040                logger_warning(
1041                    "found startxref pointing to a previous revision after "
1042                    "a corrupt one",
1043                    source=__name__,
1044                )
1045                return offset
1046            break
1047        raise PdfReadError("startxref not found")
1048
1049    def _load_recovery_cache(self, data: bytes) -> dict[int, tuple[int, int]]:
1050        cache = {}
1051        for object_number, generation_number, object_start in self._find_pdf_objects(data):
1052            if object_number in cache:
1053                # Always use the first match.
1054                continue
1055            cache[object_number] = (object_start, generation_number)
1056        return cache
1057
1058    def _read_standard_xref_table__handle_size(self, stream: StreamType) -> int | None:
1059        size = cast(int, read_object(stream, self))
1060        if not isinstance(size, int):
1061            logger_warning(
1062                "Invalid/Truncated xref table. Rebuilding it.",
1063                source=__name__,
1064            )
1065            self._rebuild_xref_table(stream)
1066            stream.read()
1067            return None
1068        # A valid entry has a size of 20 bytes.
1069        size_limit = get_stream_size(stream) // 20
1070        if size > size_limit:
1071            raise LimitReachedError(f"Declared size {size} exceeds allowed limit of {size_limit}!")
1072        return size
1073
1074    def _read_standard_xref_table(self, stream: StreamType) -> None:
1075        # standard cross-reference table
1076        ref = stream.read(3)
1077        if ref != b"ref":
1078            raise PdfReadError("xref table read error")
1079        read_non_whitespace(stream)
1080        stream.seek(-1, 1)
1081        first_time = True  # check if the first time looking at the xref table
1082        recovery_cache: dict[int, tuple[int, int]] | None = None
1083        previous_position: int | None = None
1084        while True:
1085            num = cast(int, read_object(stream, self))
1086            if first_time and num != 0:
1087                self.xref_index = num
1088                if self.strict:
1089                    logger_warning(
1090                        "Xref table not zero-indexed. ID numbers for objects will be corrected.",
1091                        source=__name__,
1092                    )
1093                    # if table not zero indexed, could be due to error from when PDF was created
1094                    # which will lead to mismatched indices later on, only warned and corrected if self.strict==True
1095            first_time = False
1096            read_non_whitespace(stream)
1097            stream.seek(-1, 1)
1098            size = self._read_standard_xref_table__handle_size(stream)
1099            if size is None:
1100                return
1101            read_non_whitespace(stream)
1102            stream.seek(-1, 1)
1103            cnt = 0
1104            while cnt < size:
1105                line = stream.read(20)
1106                if not line:
1107                    raise PdfReadError("Unexpected empty line in Xref table.")
1108
1109                # It's very clear in section 3.4.3 of the PDF spec
1110                # that all cross-reference table lines are a fixed
1111                # 20 bytes (as of PDF 1.7). However, some files have
1112                # 21-byte entries (or more) due to the use of \r\n
1113                # (CRLF) EOL's. Detect that case, and adjust the line
1114                # until it does not begin with a \r (CR) or \n (LF).
1115                while line[0] in b"\x0D\x0A":
1116                    stream.seek(-20 + 1, 1)
1117                    line = stream.read(20)
1118                    if len(line) != 20:
1119                        raise PdfReadError("Unexpected EOF in Xref table.")
1120
1121                # On the other hand, some malformed PDF files
1122                # use a single character EOL without a preceding
1123                # space. Detect that case, and seek the stream
1124                # back one character (0-9 means we've bled into
1125                # the next xref entry, t means we've bled into the
1126                # text "trailer"):
1127                if line[-1] in b"0123456789t":
1128                    stream.seek(-1, 1)
1129
1130                try:
1131                    offset_b, generation_b = line[:16].split(b" ")
1132                    entry_type_b = line[17:18]
1133
1134                    offset, generation = int(offset_b), int(generation_b)
1135                except MemoryError:  # pragma: no cover  # TODO: BLE001
1136                    raise
1137                except Exception:
1138                    if recovery_cache is None:
1139                        buf = get_stream_data(stream)
1140                        recovery_cache = self._load_recovery_cache(buf)
1141
1142                    if num not in recovery_cache:
1143                        logger_warning(
1144                            "entry %(num)d in Xref table invalid; object not found",
1145                            source=__name__,
1146                            num=num,
1147                        )
1148                        generation = 65535
1149                        offset = -1
1150                        entry_type_b = b"f"
1151                    else:
1152                        logger_warning(
1153                            "entry %(num)d in Xref table invalid but object found",
1154                            source=__name__,
1155                            num=num,
1156                        )
1157                        generation, offset = recovery_cache[num]
1158                        entry_type_b = b"n"
1159
1160                if generation not in self.xref:
1161                    self.xref[generation] = {}
1162                    self.xref_free_entry[generation] = {}
1163                if num in self.xref[generation]:
1164                    # It really seems like we should allow the last
1165                    # xref table in the file to override previous
1166                    # ones. Since we read the file backwards, assume
1167                    # any existing key is already set correctly.
1168                    pass
1169                else:
1170                    if entry_type_b == b"n":
1171                        self.xref[generation][num] = offset
1172                    try:
1173                        self.xref_free_entry[generation][num] = entry_type_b == b"f"
1174                    except MemoryError:  # pragma: no cover  # TODO: BLE001
1175                        raise
1176                    except Exception:
1177                        pass
1178                    try:
1179                        self.xref_free_entry[65535][num] = entry_type_b == b"f"
1180                    except MemoryError:  # pragma: no cover  # TODO: BLE001
1181                        raise
1182                    except Exception:
1183                        pass
1184                cnt += 1
1185                num += 1
1186            read_non_whitespace(stream)
1187            stream.seek(-1, 1)
1188            # Skip any PDF comments between xref entries and the trailer
1189            # keyword. Some PDF producers (e.g. Vectorizer.AI) insert
1190            # comments here which are legal per the PDF spec (§7.2.3).
1191            while stream.read(1) == b"%":
1192                stream.seek(-1, 1)
1193                skip_over_comment(stream)
1194                read_non_whitespace(stream)
1195                stream.seek(-1, 1)
1196            stream.seek(-1, 1)
1197            trailer_tag = stream.read(7)
1198            if trailer_tag == b"trailer":
1199                break
1200
1201            # More xrefs should move the parser to another section.
1202            stream.seek(-7, 1)
1203
1204            # Detect a repeated read at the same position.
1205            rewound_position = stream.tell()
1206            if rewound_position == previous_position:
1207                raise PdfReadError(
1208                    f"Xref parsing stuck at position {rewound_position}: {trailer_tag!r}"
1209                )
1210            previous_position = rewound_position
1211
1212    def _read_xref_tables_and_trailers(
1213        self, stream: StreamType, startxref: int | None, xref_issue_nr: int
1214    ) -> None:
1215        """Read the cross-reference tables and trailers in the PDF stream."""
1216        self.xref = {}
1217        self.xref_free_entry = {}
1218        self.xref_objStm = {}
1219        self._xref_stream_entry_count = 0
1220        self.trailer = DictionaryObject()
1221        visited_xref_offsets: set[int] = set()
1222        while startxref is not None:
1223            # Detect circular /Prev references in the xref chain
1224            if startxref in visited_xref_offsets:
1225                logger_warning(
1226                    "Circular xref chain detected at offset %(startxref)d, stopping",
1227                    source=__name__,
1228                    startxref=startxref,
1229                )
1230                break
1231            visited_xref_offsets.add(startxref)
1232            # load the xref table
1233            stream.seek(startxref, 0)
1234            x = stream.read(1)
1235            if x in b"\r\n":
1236                x = stream.read(1)
1237            if x == b"x":
1238                startxref = self._read_xref(stream)
1239            elif xref_issue_nr:
1240                try:
1241                    self._rebuild_xref_table(stream)
1242                    break
1243                except MemoryError:  # pragma: no cover  # TODO: BLE001
1244                    raise
1245                except Exception:
1246                    xref_issue_nr = 0
1247            elif x.isdigit():
1248                try:
1249                    xrefstream = self._read_pdf15_xref_stream(stream)
1250                except Exception as exception:  # pragma: no cover
1251                    if TrailerKeys.ROOT in self.trailer:
1252                        logger_warning(
1253                            "Previous trailer cannot be read: %(args)s",
1254                            source=__name__,
1255                            args=exception.args,
1256                        )
1257                        break
1258                    raise PdfReadError(f"Trailer cannot be read: {exception!s}") from exception  # pragma: no cover
1259                self._process_xref_stream(xrefstream)
1260                if "/Prev" in xrefstream:
1261                    startxref = cast(int, xrefstream["/Prev"])
1262                else:
1263                    break
1264            else:
1265                startxref = self._read_xref_other_error(stream, startxref)
1266
1267    # The trailer keys a PDF 1.5+ cross-reference stream carries in place of a
1268    # `trailer` keyword (PDF 2.0 specification, table 17).
1269    _XREF_STREAM_TRAILER_KEYS = (
1270        TrailerKeys.ROOT, TrailerKeys.ENCRYPT, TrailerKeys.INFO, TrailerKeys.ID, TrailerKeys.SIZE
1271    )
1272
1273    def _process_xref_stream(self, xrefstream: DictionaryObject) -> None:
1274        """Process and handle the xref stream."""
1275        for key in self._XREF_STREAM_TRAILER_KEYS:
1276            if key in xrefstream and key not in self.trailer:
1277                self.trailer[NameObject(key)] = xrefstream.raw_get(key)
1278        if "/XRefStm" in xrefstream:
1279            p = self.stream.tell()
1280            self.stream.seek(cast(int, xrefstream["/XRefStm"]) + 1, 0)
1281            self._read_pdf15_xref_stream(self.stream)
1282            self.stream.seek(p, 0)
1283
1284    def _read_xref(self, stream: StreamType) -> int | None:
1285        self._read_standard_xref_table(stream)
1286        if stream.read(1) == b"":
1287            return None
1288        stream.seek(-1, 1)
1289        read_non_whitespace(stream)
1290        stream.seek(-1, 1)
1291        new_trailer = cast(dict[str, Any], read_object(stream, self))
1292        for key, value in new_trailer.items():
1293            if key not in self.trailer:
1294                self.trailer[key] = value
1295        if "/XRefStm" in new_trailer:
1296            p = stream.tell()
1297            stream.seek(cast(int, new_trailer["/XRefStm"]) + 1, 0)
1298            try:
1299                self._read_pdf15_xref_stream(stream)
1300            except MemoryError:  # pragma: no cover  # TODO: BLE001
1301                raise
1302            except LimitReachedError:
1303                # Do not continue on reaching the resource limits.
1304                raise
1305            except Exception:
1306                logger_warning(
1307                    "XRef object at %(xref_stm)d can not be read, some object may be missing",
1308                    source=__name__,
1309                    xref_stm=int(new_trailer["/XRefStm"]),
1310                )
1311            stream.seek(p, 0)
1312        if "/Prev" in new_trailer:
1313            return cast(int, new_trailer["/Prev"])
1314        return None
1315
1316    def _read_xref_other_error(
1317        self, stream: StreamType, startxref: int
1318    ) -> int | None:
1319        # some PDFs have /Prev=0 in the trailer, instead of no /Prev
1320        if startxref == 0:
1321            if self.strict:
1322                raise PdfReadError(
1323                    "/Prev=0 in the trailer (try opening with strict=False)"
1324                )
1325            logger_warning(
1326                "/Prev=0 in the trailer - assuming there is no previous xref table",
1327                source=__name__,
1328            )
1329            return None
1330        # bad xref character at startxref. Let's see if we can find
1331        # the xref table nearby, as we've observed this error with an
1332        # off-by-one before.
1333        stream.seek(-11, 1)
1334        tmp = stream.read(20)
1335        xref_loc = tmp.find(b"xref")
1336        if xref_loc != -1:
1337            startxref -= 10 - xref_loc
1338            return startxref
1339        # No explicit xref table, try finding a cross-reference stream.
1340        stream.seek(startxref, 0)
1341        for look in range(25):  # value extended to cope with more linearized files
1342            if stream.read(1).isdigit():
1343                # This is not a standard PDF, consider adding a warning
1344                startxref += look
1345                return startxref
1346        # no xref table found at specified location
1347        if "/Root" in self.trailer and not self.strict:
1348            # if Root has been already found, just raise warning
1349            logger_warning("Invalid parent xref., rebuild xref", source=__name__)
1350            try:
1351                self._rebuild_xref_table(stream)
1352            except Exception as exception:  # pragma: no cover
1353                raise PdfReadError("Cannot rebuild xref") from exception  # pragma: no cover
1354            return None
1355        raise PdfReadError("Could not find xref table at specified location")
1356
1357    def _sanitize_pdf15_xref_stream_index_pairs(
1358            self, index_pairs: list[int], entry_sizes: list[int], xref_stream: StreamObject
1359    ) -> list[int]:
1360        # `entry_sizes` holds the byte widths for the entries. Summing determines the total number of bytes per entry.
1361        # We expect up to 3 values. `min_entry_bytes` will be the smallest plausible size of one xref entry.
1362        min_entry_bytes = sum(int(entry_sizes[i]) for i in range(min(len(entry_sizes), 3)))
1363        if min_entry_bytes == 0:
1364            message = "Cross-reference stream encodes no entry data."
1365            if self.strict:
1366                raise PdfStreamError(message)
1367            logger_warning(message, source=__name__)
1368            return []
1369
1370        # maximum number of entries that could physically fit
1371        max_entries = len(xref_stream.get_data()) // min_entry_bytes + 1
1372
1373        result = []
1374        total = 0
1375
1376        for index, pair_value in enumerate(index_pairs):
1377            pair_value_int = int(pair_value)
1378
1379            # `index_pairs` has the format `[start0, count0, start1, count1, ...]`
1380            # Only modify the counts here, but keep the start values.
1381            if index % 2 == 1:
1382                if pair_value_int < 0:
1383                    if self.strict:
1384                        raise PdfStreamError(f"Negative XRef count {pair_value_int}.")
1385                    logger_warning(
1386                        "Negative XRef count %(count)d, using 0.",
1387                        source=__name__,
1388                        count=pair_value_int,
1389                    )
1390                    pair_value_int = 0
1391
1392                if total + pair_value_int > max_entries:
1393                    if self.strict:
1394                        raise LimitReachedError(
1395                            f"Total XRef entries {total + pair_value_int} exceed maximum allowed value {max_entries}."
1396                        )
1397                    new_v = max(0, max_entries - total)
1398                    logger_warning(
1399                        "Clamping XRef count from %(old_count)d to %(new_count)d to fit stream size.",
1400                        source=__name__,
1401                        old_count=pair_value_int,
1402                        new_count=new_v,
1403                    )
1404                    pair_value_int = new_v
1405
1406                total += pair_value_int
1407
1408            result.append(pair_value_int)
1409
1410        return result
1411
1412    def _read_pdf15_xref_stream(self, stream: StreamType) -> StreamObject:
1413        """Read the cross-reference stream for PDF 1.5+."""
1414        stream.seek(-1, 1)
1415        stream_idnum, stream_generation = self.read_object_header(stream)
1416        xref_stream = cast(StreamObject, read_object(stream, self))
1417        if cast(str, xref_stream["/Type"]) != "/XRef":
1418            raise PdfReadError(f"Unexpected type {xref_stream['/Type']!r}")
1419        self.cache_indirect_object(stream_generation, stream_idnum, xref_stream)
1420
1421        # Index pairs specify the subsections in the dictionary.
1422        # If none, create one subsection that spans everything.
1423        if "/Size" not in xref_stream:
1424            # According to table 17 of the PDF 2.0 specification, this key is required.
1425            raise PdfReadError(f"Size missing from XRef stream {xref_stream!r}!")
1426        index_pairs = xref_stream.get("/Index", [0, xref_stream["/Size"]])
1427
1428        entry_sizes = cast(list[int], xref_stream.get("/W"))
1429        assert len(entry_sizes) >= 3
1430        if self.strict and len(entry_sizes) > 3:
1431            raise PdfReadError(f"Too many entry sizes: {entry_sizes}")
1432        index_pairs = self._sanitize_pdf15_xref_stream_index_pairs(
1433            index_pairs=index_pairs, entry_sizes=entry_sizes, xref_stream=xref_stream
1434        )
1435
1436        self._xref_stream_entry_count += sum(index_pairs[1::2])
1437        if self._xref_stream_entry_count > self._xref_stream_maximum_entries:
1438            raise LimitReachedError(
1439                f"Maximum XRef stream entry limit reached: "
1440                f"{self._xref_stream_entry_count} > {self._xref_stream_maximum_entries}."
1441            )
1442
1443        stream_data = BytesIO(xref_stream.get_data())
1444        # Do not keep the decoded data cached, as the stream remains in resolved_objects.
1445        if isinstance(xref_stream, EncodedStreamObject):
1446            xref_stream.decoded_self = None
1447
1448        def get_entry(i: int) -> int | tuple[int, ...]:
1449            # Reads the correct number of bytes for each entry. See the
1450            # discussion of the W parameter in PDF spec table 17.
1451            if entry_sizes[i] > 0:
1452                d = stream_data.read(entry_sizes[i])
1453                return convert_to_int(d, entry_sizes[i])
1454
1455            # PDF Spec Table 17: A value of zero for an element in the
1456            # W array indicates...the default value shall be used
1457            if i == 0:
1458                return 1  # First value defaults to 1
1459            return 0
1460
1461        def used_before(num: int, generation: int | tuple[int, ...]) -> bool:
1462            # We move backwards through the xrefs, don't replace any.
1463            return num in self.xref.get(generation, []) or num in self.xref_objStm  # type: ignore[arg-type]
1464
1465        # Iterate through each subsection
1466        self._read_xref_subsections(index_pairs, get_entry, used_before)
1467        return xref_stream
1468
1469    @staticmethod
1470    def _get_xref_issues(stream: StreamType, startxref: int) -> int:
1471        """
1472        Return an int which indicates an issue. 0 means there is no issue.
1473
1474        Args:
1475            stream:
1476            startxref:
1477
1478        Returns:
1479            0 means no issue, other values represent specific issues.
1480
1481        """
1482        if startxref == 0:
1483            return 4
1484
1485        stream.seek(startxref - 1, 0)  # -1 to check character before
1486        line = stream.read(1)
1487        if line == b"j":
1488            line = stream.read(1)
1489        if line not in b"\r\n \t":
1490            return 1
1491        line = stream.read(4)
1492        if line != b"xref":
1493            # not a xref so check if it is an XREF object
1494            line = b""
1495            while line in b"0123456789 \t":
1496                line = stream.read(1)
1497                if line == b"":
1498                    return 2
1499            line += stream.read(2)  # 1 char already read, +2 to check "obj"
1500            if line.lower() != b"obj":
1501                return 3
1502        return 0
1503
1504    @classmethod
1505    def _find_pdf_objects(cls, data: bytes) -> Iterable[tuple[int, int, int]]:
1506        index = 0
1507        ord_0 = ord("0")
1508        ord_9 = ord("9")
1509        while True:
1510            index = data.find(b" obj", index)
1511            if index == -1:
1512                return
1513
1514            index_before_space = index - 1
1515
1516            # Skip whitespace backwards
1517            while index_before_space >= 0 and data[index_before_space] in WHITESPACES_AS_BYTES:
1518                index_before_space -= 1
1519
1520            # Read generation number
1521            generation_end = index_before_space + 1
1522            while index_before_space >= 0 and ord_0 <= data[index_before_space] <= ord_9:
1523                index_before_space -= 1
1524            generation_start = index_before_space + 1
1525
1526            # Skip whitespace
1527            while index_before_space >= 0 and data[index_before_space] in WHITESPACES_AS_BYTES:
1528                index_before_space -= 1
1529
1530            # Read object number
1531            object_end = index_before_space + 1
1532            while index_before_space >= 0 and ord_0 <= data[index_before_space] <= ord_9:
1533                index_before_space -= 1
1534            object_start = index_before_space + 1
1535
1536            # Validate
1537            if (
1538                object_start < object_end
1539                and object_end - object_start <= IndirectObject._MAXIMUM_PART_LENGTH
1540                and generation_start < generation_end
1541                and generation_end - generation_start <= IndirectObject._MAXIMUM_PART_LENGTH
1542            ):
1543                object_number = int(data[object_start:object_end])
1544                generation_number = int(data[generation_start:generation_end])
1545
1546                yield object_number, generation_number, object_start
1547
1548            index += 4  # len(b" obj")
1549
1550    @classmethod
1551    def _find_pdf_trailers(cls, data: bytes) -> Iterable[int]:
1552        index = 0
1553        data_length = len(data)
1554        while True:
1555            index = data.find(b"trailer", index)
1556            if index == -1:
1557                return
1558
1559            index_after_trailer = index + 7  # len(b"trailer")
1560
1561            # Skip whitespace
1562            while index_after_trailer < data_length and data[index_after_trailer] in WHITESPACES_AS_BYTES:
1563                index_after_trailer += 1
1564
1565            # Must be dictionary start
1566            if index_after_trailer + 1 < data_length and data[index_after_trailer:index_after_trailer+2] == b"<<":
1567                yield index_after_trailer  # offset of '<<'
1568
1569            index += 7  # len(b"trailer")
1570
1571    def _rebuild_xref_table(self, stream: StreamType) -> None:
1572        self.xref = {}
1573        stream.seek(0, 0)
1574        stream_data = stream.read(-1)
1575
1576        for object_number, generation_number, object_start in self._find_pdf_objects(stream_data):
1577            if generation_number not in self.xref:
1578                self.xref[generation_number] = {}
1579            self.xref[generation_number][object_number] = object_start
1580
1581        logger_warning("parsing for Object Streams", source=__name__)
1582        # PDF 1.5+ files may carry the trailer keys inside a cross-reference
1583        # stream instead of behind a `trailer` keyword. Collect them here,
1584        # keyed by their offset, to merge them below in file order.
1585        xref_stream_trailers: list[tuple[int, DictionaryObject]] = []
1586        for generation_number in self.xref:
1587            for object_number in self.xref[generation_number]:
1588                # get_object in manual
1589                object_start = self.xref[generation_number][object_number]
1590                stream.seek(object_start, 0)
1591                try:
1592                    _ = self.read_object_header(stream)
1593                    obj = cast(StreamObject, read_object(stream, self))
1594                    object_type = obj.get("/Type", "")
1595                    if object_type == "/XRef":
1596                        trailer = DictionaryObject()
1597                        for key in self._XREF_STREAM_TRAILER_KEYS:
1598                            if key in obj:
1599                                trailer[NameObject(key)] = obj.raw_get(key)
1600                        xref_stream_trailers.append((object_start, trailer))
1601                        continue
1602                    if object_type != "/ObjStm":
1603                        continue
1604                    object_stream = BytesIO(obj.get_data())
1605                    actual_count = 0
1606                    while True:
1607                        current = read_until_whitespace(
1608                            object_stream, max_bytes=IndirectObject._MAXIMUM_PART_LENGTH, strict=self.strict
1609                        )
1610                        if not current.isdigit():
1611                            break
1612                        inner_object_number = int(current)
1613                        skip_over_whitespace(object_stream)
1614                        object_stream.seek(-1, 1)
1615                        current = read_until_whitespace(
1616                            object_stream, max_bytes=IndirectObject._MAXIMUM_PART_LENGTH, strict=self.strict
1617                        )
1618                        if not current.isdigit():  # pragma: no cover
1619                            break  # pragma: no cover
1620                        inner_offset = int(current)
1621                        self.xref_objStm[inner_object_number] = (object_number, inner_offset)
1622                        actual_count += 1
1623                    expected_count = cast(int, obj["/N"])
1624                    if actual_count != expected_count:  # pragma: no cover
1625                        logger_warning(  # pragma: no cover
1626                            (
1627                                "found %(actual_count)d objects within "
1628                                "Object(%(object_number)d,%(generation_number)d) "
1629                                "whereas %(expected)d expected"
1630                            ),
1631                            source=__name__,
1632                            actual_count=actual_count,
1633                            object_number=object_number,
1634                            generation_number=generation_number,
1635                            expected=expected_count,
1636                        )
1637                except LimitReachedError:
1638                    # Do not let the broad recovery below bypass the token-length limit
1639                    # when strict parsing is enabled.
1640                    raise
1641                except MemoryError:  # pragma: no cover  # TODO: BLE001
1642                    raise
1643                except Exception:  # could be multiple causes
1644                    pass
1645
1646        stream.seek(0, 0)
1647        trailers: list[tuple[int, dict[Any, Any]]] = list(xref_stream_trailers)
1648        for position in self._find_pdf_trailers(stream_data):
1649            stream.seek(position, 0)
1650            trailers.append((position, cast(dict[Any, Any], read_object(stream, self))))
1651        # Here, we are parsing the file from start to end, the new data have to erase the existing.
1652        for _, new_trailer in sorted(trailers, key=itemgetter(0)):
1653            for key, value in new_trailer.items():
1654                self.trailer[key] = value
1655
1656    def _read_xref_subsections(
1657        self,
1658        idx_pairs: list[int],
1659        get_entry: Callable[[int], int | tuple[int, ...]],
1660        used_before: Callable[[int, int | tuple[int, ...]], bool],
1661    ) -> None:
1662        """Read and process the subsections of the xref."""
1663        for start, size in self._pairs(idx_pairs):
1664            # The subsections must increase
1665            for num in range(start, start + size):
1666                # The first entry is the type
1667                xref_type = get_entry(0)
1668                # The rest of the elements depend on the xref_type
1669                if xref_type == 0:
1670                    # linked list of free objects
1671                    next_free_object = get_entry(1)  # noqa: F841
1672                    next_generation = get_entry(2)  # noqa: F841
1673                elif xref_type == 1:
1674                    # objects that are in use but are not compressed
1675                    byte_offset = get_entry(1)
1676                    generation = get_entry(2)
1677                    if generation not in self.xref:
1678                        self.xref[generation] = {}  # type: ignore[index]
1679                    if not used_before(num, generation):
1680                        self.xref[generation][num] = byte_offset  # type: ignore[index]
1681                elif xref_type == 2:
1682                    # compressed objects
1683                    objstr_num = get_entry(1)
1684                    obstr_idx = get_entry(2)
1685                    generation = 0  # PDF spec table 18, generation is 0
1686                    if not used_before(num, generation):
1687                        self.xref_objStm[num] = (objstr_num, obstr_idx)
1688                elif self.strict:
1689                    raise PdfReadError(f"Unknown xref type: {xref_type}")
1690
1691    def _pairs(self, array: list[int]) -> Iterable[tuple[int, int]]:
1692        """Iterate over pairs in the array."""
1693        i = 0
1694        while i + 1 < len(array):
1695            yield array[i], array[i + 1]
1696            i += 2
1697
1698    def decrypt(self, password: str | bytes) -> PasswordType:
1699        """
1700        When using an encrypted / secured PDF file with the PDF Standard
1701        encryption handler, this function will allow the file to be decrypted.
1702        It checks the given password against the document's user password and
1703        owner password, and then stores the resulting decryption key if either
1704        password is correct.
1705
1706        It does not matter which password was matched. Both passwords provide
1707        the correct decryption key that will allow the document to be used with
1708        this library.
1709
1710        Args:
1711            password: The password to match.
1712
1713        Returns:
1714            An indicator if the document was decrypted and whether it was the
1715            owner password or the user password.
1716
1717        """
1718        if not self._encryption:
1719            raise PdfReadError("Not encrypted file")
1720        # TODO: raise Exception for wrong password
1721        return self._encryption.verify(password, strict=self.strict)
1722
1723    @property
1724    def is_encrypted(self) -> bool:
1725        """
1726        Read-only boolean property showing whether this PDF file is encrypted.
1727
1728        Note that this property, if true, will remain true even after the
1729        :meth:`decrypt()<pypdf.PdfReader.decrypt>` method is called.
1730        """
1731        return TrailerKeys.ENCRYPT in self.trailer
1732
1733    def add_form_topname(self, name: str) -> DictionaryObject | None:
1734        """
1735        Add a top level form that groups all form fields below it.
1736
1737        Args:
1738            name: text string of the "/T" Attribute of the created object
1739
1740        Returns:
1741            The created object. ``None`` means no object was created.
1742
1743        """
1744        catalog = self.root_object
1745
1746        if "/AcroForm" not in catalog or not isinstance(
1747            catalog["/AcroForm"], DictionaryObject
1748        ):
1749            return None
1750        acroform = cast(DictionaryObject, catalog[NameObject("/AcroForm")])
1751        if "/Fields" not in acroform:
1752            # TODO: No error but this may be extended for XFA Forms
1753            return None
1754
1755        interim = DictionaryObject()
1756        interim[NameObject("/T")] = TextStringObject(name)
1757        interim[NameObject("/Kids")] = acroform[NameObject("/Fields")]
1758        # Allocate the new object_id beyond the source-file range and all cached object IDs.
1759        object_id = max(
1760            cast(int, self.trailer.get("/Size", 0)) - 1,
1761            max((i for entries in self.xref.values() for i in entries), default=0),
1762            max(self.xref_objStm, default=0),
1763            max((i for _, i in self.resolved_objects), default=0),
1764        ) + 1
1765        self.cache_indirect_object(0, object_id, interim)
1766        arr = ArrayObject()
1767        arr.append(interim.indirect_reference)
1768        acroform[NameObject("/Fields")] = arr
1769        for o in cast(ArrayObject, interim["/Kids"]):
1770            obj = o.get_object()
1771            if "/Parent" in obj:
1772                logger_warning(
1773                    "Top Level Form Field %(obj_ref)s has a non-expected parent",
1774                    source=__name__,
1775                    obj_ref=obj.indirect_reference,
1776                )
1777            obj[NameObject("/Parent")] = interim.indirect_reference
1778        return interim
1779
1780    def rename_form_topname(self, name: str) -> DictionaryObject | None:
1781        """
1782        Rename top level form field that all form fields below it.
1783
1784        Args:
1785            name: text string of the "/T" field of the created object
1786
1787        Returns:
1788            The modified object. ``None`` means no object was modified.
1789
1790        """
1791        catalog = self.root_object
1792
1793        if "/AcroForm" not in catalog or not isinstance(
1794            catalog["/AcroForm"], DictionaryObject
1795        ):
1796            return None
1797        acroform = cast(DictionaryObject, catalog[NameObject("/AcroForm")])
1798        if "/Fields" not in acroform:
1799            return None
1800
1801        interim = cast(
1802            DictionaryObject,
1803            cast(ArrayObject, acroform[NameObject("/Fields")])[0].get_object(),
1804        )
1805        interim[NameObject("/T")] = TextStringObject(name)
1806        return interim
1807
1808    def _repr_mimebundle_(
1809        self,
1810        include: Iterable[str] | None = None,
1811        exclude: Iterable[str] | None = None,
1812    ) -> dict[str, Any]:
1813        """
1814        Integration into Jupyter Notebooks.
1815
1816        This method returns a dictionary that maps a mime-type to its
1817        representation.
1818
1819        .. seealso::
1820
1821            https://ipython.readthedocs.io/en/stable/config/integrating.html
1822        """
1823        self.stream.seek(0)
1824        pdf_data = self.stream.read()
1825        data = {
1826            "application/pdf": pdf_data,
1827        }
1828
1829        if include is not None:
1830            # Filter representations based on include list
1831            data = {k: v for k, v in data.items() if k in include}
1832
1833        if exclude is not None:
1834            # Remove representations based on exclude list
1835            data = {k: v for k, v in data.items() if k not in exclude}
1836
1837        return data
1838
1839    def _get_named_destinations(
1840        self,
1841        *,
1842        tree: DictionaryObject | None = None,
1843        retval: dict[str, Destination] | None = None,
1844        visited: set[int] | None = None,
1845        depth: int = 0,
1846        traversal_state: _TraversalState | None = None,
1847    ) -> dict[str, Destination]:
1848        """Override from PdfDocCommon. In the reader we can assume this is
1849        static, but not in the writer.
1850        """
1851        if tree or retval:
1852            return super()._get_named_destinations(
1853                tree=tree,
1854                retval=retval,
1855                visited=visited,
1856                depth=depth,
1857                traversal_state=traversal_state,
1858            )
1859
1860        if self._named_destinations_cache is None:
1861            self._named_destinations_cache = super()._get_named_destinations()
1862        return self._named_destinations_cache