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