src/pypdf/_doc_common.py
1# Copyright (c) 2006, Mathieu Fenniak
2# Copyright (c) 2007, Ashish Kulkarni <kulkarni.ashish@gmail.com>
3# Copyright (c) 2024, Pubpub-ZZ
4#
5# All rights reserved.
6#
7# Redistribution and use in source and binary forms, with or without
8# modification, are permitted provided that the following conditions are
9# met:
10#
11# * Redistributions of source code must retain the above copyright notice,
12# this list of conditions and the following disclaimer.
13# * Redistributions in binary form must reproduce the above copyright notice,
14# this list of conditions and the following disclaimer in the documentation
15# and/or other materials provided with the distribution.
16# * The name of the author may not be used to endorse or promote products
17# derived from this software without specific prior written permission.
18#
19# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
23# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29# POSSIBILITY OF SUCH DAMAGE.
30
31import struct
32from abc import ABC, abstractmethod
33from collections.abc import Iterable, Iterator, Mapping, Sequence
34from datetime import datetime
35from typing import (
36 Any,
37 NamedTuple,
38 cast,
39)
40
41from ._configuration import get_configuration
42from ._encryption import Encryption
43from ._page import PageObject, _VirtualList
44from ._page_labels import index2labels
45from ._utils import (
46 _TraversalState,
47 deprecation_no_replacement,
48 logger_warning,
49 parse_iso8824_date,
50)
51from .constants import (
52 CatalogAttributes,
53 CheckboxRadioButtonAttributes,
54 Core,
55 DocumentInformationAttributes,
56 FieldDictionaryAttributes,
57 GoToActionArguments,
58 PageAttributes,
59 PagesAttributes,
60 UserAccessPermissions,
61)
62from .errors import LimitReachedError, PdfReadError, PyPdfError
63from .generic import (
64 ArrayObject,
65 BooleanObject,
66 ByteStringObject,
67 Destination,
68 DictionaryObject,
69 Field,
70 Fit,
71 FloatObject,
72 IndirectObject,
73 NameObject,
74 NullObject,
75 PdfObject,
76 StreamObject,
77 TextStringObject,
78 TreeObject,
79 ViewerPreferences,
80 create_string_object,
81 is_null_or_none,
82)
83from .generic._files import EmbeddedFile
84from .types import OutlineType, PagemodeType
85from .xmp import XmpInformation
86
87
88def convert_to_int(d: bytes, size: int) -> int | tuple[Any, ...]:
89 if size > 8:
90 raise PdfReadError("Invalid size in convert_to_int")
91 d = b"\x00\x00\x00\x00\x00\x00\x00\x00" + d
92 d = d[-8:]
93 return cast(int, struct.unpack(">Q", d)[0])
94
95
96# Attributes a page inherits from its ancestors in the page tree.
97_INHERITABLE_PAGE_ATTRIBUTES = (
98 NameObject(PageAttributes.RESOURCES),
99 NameObject(PageAttributes.MEDIABOX),
100 NameObject(PageAttributes.CROPBOX),
101 NameObject(PageAttributes.ROTATE),
102)
103
104
105class _PageTreeItem(NamedTuple):
106 """A page tree node waiting to be flattened by :meth:`PdfDocCommon._flatten`."""
107
108 node: DictionaryObject
109 #: Inherited attributes. Shared read-only between the kids of one node.
110 inherit: dict[str, Any]
111 indirect_reference: IndirectObject | None
112 depth: int
113
114
115#: A ``/Pages`` node currently being walked: the node - carrying the attributes its
116#: kids inherit - and the part of its ``/Kids`` which has not been reached yet.
117_PageTreeFrame = tuple[_PageTreeItem, Iterator[PdfObject]]
118
119_UNSET = object()
120
121
122class DocumentInformation(DictionaryObject):
123 """
124 A class representing the basic document metadata provided in a PDF File.
125 This class is accessible through
126 :py:class:`PdfReader.metadata<pypdf.PdfReader.metadata>`.
127
128 All text properties of the document metadata have
129 *two* properties, e.g. author and author_raw. The non-raw property will
130 always return a ``TextStringObject``, making it ideal for a case where the
131 metadata is being displayed. The raw property can sometimes return a
132 ``ByteStringObject``, if pypdf was unable to decode the string's text
133 encoding; this requires additional safety in the caller and therefore is not
134 as commonly accessed.
135 """
136
137 def __init__(self) -> None:
138 DictionaryObject.__init__(self)
139
140 def _get_text(self, key: str) -> str | None:
141 retval = self.get(key, None)
142 if isinstance(retval, TextStringObject):
143 return retval
144 if isinstance(retval, ByteStringObject):
145 return str(retval)
146 return None
147
148 @property
149 def title(self) -> str | None:
150 """
151 Read-only property accessing the document's title.
152
153 Returns a ``TextStringObject`` or ``None`` if the title is not
154 specified.
155 """
156 return (
157 self._get_text(DocumentInformationAttributes.TITLE)
158 or self.get(DocumentInformationAttributes.TITLE).get_object() # type: ignore[union-attr]
159 if self.get(DocumentInformationAttributes.TITLE)
160 else None
161 )
162
163 @property
164 def title_raw(self) -> str | None:
165 """The "raw" version of title; can return a ``ByteStringObject``."""
166 return self.get(DocumentInformationAttributes.TITLE)
167
168 @property
169 def author(self) -> str | None:
170 """
171 Read-only property accessing the document's author.
172
173 Returns a ``TextStringObject`` or ``None`` if the author is not
174 specified.
175 """
176 return self._get_text(DocumentInformationAttributes.AUTHOR)
177
178 @property
179 def author_raw(self) -> str | None:
180 """The "raw" version of author; can return a ``ByteStringObject``."""
181 return self.get(DocumentInformationAttributes.AUTHOR)
182
183 @property
184 def subject(self) -> str | None:
185 """
186 Read-only property accessing the document's subject.
187
188 Returns a ``TextStringObject`` or ``None`` if the subject is not
189 specified.
190 """
191 return self._get_text(DocumentInformationAttributes.SUBJECT)
192
193 @property
194 def subject_raw(self) -> str | None:
195 """The "raw" version of subject; can return a ``ByteStringObject``."""
196 return self.get(DocumentInformationAttributes.SUBJECT)
197
198 @property
199 def creator(self) -> str | None:
200 """
201 Read-only property accessing the document's creator.
202
203 If the document was converted to PDF from another format, this is the
204 name of the application (e.g. OpenOffice) that created the original
205 document from which it was converted. Returns a ``TextStringObject`` or
206 ``None`` if the creator is not specified.
207 """
208 return self._get_text(DocumentInformationAttributes.CREATOR)
209
210 @property
211 def creator_raw(self) -> str | None:
212 """The "raw" version of creator; can return a ``ByteStringObject``."""
213 return self.get(DocumentInformationAttributes.CREATOR)
214
215 @property
216 def producer(self) -> str | None:
217 """
218 Read-only property accessing the document's producer.
219
220 If the document was converted to PDF from another format, this is the
221 name of the application (for example, macOS Quartz) that converted it to
222 PDF. Returns a ``TextStringObject`` or ``None`` if the producer is not
223 specified.
224 """
225 return self._get_text(DocumentInformationAttributes.PRODUCER)
226
227 @property
228 def producer_raw(self) -> str | None:
229 """The "raw" version of producer; can return a ``ByteStringObject``."""
230 return self.get(DocumentInformationAttributes.PRODUCER)
231
232 @property
233 def creation_date(self) -> datetime | None:
234 """Read-only property accessing the document's creation date."""
235 return parse_iso8824_date(self._get_text(DocumentInformationAttributes.CREATION_DATE))
236
237 @property
238 def creation_date_raw(self) -> str | None:
239 """
240 The "raw" version of creation date; can return a ``ByteStringObject``.
241
242 Typically in the format ``D:YYYYMMDDhhmmss[+Z-]hh'mm`` where the suffix
243 is the offset from UTC.
244 """
245 return self.get(DocumentInformationAttributes.CREATION_DATE)
246
247 @property
248 def modification_date(self) -> datetime | None:
249 """
250 Read-only property accessing the document's modification date.
251
252 The date and time the document was most recently modified.
253 """
254 return parse_iso8824_date(self._get_text(DocumentInformationAttributes.MOD_DATE))
255
256 @property
257 def modification_date_raw(self) -> str | None:
258 """
259 The "raw" version of modification date; can return a
260 ``ByteStringObject``.
261
262 Typically, in the format ``D:YYYYMMDDhhmmss[+Z-]hh'mm`` where the suffix
263 is the offset from UTC.
264 """
265 return self.get(DocumentInformationAttributes.MOD_DATE)
266
267 @property
268 def keywords(self) -> str | None:
269 """
270 Read-only property accessing the document's keywords.
271
272 Returns a ``TextStringObject`` or ``None`` if keywords are not
273 specified.
274 """
275 return self._get_text(DocumentInformationAttributes.KEYWORDS)
276
277 @property
278 def keywords_raw(self) -> str | None:
279 """The "raw" version of keywords; can return a ``ByteStringObject``."""
280 return self.get(DocumentInformationAttributes.KEYWORDS)
281
282
283class PdfDocCommon(ABC):
284 """
285 Common functions from PdfWriter and PdfReader objects.
286
287 This root class is strongly abstracted.
288 """
289
290 strict: bool = False # default
291
292 flattened_pages: list[PageObject] | None = None
293
294 _encryption: Encryption | None = None
295
296 _readonly: bool = False
297
298 @property
299 @abstractmethod
300 def root_object(self) -> DictionaryObject:
301 ... # pragma: no cover
302
303 @property
304 @abstractmethod
305 def pdf_header(self) -> str:
306 ... # pragma: no cover
307
308 @abstractmethod
309 def get_object(
310 self, indirect_reference: int | IndirectObject
311 ) -> PdfObject | None:
312 ... # pragma: no cover
313
314 @abstractmethod
315 def _replace_object(self, indirect_reference: IndirectObject, obj: PdfObject) -> PdfObject:
316 ... # pragma: no cover
317
318 @property
319 @abstractmethod
320 def _info(self) -> DictionaryObject | None:
321 ... # pragma: no cover
322
323 @property
324 def metadata(self) -> DocumentInformation | None:
325 """
326 Retrieve the PDF file's document information dictionary, if it exists.
327
328 Note that some PDF files use metadata streams instead of document
329 information dictionaries, and these metadata streams will not be
330 accessed by this function.
331 """
332 retval = DocumentInformation()
333 if self._info is None:
334 return None
335 retval.update(self._info)
336 return retval
337
338 @property
339 @abstractmethod
340 def xmp_metadata(self) -> XmpInformation | None:
341 ... # pragma: no cover
342
343 @property
344 def viewer_preferences(self) -> ViewerPreferences | None:
345 """Returns the existing ViewerPreferences as an overloaded dictionary."""
346 o = self.root_object.get(CatalogAttributes.VIEWER_PREFERENCES, None)
347 if o is None:
348 return None
349 o = o.get_object()
350 if not isinstance(o, DictionaryObject):
351 logger_warning(
352 "Viewer preferences are not a dictionary: %(preferences)s",
353 source=__name__,
354 preferences=o,
355 )
356 return None
357 if not isinstance(o, ViewerPreferences):
358 o = ViewerPreferences(o)
359 if hasattr(o, "indirect_reference") and o.indirect_reference is not None:
360 self._replace_object(o.indirect_reference, o)
361 else:
362 self.root_object[NameObject(CatalogAttributes.VIEWER_PREFERENCES)] = o
363 return o
364
365 def get_num_pages(self) -> int:
366 """
367 Calculate the number of pages in this PDF file.
368
369 Returns:
370 The number of pages of the parsed PDF file.
371
372 Raises:
373 PdfReadError: If restrictions prevent this action.
374
375 """
376 # The page tree cannot be walked while the document is still encrypted;
377 # the PDF file's page count is used in this case. Once the document has
378 # been decrypted (or if it is not encrypted at all), the flattened page
379 # tree is used instead, as the /Count value might be wrong.
380 encryption = self._encryption
381 if self.is_encrypted and (encryption is None or not encryption.is_decrypted()):
382 return self.root_object["/Pages"]["/Count"] # type: ignore[no-any-return, index]
383 if self.flattened_pages is None:
384 self._flatten(self._readonly)
385 assert self.flattened_pages is not None
386 return len(self.flattened_pages)
387
388 def get_page(self, page_number: int) -> PageObject:
389 """
390 Retrieve a page by number from this PDF file.
391 Most of the time ``.pages[page_number]`` is preferred.
392
393 Args:
394 page_number: The page number to retrieve
395 (pages begin at zero)
396
397 Returns:
398 A :class:`PageObject<pypdf._page.PageObject>` instance.
399
400 """
401 if self.flattened_pages is None:
402 self._flatten(self._readonly)
403 assert self.flattened_pages is not None, "mypy"
404 return self.flattened_pages[page_number]
405
406 def _get_page_in_node(
407 self,
408 page_number: int,
409 ) -> tuple[DictionaryObject, int]:
410 """
411 Retrieve the node and position within the /Kids containing the page.
412 If page_number is greater than the number of pages, it returns the top node, -1.
413 """
414 top = cast(DictionaryObject, self.root_object["/Pages"])
415 visited: set[int] = set()
416
417 def recursive_call(
418 _node: DictionaryObject, mi: int
419 ) -> tuple[PdfObject | None, int]:
420 _node_id = id(_node)
421 if _node_id in visited:
422 raise LimitReachedError("Detected cycle in /Pages hierarchy when retrieving page.")
423 visited.add(_node_id)
424 ma = cast(int, _node.get("/Count", 1)) # default 1 for /Page types
425 if _node.get("/Type") == "/Page":
426 if page_number == mi:
427 return _node, -1
428 return None, mi + 1
429 if (page_number - mi) >= ma: # not in nodes below
430 if _node == top:
431 return top, -1
432 return None, mi + ma
433 for _idx, kid in enumerate(cast(ArrayObject, _node["/Kids"])):
434 kid = cast(DictionaryObject, kid.get_object())
435 n, i = recursive_call(kid, mi)
436 if n is not None: # page has just been found ...
437 if i < 0: # ... just below!
438 return _node, _idx
439 # ... at lower levels
440 return n, i
441 mi = i
442 raise PyPdfError("Unexpectedly cannot find the node.")
443
444 node, idx = recursive_call(top, 0)
445 assert isinstance(node, DictionaryObject), "mypy"
446 return node, idx
447
448 @property
449 def named_destinations(self) -> dict[str, Destination]:
450 """A read-only dictionary which maps names to destinations."""
451 return self._get_named_destinations()
452
453 def get_named_dest_root(self) -> ArrayObject:
454 named_dest = ArrayObject()
455 if CatalogAttributes.NAMES in self.root_object and isinstance(
456 self.root_object[CatalogAttributes.NAMES], DictionaryObject
457 ):
458 names = cast(DictionaryObject, self.root_object[CatalogAttributes.NAMES])
459 if CatalogAttributes.DESTS in names and isinstance(names[CatalogAttributes.DESTS], DictionaryObject):
460 # §3.6.3 Name Dictionary (PDF spec 1.7)
461 dests = cast(DictionaryObject, names[CatalogAttributes.DESTS])
462 if CatalogAttributes.NAMES in dests:
463 # §7.9.6, entries in a name tree node dictionary
464 named_dest = cast(ArrayObject, dests[CatalogAttributes.NAMES])
465 else:
466 named_dest = ArrayObject()
467 dests[NameObject(CatalogAttributes.NAMES)] = named_dest
468 elif hasattr(self, "_add_object"):
469 dests = DictionaryObject()
470 dests_ref = self._add_object(dests)
471 names[NameObject(CatalogAttributes.DESTS)] = dests_ref
472 dests[NameObject(CatalogAttributes.NAMES)] = named_dest
473
474 elif hasattr(self, "_add_object"):
475 names = DictionaryObject()
476 names_ref = self._add_object(names)
477 self.root_object[NameObject(CatalogAttributes.NAMES)] = names_ref
478 dests = DictionaryObject()
479 dests_ref = self._add_object(dests)
480 names[NameObject(CatalogAttributes.DESTS)] = dests_ref
481 dests[NameObject(CatalogAttributes.NAMES)] = named_dest
482
483 return named_dest
484
485 ## common
486 def _get_named_destinations(
487 self,
488 *,
489 tree: DictionaryObject | None = None,
490 retval: dict[str, Destination] | None = None,
491 visited: set[int] | None = None,
492 depth: int = 0,
493 traversal_state: _TraversalState | None = None,
494 ) -> dict[str, Destination]:
495 """
496 Retrieve the named destinations present in the document.
497
498 Args:
499 tree: The current tree.
500 retval: The previously retrieved destinations for nested calls.
501 visited: Already known/visited objects.
502 depth: Current name tree nesting depth.
503 traversal_state: Shared visitor counters.
504
505 Returns:
506 A dictionary which maps names to destinations.
507
508 """
509 if traversal_state is None:
510 traversal_state = _TraversalState()
511
512 if visited is None:
513 visited = set()
514 if retval is None:
515 retval = {}
516 catalog = self.root_object
517
518 # get the name tree
519 candidate: PdfObject | None = None
520 if CatalogAttributes.DESTS in catalog:
521 candidate = catalog[CatalogAttributes.DESTS].get_object()
522 elif CatalogAttributes.NAMES in catalog:
523 names = catalog[CatalogAttributes.NAMES].get_object()
524 if isinstance(names, DictionaryObject) and CatalogAttributes.DESTS in names:
525 candidate = names[CatalogAttributes.DESTS].get_object()
526 if candidate is not None and not isinstance(candidate, DictionaryObject):
527 logger_warning(
528 "Destination tree is not a dictionary: %(tree)s",
529 source=__name__,
530 tree=candidate,
531 )
532 return retval
533 if candidate is not None:
534 tree = candidate
535
536 if is_null_or_none(tree):
537 return retval
538 assert tree is not None, "mypy"
539
540 configuration = get_configuration()
541 if depth > configuration.named_destinations_maximum_depth:
542 raise LimitReachedError(
543 f"Maximum named destination depth exceeded: "
544 f"{depth} > {configuration.named_destinations_maximum_depth}."
545 )
546
547 tree_id = id(tree)
548 if tree_id in visited:
549 logger_warning("Detected cycle in destination tree.", source=__name__)
550 return retval
551 visited.add(tree_id)
552
553 traversal_state.entry_count += 1
554 if traversal_state.entry_count > configuration.named_destinations_maximum_entries:
555 raise LimitReachedError(
556 f"Maximum named destination entry limit exceeded: "
557 f"{traversal_state.entry_count} > {configuration.named_destinations_maximum_entries}."
558 )
559
560 if PagesAttributes.KIDS in tree:
561 kids = tree[PagesAttributes.KIDS].get_object()
562 if not isinstance(kids, ArrayObject):
563 logger_warning(
564 "Destination tree kids are not an array: %(kids)s",
565 source=__name__,
566 kids=kids,
567 )
568 return retval
569 # recurse down the tree
570 for kid in kids:
571 self._get_named_destinations(
572 tree=kid.get_object(),
573 retval=retval,
574 visited=visited,
575 depth=depth + 1,
576 traversal_state=traversal_state,
577 )
578 # §7.9.6, entries in a name tree node dictionary
579 elif CatalogAttributes.NAMES in tree: # /Kids and /Names are exclusives (§7.9.6)
580 names = tree[CatalogAttributes.NAMES].get_object()
581 if not isinstance(names, ArrayObject):
582 logger_warning(
583 "Destination tree names are not an array: %(names)s",
584 source=__name__,
585 names=names,
586 )
587 return retval
588 i = 0
589 while i < len(names):
590 key = names[i].get_object()
591 i += 1
592 if not isinstance(key, (bytes, str)):
593 continue
594 try:
595 value = names[i].get_object()
596 except IndexError:
597 break
598 i += 1
599 if isinstance(value, DictionaryObject):
600 if "/D" in value:
601 value = value["/D"]
602 else:
603 continue
604 dest = self._build_destination(key, value)
605 if dest is not None:
606 retval[cast(str, dest["/Title"])] = dest
607 # Remain backwards-compatible.
608 retval[str(key)] = dest
609 else: # case where /Dests is in the document's catalog dictionary (PDF 1.7 specs, §2 about PDF 1.1)
610 for k__, v__ in tree.items():
611 val = v__.get_object()
612 if isinstance(val, DictionaryObject):
613 if "/D" in val:
614 val = val["/D"].get_object()
615 else:
616 continue
617 dest = self._build_destination(k__, val)
618 if dest is not None:
619 retval[k__] = dest
620 return retval
621
622 # A select group of relevant field attributes. For the complete list,
623 # see §12.3.2 of the PDF 1.7 or PDF 2.0 specification.
624
625 def get_fields(
626 self,
627 tree: DictionaryObject | None = None,
628 retval: dict[Any, Any] | None = None,
629 fileobj: Any | None = None,
630 stack: Any = _UNSET,
631 *,
632 _visited: set[int] | None = None,
633 _depth: int = 0,
634 _traversal_state: _TraversalState | None = None,
635 ) -> dict[str, Any] | None:
636 """
637 Extract field data if this PDF contains interactive form fields.
638
639 The *tree*, *retval*, *visited*, *depth* parameters are for internal use.
640
641 Args:
642 tree: Current object to parse.
643 retval: In-progress list of fields.
644 fileobj: A file object (usually a text file) to write
645 a report to on all interactive form fields found.
646 stack: The stack to use. Deprecated.
647 _visited: Set of already visited IDs. Callers should usually omit this.
648 _depth: The current field depth.
649 _traversal_state: The current traversal state.
650
651 Returns:
652 A dictionary where each key is a field name, and each
653 value is a :class:`Field<pypdf.generic.Field>` object. By
654 default, the mapping name is used for keys.
655 ``None`` if form data could not be located.
656
657 """
658 if stack is not _UNSET:
659 deprecation_no_replacement(name="stack", removed_in="7.0.0")
660
661 configuration = get_configuration()
662 if _depth >= configuration.form_fields_maximum_depth:
663 raise LimitReachedError("Reached maximum allowed form field depth.")
664 if _traversal_state is None:
665 _traversal_state = _TraversalState()
666
667 def _check_field_limit(_increment: int) -> None:
668 _traversal_state.entry_count += _increment
669 if _traversal_state.entry_count > configuration.form_fields_maximum_entries:
670 raise LimitReachedError("Exceeded maximum number of fields allowed.")
671
672 field_attributes = FieldDictionaryAttributes.attributes_dict()
673 field_attributes.update(CheckboxRadioButtonAttributes.attributes_dict())
674 if retval is None:
675 retval = {}
676 catalog = self.root_object
677 _visited = set()
678 # get the AcroForm tree
679 if CatalogAttributes.ACRO_FORM in catalog:
680 entry = catalog[CatalogAttributes.ACRO_FORM]
681 acro_form = None if entry is None else entry.get_object()
682 if acro_form is not None and not isinstance(
683 acro_form, DictionaryObject
684 ):
685 logger_warning(
686 "AcroForm is not a dictionary: %(acro_form)s",
687 source=__name__,
688 acro_form=acro_form,
689 )
690 return None
691 tree = acro_form
692 else:
693 return None
694 if tree is None:
695 return retval
696 assert _visited is not None
697 if "/Fields" in tree:
698 fields = tree["/Fields"].get_object()
699 if not isinstance(fields, ArrayObject):
700 logger_warning(
701 "AcroForm /Fields is not an array: %(fields)s",
702 source=__name__,
703 fields=fields,
704 )
705 return retval
706 _check_field_limit(len(fields))
707 for f in fields:
708 field = f.get_object()
709 self._build_field(
710 field=field, retval=retval, fileobj=fileobj, field_attributes=field_attributes,
711 visited=_visited, depth=_depth, traversal_state=_traversal_state,
712 )
713 elif any(attr in tree for attr in field_attributes):
714 # Tree is a field
715 _check_field_limit(1)
716 self._build_field(
717 field=tree, retval=retval, fileobj=fileobj, field_attributes=field_attributes,
718 visited=_visited, depth=_depth, traversal_state=_traversal_state,
719 )
720 return retval
721
722 def _get_qualified_field_name(
723 self,
724 *,
725 parent: DictionaryObject,
726 visited: set[int] | None = None
727 ) -> str:
728 if visited is None:
729 visited = set()
730 parent_id = id(parent)
731 if parent_id in visited:
732 raise LimitReachedError("Detected cycle in /Parent hierarchy when retrieving qualified field name.")
733 visited.add(parent_id)
734
735 if "/TM" in parent:
736 return cast(str, parent["/TM"])
737 if "/Parent" in parent:
738 return (
739 self._get_qualified_field_name(
740 parent=cast(DictionaryObject, parent["/Parent"]),
741 visited=visited,
742 )
743 + "."
744 + cast(str, parent.get("/T", ""))
745 )
746 return cast(str, parent.get("/T", ""))
747
748 @staticmethod
749 def _normal_appearance(appearance: Any) -> DictionaryObject:
750 """Return the /N normal-appearance sub-dictionary of an /AP entry."""
751 appearance = appearance.get_object()
752 if not isinstance(appearance, DictionaryObject):
753 raise PdfReadError(f"Expected appearance dictionary, got {appearance!r}")
754 normal = appearance.get("/N")
755 if normal is not None:
756 normal = normal.get_object()
757 if not isinstance(normal, DictionaryObject):
758 raise PdfReadError(f"Expected /N appearance dictionary, got {normal!r}")
759 return normal
760
761 def _build_field(
762 self,
763 *,
764 field: TreeObject | DictionaryObject,
765 retval: dict[Any, Any],
766 fileobj: Any,
767 field_attributes: Any,
768 visited: set[int],
769 depth: int,
770 traversal_state: _TraversalState,
771 ) -> None:
772 if not isinstance(field, DictionaryObject):
773 logger_warning(
774 "Form field is not a dictionary: %(field)s",
775 source=__name__,
776 field=field,
777 )
778 return
779 if all(attr not in field for attr in ("/T", "/TM")):
780 return
781 key = self._get_qualified_field_name(parent=field)
782 if fileobj:
783 self._write_field(fileobj, field, field_attributes)
784 fileobj.write("\n")
785 retval[key] = Field(field)
786 obj = retval[key].indirect_reference.get_object() # to get the full object
787 if obj.get(FieldDictionaryAttributes.FT, "") == "/Ch" and obj.get(NameObject(FieldDictionaryAttributes.Opt)):
788 retval[key][NameObject("/_States_")] = obj[NameObject(FieldDictionaryAttributes.Opt)]
789 if obj.get(FieldDictionaryAttributes.FT, "") == "/Btn" and "/AP" in obj:
790 # Checkbox
791 normal = self._normal_appearance(obj["/AP"])
792 retval[key][NameObject("/_States_")] = ArrayObject(list(normal.keys()))
793 if "/Off" not in retval[key]["/_States_"]:
794 retval[key][NameObject("/_States_")].append(NameObject("/Off"))
795 elif (
796 obj.get(FieldDictionaryAttributes.FT, "") == "/Btn"
797 and obj.get(FieldDictionaryAttributes.Ff, 0) & FieldDictionaryAttributes.FfBits.Radio != 0
798 ):
799 states: list[str] = []
800 retval[key][NameObject("/_States_")] = ArrayObject(states)
801 for k in obj.get(FieldDictionaryAttributes.Kids, {}):
802 k = k.get_object()
803 if "/AP" not in k:
804 raise PdfReadError(f"Button field kid missing /AP: {k!r}")
805 normal = self._normal_appearance(k["/AP"])
806 for s in list(normal.keys()):
807 if s not in states:
808 states.append(s)
809 retval[key][NameObject("/_States_")] = ArrayObject(states)
810 if (
811 obj.get(FieldDictionaryAttributes.Ff, 0) & FieldDictionaryAttributes.FfBits.NoToggleToOff != 0
812 and "/Off" in retval[key]["/_States_"]
813 ):
814 del retval[key]["/_States_"][retval[key]["/_States_"].index("/Off")]
815 # at last for order
816 self._check_kids(
817 tree=field, retval=retval, fileobj=fileobj, visited=visited, depth=depth, traversal_state=traversal_state
818 )
819
820 def _check_kids(
821 self,
822 *,
823 tree: TreeObject | DictionaryObject,
824 retval: Any,
825 fileobj: Any,
826 visited: set[int],
827 depth: int,
828 traversal_state: _TraversalState,
829 ) -> None:
830 tree_id = id(tree)
831 if tree_id in visited:
832 logger_warning(
833 "%(field_name)s already parsed",
834 source=__name__,
835 field_name=self._get_qualified_field_name(parent=tree),
836 )
837 return
838 visited.add(tree_id)
839 if PagesAttributes.KIDS in tree:
840 # recurse down the tree
841 for kid in tree[PagesAttributes.KIDS]: # type: ignore[attr-defined]
842 kid = kid.get_object()
843 self.get_fields(
844 tree=kid, retval=retval, fileobj=fileobj,
845 _visited=visited, _depth=depth + 1, _traversal_state=traversal_state
846 )
847
848 def _write_field(self, fileobj: Any, field: Any, field_attributes: Any) -> None:
849 field_attributes_tuple = FieldDictionaryAttributes.attributes()
850 field_attributes_tuple = (
851 field_attributes_tuple + CheckboxRadioButtonAttributes.attributes()
852 )
853
854 for attr in field_attributes_tuple:
855 if attr in (
856 FieldDictionaryAttributes.Kids,
857 FieldDictionaryAttributes.AA,
858 ):
859 continue
860 attr_name = field_attributes[attr]
861 try:
862 if attr == FieldDictionaryAttributes.FT:
863 # Make the field type value clearer
864 types = {
865 "/Btn": "Button",
866 "/Tx": "Text",
867 "/Ch": "Choice",
868 "/Sig": "Signature",
869 }
870 if field[attr] in types:
871 fileobj.write(f"{attr_name}: {types[field[attr]]}\n")
872 elif attr == FieldDictionaryAttributes.Parent:
873 # Let's just write the name of the parent
874 try:
875 name = field[attr][FieldDictionaryAttributes.TM]
876 except KeyError:
877 name = field[attr][FieldDictionaryAttributes.T]
878 fileobj.write(f"{attr_name}: {name}\n")
879 else:
880 fileobj.write(f"{attr_name}: {field[attr]}\n")
881 except KeyError:
882 # Field attribute is N/A or unknown, so don't write anything
883 pass
884
885 def get_form_text_fields(self, full_qualified_name: bool = False) -> dict[str, Any]:
886 """
887 Retrieve form fields from the document with textual data.
888
889 Args:
890 full_qualified_name: to get full name
891
892 Returns:
893 A dictionary. The key is the name of the form field,
894 the value is the content of the field.
895
896 If the document contains multiple form fields with the same name, the
897 second and following will get the suffix .2, .3, ...
898
899 """
900
901 def indexed_key(k: str, fields: dict[Any, Any]) -> str:
902 if k not in fields:
903 return k
904 return (
905 k
906 + "."
907 + str(sum(1 for kk in fields if kk.startswith(k + ".")) + 2)
908 )
909
910 # Retrieve document form fields
911 form_fields = self.get_fields()
912 if form_fields is None:
913 return {}
914 ff = {}
915 for field, value in form_fields.items():
916 if value.get("/FT") == "/Tx":
917 if full_qualified_name:
918 ff[field] = value.get("/V")
919 else:
920 ff[indexed_key(cast(str, value.get("/T", field)), ff)] = value.get("/V")
921 return ff
922
923 def get_pages_showing_field(
924 self, field: Field | PdfObject | IndirectObject
925 ) -> list[PageObject]:
926 """
927 Provides list of pages where the field is called.
928
929 Args:
930 field: Field Object, PdfObject or IndirectObject referencing a Field
931
932 Returns:
933 List of pages:
934 - Empty list:
935 The field has no widgets attached
936 (either hidden field or ancestor field).
937 - Single page list:
938 Page where the widget is present
939 (most common).
940 - Multi-page list:
941 Field with multiple kids widgets
942 (example: radio buttons, field repeated on multiple pages).
943
944 """
945 try:
946 # to cope with all types
947 field = cast(DictionaryObject, field.indirect_reference.get_object()) # type: ignore[union-attr]
948 except Exception as exc:
949 raise ValueError("Field type is invalid") from exc
950 if is_null_or_none(field.get_inherited(key="/FT", default=None)):
951 raise ValueError("Field is not valid")
952 ret = []
953 if field.get("/Subtype", "") == "/Widget":
954 if "/P" in field:
955 ret = [field["/P"].get_object()]
956 else:
957 ret = [
958 p
959 for p in self.pages
960 if field.indirect_reference in p.get("/Annots", "")
961 ]
962 else:
963 kids = field.get("/Kids", ())
964 for k in kids:
965 k = k.get_object()
966 if (k.get("/Subtype", "") == "/Widget") and ("/T" not in k):
967 # Kid that is just a widget, not a field:
968 if "/P" in k:
969 ret += [k["/P"].get_object()]
970 else:
971 ret += [
972 p
973 for p in self.pages
974 if k.indirect_reference in p.get("/Annots", "")
975 ]
976 return [
977 x
978 if isinstance(x, PageObject)
979 else (self.pages[self._get_page_number_by_indirect(x.indirect_reference)]) # type: ignore[index, union-attr]
980 for x in ret
981 ]
982
983 @property
984 def open_destination(
985 self,
986 ) -> Destination | TextStringObject | ByteStringObject | None:
987 """
988 Property to access the opening destination (``/OpenAction`` entry in
989 the PDF catalog). It returns ``None`` if the entry does not exist
990 or is not set.
991
992 Raises:
993 Exception: If a destination is invalid.
994
995 """
996 if "/OpenAction" not in self.root_object:
997 return None
998 oa: Any = self.root_object["/OpenAction"]
999 if isinstance(oa, bytes): # pragma: no cover
1000 oa = oa.decode()
1001 if isinstance(oa, str):
1002 return create_string_object(oa)
1003 if isinstance(oa, ArrayObject):
1004 try:
1005 page, typ, *array = oa
1006 fit = Fit(typ, tuple(array))
1007 return Destination("OpenAction", page, fit)
1008 except Exception as exc:
1009 raise Exception(f"Invalid Destination {oa}: {exc}") from exc
1010 else:
1011 return None
1012
1013 @open_destination.setter
1014 def open_destination(self, dest: str | Destination | PageObject | None) -> None:
1015 raise NotImplementedError("No setter for open_destination")
1016
1017 @property
1018 def outline(self) -> OutlineType:
1019 """
1020 Read-only property for the outline present in the document
1021 (i.e., a collection of 'outline items' which are also known as
1022 'bookmarks').
1023 """
1024 return self._get_outline()
1025
1026 def _get_outline(
1027 self,
1028 *,
1029 node: DictionaryObject | None = None,
1030 outline: Any | None = None,
1031 visited: set[int] | None = None,
1032 depth: int = 0,
1033 traversal_state: _TraversalState | None = None
1034 ) -> OutlineType:
1035 if traversal_state is None:
1036 traversal_state = _TraversalState()
1037
1038 if outline is None:
1039 outline = []
1040 catalog = self.root_object
1041
1042 # get the outline dictionary and named destinations
1043 if Core.OUTLINES in catalog:
1044 lines = catalog[Core.OUTLINES]
1045
1046 # A reference to an object which is missing or free in the xref table
1047 # resolves to None.
1048 if is_null_or_none(lines):
1049 return outline
1050
1051 if not isinstance(lines, DictionaryObject):
1052 logger_warning(
1053 "Outlines are not a dictionary: %(lines)s",
1054 source=__name__,
1055 lines=lines,
1056 )
1057 return outline
1058
1059 # §12.3.3 Document outline, entries in the outline dictionary
1060 if "/First" in lines:
1061 node = cast(DictionaryObject, lines["/First"])
1062 self._named_destinations = self._get_named_destinations()
1063
1064 if node is None:
1065 return outline
1066
1067 configuration = get_configuration()
1068 if depth > configuration.outline_maximum_depth:
1069 raise LimitReachedError(f"Maximum outline depth reached: {depth} > {configuration.outline_maximum_depth}.")
1070
1071 # see if there are any more outline items
1072 if visited is None:
1073 visited = set()
1074 while True:
1075 node_id = id(node)
1076 if node_id in visited:
1077 logger_warning("Detected cycle in outline structure for %(node)s", source=__name__, node=node)
1078 break
1079 visited.add(node_id)
1080 traversal_state.entry_count += 1
1081 if traversal_state.entry_count > configuration.outline_maximum_entries:
1082 raise LimitReachedError(
1083 f"Maximum outline entry limit reached: "
1084 f"{traversal_state.entry_count} > {configuration.outline_maximum_entries}."
1085 )
1086
1087 if not isinstance(node, DictionaryObject):
1088 logger_warning(
1089 "Outline node is not a dictionary: %(node)s",
1090 source=__name__,
1091 node=node,
1092 )
1093 break
1094
1095 outline_obj = self._build_outline_item(node)
1096 if outline_obj:
1097 outline.append(outline_obj)
1098
1099 # check for sub-outline
1100 if "/First" in node:
1101 sub_outline: list[Any] = []
1102 # Pass a copy to allow multiple outer entries to reference the same inner one.
1103 inner_visited = visited.copy()
1104 self._get_outline(
1105 node=cast(DictionaryObject, node["/First"]),
1106 outline=sub_outline,
1107 visited=inner_visited,
1108 depth=depth + 1,
1109 traversal_state=traversal_state,
1110 )
1111 if sub_outline:
1112 outline.append(sub_outline)
1113
1114 if "/Next" not in node:
1115 break
1116 node = cast(DictionaryObject, node["/Next"])
1117
1118 return outline
1119
1120 @property
1121 def threads(self) -> ArrayObject | None:
1122 """
1123 Read-only property for the list of threads.
1124
1125 See §12.4.3 from the PDF 1.7 or 2.0 specification.
1126
1127 It is an array of dictionaries with "/F" (the first bead in the thread)
1128 and "/I" (a thread information dictionary containing information about
1129 the thread, such as its title, author, and creation date) properties or
1130 None if there are no articles.
1131
1132 Since PDF 2.0 it can also contain an indirect reference to a metadata
1133 stream containing information about the thread, such as its title,
1134 author, and creation date.
1135 """
1136 catalog = self.root_object
1137 if Core.THREADS in catalog:
1138 return cast("ArrayObject", catalog[Core.THREADS])
1139 return None
1140
1141 @abstractmethod
1142 def _get_page_number_by_indirect(
1143 self, indirect_reference: int | NullObject | IndirectObject | None
1144 ) -> int | None:
1145 ... # pragma: no cover
1146
1147 def get_page_number(self, page: PageObject) -> int | None:
1148 """
1149 Retrieve page number of a given PageObject.
1150
1151 Args:
1152 page: The page to get page number. Should be
1153 an instance of :class:`PageObject<pypdf._page.PageObject>`
1154
1155 Returns:
1156 The page number or None if page is not found
1157
1158 """
1159 return self._get_page_number_by_indirect(page.indirect_reference)
1160
1161 def get_destination_page_number(self, destination: Destination) -> int | None:
1162 """
1163 Retrieve page number of a given Destination object.
1164
1165 Args:
1166 destination: The destination to get page number.
1167
1168 Returns:
1169 The page number or None if page is not found
1170
1171 """
1172 return self._get_page_number_by_indirect(destination.page)
1173
1174 def _build_destination(
1175 self,
1176 title: str | bytes,
1177 array: ArrayObject | None,
1178 ) -> Destination:
1179 page, typ = None, None
1180 # A valid destination is an array of at least a page and a fit type.
1181 # Anything else (a name, a bare number, a NullObject, None, ...) cannot
1182 # be unpacked below, so treat it as a missing destination.
1183 if not isinstance(array, ArrayObject) or len(array) < 2:
1184 page = NullObject()
1185 return Destination(title, page, Fit.fit())
1186 page, typ, *fit_args = array
1187 try:
1188 return Destination(title, page, Fit(fit_type=typ, fit_args=fit_args))
1189 except PdfReadError:
1190 logger_warning(
1191 "Unknown destination: %(title)r %(fit_args)s",
1192 source=__name__,
1193 title=title,
1194 fit_args=fit_args,
1195 )
1196 if self.strict:
1197 raise
1198 # create a link to the first page if the document has one,
1199 # and to a null target otherwise
1200 if self.pages:
1201 tmp = self.pages[0].indirect_reference
1202 else:
1203 tmp = None
1204 indirect_reference = NullObject() if tmp is None else tmp
1205 return Destination(title, indirect_reference, Fit.fit())
1206
1207 def _build_outline_item(self, node: DictionaryObject) -> Destination | None:
1208 dest, title, outline_item = None, None, None
1209
1210 # title required for valid outline
1211 # §12.3.3, entries in an outline item dictionary
1212 if "/Title" in node:
1213 title = cast("str", node["/Title"])
1214 else:
1215 if self.strict:
1216 raise PdfReadError(f"Outline Entry Missing /Title attribute: {node!r}")
1217 title = ""
1218
1219 if "/A" in node:
1220 # Action, PDF 1.7 and PDF 2.0 §12.6 (only type GoTo supported)
1221 action = cast(DictionaryObject, node["/A"])
1222 if GoToActionArguments.S in action:
1223 action_type = cast(NameObject, action[GoToActionArguments.S])
1224 if action_type == "/GoTo":
1225 if GoToActionArguments.D in action:
1226 dest = action[GoToActionArguments.D]
1227 elif self.strict:
1228 raise PdfReadError(f"Outline Action Missing /D attribute: {node!r}")
1229 elif self.strict:
1230 raise PdfReadError(f"Outline Action Missing /S attribute: {node!r}")
1231 elif "/Dest" in node:
1232 # Destination, PDF 1.7 and PDF 2.0 §12.3.2
1233 dest = node["/Dest"]
1234 # if array was referenced in another object, will be a dict w/ key "/D"
1235 if isinstance(dest, DictionaryObject) and "/D" in dest:
1236 dest = dest["/D"]
1237
1238 if isinstance(dest, ArrayObject):
1239 outline_item = self._build_destination(title, dest)
1240 elif isinstance(dest, str):
1241 # named destination, addresses NameObject Issue #193
1242 # TODO: Keep named destination instead of replacing it?
1243 try:
1244 outline_item = self._build_destination(
1245 title, self._named_destinations[dest].dest_array
1246 )
1247 except KeyError:
1248 # named destination not found in Name Dict
1249 outline_item = self._build_destination(title, None)
1250 elif dest is None:
1251 # outline item not required to have destination or action
1252 # PDFv1.7 Table 153
1253 outline_item = self._build_destination(title, dest)
1254 else:
1255 if self.strict:
1256 raise PdfReadError(f"Unexpected destination {dest!r}")
1257 logger_warning(
1258 "Removed unexpected destination %(dest)r from destination",
1259 source=__name__,
1260 dest=dest,
1261 )
1262 outline_item = self._build_destination(title, None)
1263
1264 # if outline item created, add color, format, and child count if present
1265 if outline_item:
1266 if "/C" in node:
1267 # Color of outline item font in (R, G, B) with values ranging 0.0-1.0
1268 color = node["/C"]
1269 if isinstance(color, list):
1270 outline_item[NameObject("/C")] = ArrayObject(FloatObject(c) for c in color)
1271 else:
1272 logger_warning(
1273 "Ignoring non-array outline color %(color)r",
1274 source=__name__,
1275 color=color,
1276 )
1277 if "/F" in node:
1278 # specifies style characteristics bold and/or italic
1279 # with 1=italic, 2=bold, 3=both
1280 outline_item[NameObject("/F")] = node["/F"]
1281 if "/Count" in node:
1282 # absolute value = num. visible children
1283 # with positive = open/unfolded, negative = closed/folded
1284 outline_item[NameObject("/Count")] = node["/Count"]
1285 # if count is 0 we will consider it as open (to have available is_open)
1286 outline_item[NameObject("/%is_open%")] = BooleanObject(
1287 node.get("/Count", 0) >= 0
1288 )
1289 outline_item.node = node
1290 try:
1291 outline_item.indirect_reference = node.indirect_reference
1292 except AttributeError:
1293 pass
1294 return outline_item
1295
1296 @property
1297 def pages(self) -> Sequence[PageObject]:
1298 """
1299 Property that emulates a list of :class:`PageObject<pypdf._page.PageObject>`.
1300 This property allows to get a page or a range of pages.
1301
1302 The returned object supports indexing, slicing, ``len()``, iteration and
1303 (for PdfWriter) ``del``, but it is not a :class:`list` - pages are looked
1304 up on demand rather than materialized up front, so list-only operations
1305 such as ``append()`` or concatenation with ``+`` are not available.
1306
1307 Note:
1308 For PdfWriter only: Provides the capability to remove a page/range of
1309 page from the list (using the del operator). Remember: Only the page
1310 entry is removed, as the objects beneath can be used elsewhere. A
1311 solution to completely remove them - if they are not used anywhere - is
1312 to write to a buffer/temporary file and then load it into a new
1313 PdfWriter.
1314
1315 """
1316 return _VirtualList(self.get_num_pages, self.get_page)
1317
1318 @property
1319 def page_labels(self) -> list[str]:
1320 """
1321 A list of labels for the pages in this document.
1322
1323 This property is read-only. The labels are in the order that the pages
1324 appear in the document.
1325 """
1326 return index2labels(self, len(self.pages))
1327
1328 @property
1329 def page_layout(self) -> str | None:
1330 """
1331 Get the page layout currently being used.
1332
1333 .. list-table:: Valid ``layout`` values
1334 :widths: 50 200
1335
1336 * - /NoLayout
1337 - Layout explicitly not specified
1338 * - /SinglePage
1339 - Show one page at a time
1340 * - /OneColumn
1341 - Show one column at a time
1342 * - /TwoColumnLeft
1343 - Show pages in two columns, odd-numbered pages on the left
1344 * - /TwoColumnRight
1345 - Show pages in two columns, odd-numbered pages on the right
1346 * - /TwoPageLeft
1347 - Show two pages at a time, odd-numbered pages on the left
1348 * - /TwoPageRight
1349 - Show two pages at a time, odd-numbered pages on the right
1350 """
1351 try:
1352 return cast(NameObject, self.root_object[CatalogAttributes.PAGE_LAYOUT])
1353 except KeyError:
1354 return None
1355
1356 @property
1357 def page_mode(self) -> PagemodeType | None:
1358 """
1359 Get the page mode currently being used.
1360
1361 .. list-table:: Valid ``mode`` values
1362 :widths: 50 200
1363
1364 * - /UseNone
1365 - Do not show outline or thumbnails panels
1366 * - /UseOutlines
1367 - Show outline (aka bookmarks) panel
1368 * - /UseThumbs
1369 - Show page thumbnails panel
1370 * - /FullScreen
1371 - Fullscreen view
1372 * - /UseOC
1373 - Show Optional Content Group (OCG) panel
1374 * - /UseAttachments
1375 - Show attachments panel
1376 """
1377 try:
1378 return self.root_object["/PageMode"] # type: ignore[return-value]
1379 except KeyError:
1380 return None
1381
1382 def _flatten(self, list_only: bool = False) -> None:
1383 """
1384 Process the document pages to ease searching.
1385
1386 Attributes of a page may inherit from ancestor nodes
1387 in the page tree. Flattening means moving
1388 any inheritance data into descendant nodes,
1389 effectively removing the inheritance dependency.
1390 The result is stored in ``self.flattened_pages``.
1391
1392 Note: It is distinct from another use of "flattening" applied to PDFs.
1393 Flattening a PDF also means combining all the contents into one single layer
1394 and making the file less editable.
1395
1396 The page tree is walked with an explicit stack instead of recursion, so the
1397 traversal is bound by ``Configuration.page_tree_maximum_depth`` and
1398 ``Configuration.page_tree_maximum_entries`` only, not by the interpreter
1399 recursion limit.
1400
1401 Args:
1402 list_only: If True, the page's own entries are not copied into the
1403 generated :class:`PageObject`. Attributes inherited from ancestor
1404 nodes are applied either way. Note that a page reached through an
1405 indirect reference is already populated by :class:`PageObject`
1406 itself, so this only has an effect for ``/Kids`` entries that are
1407 inline dictionaries.
1408
1409 """
1410 configuration = get_configuration()
1411 self.flattened_pages = None
1412 pages = self.root_object.get("/Pages", NullObject()).get_object()
1413 if not isinstance(pages, DictionaryObject):
1414 raise PdfReadError("Invalid object in /Pages")
1415
1416 flattened_pages: list[PageObject] = []
1417 traversal_state = _TraversalState()
1418 remaining_page_entries = _TraversalState(entry_count=configuration.page_tree_maximum_page_entries)
1419 # id() values of the nodes on the path from the root to the current node.
1420 # Detects multi-hop cycles such as A→B→C→A that the single-parent check misses.
1421 ancestor_ids: set[int] = set()
1422 # The /Pages nodes of that path whose /Kids are not exhausted yet.
1423 stack: list[_PageTreeFrame] = []
1424 item: _PageTreeItem | None = _PageTreeItem(
1425 node=pages, inherit={}, indirect_reference=None, depth=0
1426 )
1427 while item is not None:
1428 if item.depth > configuration.page_tree_maximum_depth:
1429 raise LimitReachedError(
1430 f"Maximum page tree depth reached: {item.depth} > {configuration.page_tree_maximum_depth}."
1431 )
1432
1433 # Get the current node_type
1434 node = item.node
1435 if PagesAttributes.TYPE in node:
1436 node_type = cast(str, node[PagesAttributes.TYPE])
1437 # if the page tree node has no /Type, consider as a page if /Kids is also missing
1438 elif PagesAttributes.KIDS not in node:
1439 # Without /Type, only accept it as a page if it carries a structural page key.
1440 if self.strict and not any(
1441 key in node for key in (PageAttributes.CONTENTS, PageAttributes.MEDIABOX, PageAttributes.PARENT)
1442 ):
1443 raise PdfReadError(f"Non-page object reached through /Kids: {node!r}")
1444 node_type = "/Page"
1445 else:
1446 node_type = "/Pages"
1447
1448 # Flatten that type of node
1449 if node_type == "/Pages":
1450 ancestor_ids.add(id(node))
1451 stack.append(self._enter_page_tree_node(item))
1452 elif node_type == "/Page":
1453 flattened_pages.append(
1454 self._flatten_leaf_page(
1455 item=item, list_only=list_only, remaining_page_entries=remaining_page_entries
1456 )
1457 )
1458
1459 item = self._pop_next_page_tree_kid(stack, ancestor_ids, traversal_state)
1460
1461 # Assigned only here, so that a failed traversal does not leave a partial page list behind.
1462 self.flattened_pages = flattened_pages
1463
1464 def _enter_page_tree_node(self, item: _PageTreeItem) -> _PageTreeFrame:
1465 """
1466 Start walking an intermediate ``/Pages`` node: propagate its inheritable
1467 attributes and pair it with an iterator over its ``/Kids``.
1468 """
1469 pages = item.node
1470 # Copied before being modified, as the kids of the enclosing node share it.
1471 inherit = dict(item.inherit)
1472 for attr in _INHERITABLE_PAGE_ATTRIBUTES:
1473 if attr in pages:
1474 inherit[attr] = pages[attr]
1475
1476 kids = pages.get(PagesAttributes.KIDS, ArrayObject()).get_object()
1477 if isinstance(kids, NullObject):
1478 kids = ArrayObject()
1479 elif not isinstance(kids, ArrayObject):
1480 raise PdfReadError(f"Expected /Kids to be an array, got {type(kids).__name__}.")
1481
1482 return item._replace(inherit=inherit), iter(kids)
1483
1484 def _pop_next_page_tree_kid(
1485 self,
1486 stack: list[_PageTreeFrame],
1487 ancestor_ids: set[int],
1488 traversal_state: _TraversalState,
1489 ) -> _PageTreeItem | None:
1490 """
1491 Return the next page tree node to flatten, leaving the ``/Pages`` nodes whose
1492 ``/Kids`` are exhausted, or ``None`` when the traversal is complete.
1493
1494 Cyclic references and the configured page-tree entry limit are enforced here.
1495 """
1496 configuration = get_configuration()
1497 while stack:
1498 parent, kids = stack[-1]
1499 pages_reference = getattr(parent.node, "indirect_reference", object())
1500 for page in kids:
1501 if getattr(page, "indirect_reference", object()) == pages_reference:
1502 raise PdfReadError("Detected cyclic page references.")
1503
1504 obj = page.get_object()
1505 if not isinstance(obj, DictionaryObject):
1506 if not is_null_or_none(obj):
1507 logger_warning(
1508 "Ignoring page tree entry that is not a dictionary: %(entry)s",
1509 source=__name__,
1510 entry=obj,
1511 )
1512 # damaged file may have invalid child in /Pages
1513 continue
1514 if not obj:
1515 # An empty dictionary would otherwise be read as a blank page.
1516 continue
1517 if id(obj) in ancestor_ids:
1518 raise PdfReadError("Detected cyclic page references.")
1519 traversal_state.entry_count += 1
1520 if traversal_state.entry_count > configuration.page_tree_maximum_entries:
1521 raise LimitReachedError(
1522 "Maximum page tree entry limit reached: "
1523 f"{traversal_state.entry_count} > {configuration.page_tree_maximum_entries}."
1524 )
1525 return _PageTreeItem(
1526 node=obj,
1527 inherit=parent.inherit,
1528 indirect_reference=page if isinstance(page, IndirectObject) else None,
1529 depth=parent.depth + 1,
1530 )
1531 stack.pop()
1532 ancestor_ids.discard(id(parent.node))
1533 return None
1534
1535 def _flatten_leaf_page(
1536 self, *, item: _PageTreeItem, list_only: bool, remaining_page_entries: _TraversalState
1537 ) -> PageObject:
1538 """
1539 Build the :class:`PageObject` for a leaf ``/Page`` node.
1540
1541 ``list_only`` suppresses copying the page's own entries; the inherited
1542 attributes are applied regardless. When the node has an indirect reference,
1543 :class:`PageObject` has already copied those entries in its constructor,
1544 so the flag only matters for inline ``/Kids`` dictionaries.
1545 """
1546 node = item.node
1547
1548 # Indirect PageObjects are populated by the constructor even when
1549 # list_only=True. Inline dictionaries are copied only when list_only=False.
1550 entry_count = (
1551 len(node)
1552 if item.indirect_reference is not None or not list_only
1553 else 0
1554 )
1555
1556 # Inherited attributes are inserted only when missing from the page.
1557 entry_count += sum(
1558 attribute not in node for attribute in item.inherit
1559 )
1560
1561 remaining_page_entries.entry_count -= entry_count
1562 if remaining_page_entries.entry_count < 0:
1563 raise LimitReachedError("Maximum page tree page entry limit exceeded!")
1564
1565 page = PageObject(self, item.indirect_reference)
1566 if not list_only:
1567 page.update(node)
1568 for attribute, value in item.inherit.items():
1569 # If the page has its own value, it does not inherit the parent's value.
1570 if attribute not in page:
1571 page[attribute] = value
1572
1573 return page
1574
1575 def remove_page(
1576 self,
1577 page: int | PageObject | IndirectObject,
1578 clean: bool = False,
1579 ) -> None:
1580 """
1581 Remove page from pages list.
1582
1583 Args:
1584 page:
1585 * :class:`int`: Page number to be removed.
1586 * :class:`~pypdf._page.PageObject`: page to be removed. If the page appears many times
1587 only the first one will be removed.
1588 * :class:`~pypdf.generic.IndirectObject`: Reference to page to be removed.
1589
1590 clean: replace PageObject with NullObject to prevent annotations
1591 or destinations to reference a detached page.
1592
1593 """
1594 if self.flattened_pages is None:
1595 self._flatten(self._readonly)
1596 assert self.flattened_pages is not None
1597 if isinstance(page, IndirectObject):
1598 p = page.get_object()
1599 if not isinstance(p, PageObject):
1600 logger_warning("IndirectObject is not referencing a page", source=__name__)
1601 return
1602 page = p
1603
1604 if not isinstance(page, int):
1605 try:
1606 page = self.flattened_pages.index(page)
1607 except ValueError:
1608 logger_warning("Cannot find page in pages", source=__name__)
1609 return
1610 if not (0 <= page < len(self.flattened_pages)):
1611 logger_warning("Page number is out of range", source=__name__)
1612 return
1613
1614 ind = self.pages[page].indirect_reference
1615 # `pages` is typed as a Sequence because it is not a list, but the
1616 # concrete _VirtualList does implement deletion.
1617 del cast(_VirtualList, self.pages)[page]
1618 if clean and ind is not None:
1619 self._replace_object(ind, NullObject())
1620
1621 def _get_indirect_object(self, num: int, gen: int) -> PdfObject | None:
1622 """
1623 Used to ease development.
1624
1625 This is equivalent to generic.IndirectObject(num,gen,self).get_object()
1626
1627 Args:
1628 num: The object number of the indirect object.
1629 gen: The generation number of the indirect object.
1630
1631 Returns:
1632 A PdfObject
1633
1634 """
1635 return IndirectObject(num, gen, self).get_object()
1636
1637 @property
1638 def user_access_permissions(self) -> UserAccessPermissions | None:
1639 """
1640 Get the user access permissions for encrypted documents.
1641 Returns None if not encrypted.
1642
1643 .. warning::
1644
1645 For AES-256 encrypted documents (R=5/R=6), the returned
1646 permissions are derived from the ``/P`` field, which is
1647 only trustworthy if the ``/Perms`` integrity check passed.
1648 Check :attr:`are_permissions_valid` to verify.
1649 """
1650 if self._encryption is None:
1651 return None
1652 return UserAccessPermissions(self._encryption.P)
1653
1654 @property
1655 def are_permissions_valid(self) -> bool | None:
1656 """
1657 Whether the ``/Perms`` integrity check passed for this document.
1658
1659 For AES-256 encrypted documents (R=5/R=6), the ``/Perms`` field
1660 is an encrypted copy of the permissions that can be verified
1661 independently. Returns ``False`` if this check fails (the ``/P``
1662 permissions may have been tampered with).
1663
1664 Returns ``None`` if the document is not encrypted or has not yet
1665 been decrypted via :meth:`decrypt()<pypdf.PdfReader.decrypt>`.
1666 Returns ``True`` for non-AES-256 encryption (no ``/Perms`` to check).
1667 """
1668 if self._encryption is None:
1669 return None
1670 if not self._encryption.is_decrypted():
1671 return None
1672 return self._encryption._are_permissions_valid
1673
1674 @property
1675 @abstractmethod
1676 def is_encrypted(self) -> bool:
1677 """
1678 Read-only boolean property showing whether this PDF file is encrypted.
1679
1680 Note that this property, if true, will remain true even after the
1681 :meth:`decrypt()<pypdf.PdfReader.decrypt>` method is called.
1682 """
1683 ... # pragma: no cover
1684
1685 @property
1686 def xfa(self) -> dict[str, bytes] | None:
1687
1688 catalog = self.root_object
1689
1690 if "/AcroForm" not in catalog or not catalog["/AcroForm"]:
1691 return None
1692
1693 tree = cast(TreeObject, catalog["/AcroForm"])
1694 retval: dict[str, bytes] = {}
1695
1696 if "/XFA" not in tree:
1697 return retval
1698
1699 fields = tree["/XFA"].get_object()
1700 if not isinstance(fields, ArrayObject):
1701 logger_warning(
1702 "XFA entry is not an array: %(fields)s",
1703 source=__name__,
1704 fields=fields,
1705 )
1706 return retval
1707
1708 accumulated_length = 0
1709 decoding_work_maximum_length = get_configuration().xfa_decoding_work_maximum_length
1710
1711 field_iterator = iter(fields)
1712 for field in field_iterator:
1713 tag = field
1714 field = next(field_iterator, None)
1715 if is_null_or_none(field):
1716 continue
1717 assert field is not None, "mypy"
1718
1719 field = cast(StreamObject | None, field.get_object())
1720 if is_null_or_none(field):
1721 continue
1722 assert field is not None, "mypy"
1723
1724 decoded_data = field.get_data()
1725 accumulated_length += len(decoded_data)
1726
1727 if accumulated_length > decoding_work_maximum_length:
1728 raise LimitReachedError(
1729 "XFA decoding exceeded the maximum accumulated "
1730 f"decoding work of {decoding_work_maximum_length} bytes."
1731 )
1732
1733 retval[tag] = decoded_data
1734 return retval
1735
1736 @property
1737 def attachments(self) -> Mapping[str, list[bytes]]:
1738 """Mapping of attachment filenames to their content."""
1739 entries: dict[str, list[EmbeddedFile]] = {}
1740
1741 for entry in self.attachment_list:
1742 for name in entry._names:
1743 entries.setdefault(name, []).append(entry)
1744
1745 return LazyDict(
1746 {
1747 name: (self._get_attachment_contents, attachment_entries)
1748 for name, attachment_entries in entries.items()
1749 }
1750 )
1751
1752 @classmethod
1753 def _get_attachment_contents(cls, entries: list[EmbeddedFile]) -> list[bytes]:
1754 return [entry.content for entry in entries]
1755
1756 @property
1757 def attachment_list(self) -> Iterator[EmbeddedFile]:
1758 """Iterable of attachment objects."""
1759 yield from EmbeddedFile._load(self.root_object, strict=self.strict)
1760
1761 @abstractmethod
1762 def _repr_mimebundle_(
1763 self,
1764 include: Iterable[str] | None = None,
1765 exclude: Iterable[str] | None = None,
1766 ) -> dict[str, Any]:
1767 """
1768 Integration into Jupyter Notebooks.
1769
1770 This method returns a dictionary that maps a mime-type to its
1771 representation.
1772
1773 .. seealso::
1774
1775 https://ipython.readthedocs.io/en/stable/config/integrating.html
1776 """
1777 ... # pragma: no cover
1778
1779
1780class LazyDict(Mapping[Any, Any]):
1781 def __init__(self, *args: Any, **kwargs: Any) -> None:
1782 self._raw_dict = dict(*args, **kwargs)
1783
1784 def __getitem__(self, key: str) -> Any:
1785 func, arg = self._raw_dict.__getitem__(key)
1786 return func(arg)
1787
1788 def __iter__(self) -> Iterator[Any]:
1789 return iter(self._raw_dict)
1790
1791 def __len__(self) -> int:
1792 return len(self._raw_dict)
1793
1794 def __str__(self) -> str:
1795 return f"LazyDict(keys={list(self.keys())})"