Source code

Download source archive ↓

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())})"