Source code

Download source archive ↓

src/pypdf/_page.py

1# Copyright (c) 2006, Mathieu Fenniak
2# Copyright (c) 2007, Ashish Kulkarni <kulkarni.ashish@gmail.com>
3#
4# All rights reserved.
5#
6# Redistribution and use in source and binary forms, with or without
7# modification, are permitted provided that the following conditions are
8# met:
9#
10# * Redistributions of source code must retain the above copyright notice,
11# this list of conditions and the following disclaimer.
12# * Redistributions in binary form must reproduce the above copyright notice,
13# this list of conditions and the following disclaimer in the documentation
14# and/or other materials provided with the distribution.
15# * The name of the author may not be used to endorse or promote products
16# derived from this software without specific prior written permission.
17#
18# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
22# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28# POSSIBILITY OF SUCH DAMAGE.
29
30import math
31from collections.abc import Callable, Iterable, Iterator, Sequence
32from copy import deepcopy
33from dataclasses import asdict, dataclass
34from decimal import Decimal
35from io import BytesIO
36from pathlib import Path
37from typing import (
38    Any,
39    Literal,
40    NoReturn,
41    cast,
42    overload,
43)
44
45from ._configuration import get_configuration
46from ._protocols import PdfCommonDocProtocol
47from ._text_extraction import (
48    _layout_mode,
49)
50from ._text_extraction._text_extractor import TextExtraction
51from ._utils import (
52    CompressedTransformationMatrix,
53    TransformationMatrixType,
54    _human_readable_bytes,
55    _TraversalState,
56    deprecation,
57    deprecation_no_replacement,
58    deprecation_with_replacement,
59    logger_warning,
60    matrix_multiply,
61)
62from .actions import Action, PageTrigger
63from .constants import (
64    _INLINE_IMAGE_KEY_MAPPING,
65    _INLINE_IMAGE_VALUE_MAPPING,
66    AnnotationDictionaryAttributes,
67    ImageAttributes,
68    PageAttributes,
69    Resources,
70)
71from .errors import PageSizeNotDefinedError, PdfReadError
72from .generic import (
73    ArrayObject,
74    ContentStream,
75    DictionaryObject,
76    EncodedStreamObject,
77    FloatObject,
78    IndirectObject,
79    NameObject,
80    NullObject,
81    NumberObject,
82    PdfObject,
83    RectangleObject,
84    StreamObject,
85    is_null_or_none,
86)
87from .generic._font import Font
88
89try:
90    from PIL.Image import Image
91
92    pil_not_imported = False
93except ImportError:
94    Image = object  # type: ignore[assignment,misc,unused-ignore]  # TODO: Remove unused-ignore on Python 3.10
95    pil_not_imported = True  # error will be raised only when using images
96
97MERGE_CROP_BOX = "cropbox"  # DEPRECATED: Use pypdf.Configuration.
98
99
100def _get_page_resources(obj: Any, inherit: bool = True) -> DictionaryObject:
101    """
102    Return the /Resources, or an empty dictionary if missing or malformed.
103
104    With ``inherit=False``, only the /Resources set on the page itself are used,
105    not those inherited from its parents.
106    """
107    if inherit:
108        resources = obj.get_inherited(key=PageAttributes.RESOURCES, default=DictionaryObject())
109    else:
110        resources = obj.get(PageAttributes.RESOURCES)
111    if is_null_or_none(resources):
112        return DictionaryObject()
113    resources = resources.get_object()
114    if not isinstance(resources, DictionaryObject):
115        logger_warning(
116            "Page resources are not a dictionary: %(resources)s",
117            source=__name__,
118            resources=resources,
119        )
120        return DictionaryObject()
121    return resources
122
123
124def _get_font_resources(resources: Any) -> DictionaryObject:
125    """Return the /Font resources, or an empty dictionary if missing or malformed."""
126    fonts = resources.get(Resources.FONT)
127    if is_null_or_none(fonts):
128        return DictionaryObject()
129    fonts = fonts.get_object()
130    if not isinstance(fonts, DictionaryObject):
131        logger_warning(
132            "Font resources are not a dictionary: %(fonts)s",
133            source=__name__,
134            fonts=fonts,
135        )
136        return DictionaryObject()
137    return fonts
138
139
140def _get_rectangle(self: Any, name: str, defaults: Iterable[str]) -> RectangleObject:
141    retval: PdfObject = self.get(name, NullObject()).get_object()
142    if isinstance(retval, RectangleObject):
143        return retval
144    if is_null_or_none(retval):
145        for d in defaults:
146            retval = self.get(d, NullObject()).get_object()
147            if not is_null_or_none(retval):
148                break
149    if not isinstance(retval, ArrayObject):
150        raise ValueError(f"Expected an array of four values for {name}, got {retval}")
151    if (length := len(retval)) != 4:
152        if length > 4:
153            # Keep backwards-compatibility with files previously written in a
154            # broken way by pypdf, which carried more than four values.
155            logger_warning(
156                "Expected four values, got %(length)d: %(retval)s",
157                source=__name__,
158                length=length,
159                retval=retval,
160            )
161            retval = RectangleObject(tuple(retval[:4]))
162        else:
163            raise ValueError(
164                f"Expected four values for {name}, got {length}: {retval}"
165            )
166    else:
167        retval = RectangleObject(retval)
168    _set_rectangle(self, name, retval)
169    return retval
170
171
172def _set_rectangle(self: Any, name: str, value: RectangleObject | float) -> None:
173    if isinstance(value, (list, tuple)) and len(value) < 4:
174        # The getter tolerates more than four values for backwards compatibility
175        # but cannot do anything with fewer, so writing them would produce a page
176        # whose box cannot be read back.
177        raise ValueError(
178            f"Expected four values for {name}, got {len(value)}: {value}"
179        )
180    self[NameObject(name)] = value
181
182
183def _delete_rectangle(self: Any, name: str) -> None:
184    del self[name]
185
186
187def _create_rectangle_accessor(name: str, fallback: Iterable[str]) -> property:
188    return property(
189        lambda self: _get_rectangle(self, name, fallback),
190        lambda self, value: _set_rectangle(self, name, value),
191        lambda self: _delete_rectangle(self, name),
192    )
193
194
195class Transformation:
196    """
197    Represent a 2D transformation.
198
199    The transformation between two coordinate systems is represented by a 3-by-3
200    transformation matrix with the following form::
201
202        a b 0
203        c d 0
204        e f 1
205
206    Because a transformation matrix has only six elements that can be changed,
207    it is usually specified in PDF as the six-element array [ a b c d e f ].
208
209    Coordinate transformations are expressed as matrix multiplications::
210
211                                 a b 0
212     [ x′ y′ 1 ] = [ x y 1 ] ×   c d 0
213                                 e f 1
214
215
216    Example:
217        >>> from pypdf import PdfWriter, Transformation
218        >>> page = PdfWriter().add_blank_page(800, 600)
219        >>> op = Transformation().scale(sx=2, sy=3).translate(tx=10, ty=20)
220        >>> page.add_transformation(op)
221
222    """
223
224    def __init__(self, ctm: CompressedTransformationMatrix = (1, 0, 0, 1, 0, 0)) -> None:
225        self.ctm = ctm
226
227    @property
228    def matrix(self) -> TransformationMatrixType:
229        """
230        Return the transformation matrix as a tuple of tuples in the form:
231
232        ((a, b, 0), (c, d, 0), (e, f, 1))
233        """
234        return (
235            (self.ctm[0], self.ctm[1], 0),
236            (self.ctm[2], self.ctm[3], 0),
237            (self.ctm[4], self.ctm[5], 1),
238        )
239
240    @staticmethod
241    def compress(matrix: TransformationMatrixType) -> CompressedTransformationMatrix:
242        """
243        Compresses the transformation matrix into a tuple of (a, b, c, d, e, f).
244
245        Args:
246            matrix: The transformation matrix as a tuple of tuples.
247
248        Returns:
249            A tuple representing the transformation matrix as (a, b, c, d, e, f)
250
251        """
252        return (
253            matrix[0][0],
254            matrix[0][1],
255            matrix[1][0],
256            matrix[1][1],
257            matrix[2][0],
258            matrix[2][1],
259        )
260
261    def _to_cm(self) -> str:
262        # Returns the cm operation string for the given transformation matrix
263        return (
264            f"{self.ctm[0]:.4f} {self.ctm[1]:.4f} {self.ctm[2]:.4f} "
265            f"{self.ctm[3]:.4f} {self.ctm[4]:.4f} {self.ctm[5]:.4f} cm"
266        )
267
268    def transform(self, m: "Transformation") -> "Transformation":
269        """
270        Apply one transformation to another.
271
272        Args:
273            m: a Transformation to apply.
274
275        Returns:
276            A new ``Transformation`` instance
277
278        Example:
279            >>> from pypdf import PdfWriter, Transformation
280            >>> height, width = 40, 50
281            >>> page = PdfWriter().add_blank_page(800, 600)
282            >>> op = Transformation((1, 0, 0, -1, 0, height)) # vertical mirror
283            >>> op = Transformation().transform(Transformation((-1, 0, 0, 1, width, 0)))  # horizontal mirror
284            >>> page.add_transformation(op)
285
286        """
287        ctm = Transformation.compress(matrix_multiply(self.matrix, m.matrix))
288        return Transformation(ctm)
289
290    def translate(self, tx: float = 0, ty: float = 0) -> "Transformation":
291        """
292        Translate the contents of a page.
293
294        Args:
295            tx: The translation along the x-axis.
296            ty: The translation along the y-axis.
297
298        Returns:
299            A new ``Transformation`` instance
300
301        """
302        m = self.ctm
303        return Transformation(ctm=(m[0], m[1], m[2], m[3], m[4] + tx, m[5] + ty))
304
305    def scale(
306        self, sx: float | None = None, sy: float | None = None
307    ) -> "Transformation":
308        """
309        Scale the contents of a page towards the origin of the coordinate system.
310
311        Typically, that is the lower-left corner of the page. That can be
312        changed by translating the contents / the page boxes.
313
314        Args:
315            sx: The scale factor along the x-axis.
316            sy: The scale factor along the y-axis.
317
318        Returns:
319            A new Transformation instance with the scaled matrix.
320
321        """
322        if sx is None and sy is None:
323            raise ValueError("Either sx or sy must be specified")
324        if sx is None:
325            sx = sy
326        if sy is None:
327            sy = sx
328        assert sx is not None
329        assert sy is not None
330        op: TransformationMatrixType = ((sx, 0, 0), (0, sy, 0), (0, 0, 1))
331        ctm = Transformation.compress(matrix_multiply(self.matrix, op))
332        return Transformation(ctm)
333
334    def rotate(self, rotation: float) -> "Transformation":
335        """
336        Rotate the contents of a page.
337
338        Args:
339            rotation: The angle of rotation in degrees.
340
341        Returns:
342            A new ``Transformation`` instance with the rotated matrix.
343
344        """
345        rotation = math.radians(rotation)
346        op: TransformationMatrixType = (
347            (math.cos(rotation), math.sin(rotation), 0),
348            (-math.sin(rotation), math.cos(rotation), 0),
349            (0, 0, 1),
350        )
351        ctm = Transformation.compress(matrix_multiply(self.matrix, op))
352        return Transformation(ctm)
353
354    def __repr__(self) -> str:
355        return f"Transformation(ctm={self.ctm})"
356
357    @overload
358    def apply_on(self, pt: list[float], as_object: bool = False) -> list[float]:
359        ...
360
361    @overload
362    def apply_on(
363        self, pt: tuple[float, float], as_object: bool = False
364    ) -> tuple[float, float]:
365        ...
366
367    def apply_on(
368        self,
369        pt: tuple[float, float] | list[float],
370        as_object: bool = False,
371    ) -> tuple[float, float] | list[float]:
372        """
373        Apply the transformation matrix on the given point.
374
375        Args:
376            pt: A tuple or list representing the point in the form (x, y).
377            as_object: If True, return items as FloatObject, otherwise as plain floats.
378
379        Returns:
380            A tuple or list representing the transformed point in the form (x', y')
381
382        """
383        typ = FloatObject if as_object else float
384        pt1 = (
385            typ(float(pt[0]) * self.ctm[0] + float(pt[1]) * self.ctm[2] + self.ctm[4]),
386            typ(float(pt[0]) * self.ctm[1] + float(pt[1]) * self.ctm[3] + self.ctm[5]),
387        )
388        return list(pt1) if isinstance(pt, list) else pt1
389
390
391@dataclass
392class ImageFile:
393    """
394    Image within the PDF file. *This object is not designed to be built.*
395
396    This object should not be modified except using :func:`ImageFile.replace` to replace the image with a new one.
397    """
398
399    name: str = ""
400    """
401    Filename as identified within the PDF file.
402
403    .. warning::
404
405        This value can contain arbitrary characters. Please make sure to sanitize it before
406        using it to write the file content to the disk for example.
407    """
408
409    data: bytes = b""
410    """
411    Data as bytes.
412    """
413
414    image: Image | None = None
415    """
416    Data as PIL image.
417    """
418
419    indirect_reference: IndirectObject | None = None
420    """
421    Reference to the object storing the stream.
422    """
423
424    is_inline: bool = False
425    """
426    True if this is an inline image (~0~, ~1~, etc.).
427    """
428
429    is_displayed: bool = False
430    """
431    True if this image is displayed in the page content stream.
432    """
433
434    def replace(self, new_image: Image, **kwargs: Any) -> None:
435        """
436        Replace the image with a new PIL image.
437
438        Args:
439            new_image (PIL.Image.Image): The new PIL image to replace the existing image.
440            **kwargs: Additional keyword arguments to pass to `Image.save()`.
441
442        Raises:
443            TypeError: If the image is inline or in a PdfReader.
444            TypeError: If the image does not belong to a PdfWriter.
445            TypeError: If `new_image` is not a PIL Image.
446
447        Note:
448            This method replaces the existing image with a new image.
449            It is not allowed for inline images or images within a PdfReader.
450            The `kwargs` parameter allows passing additional parameters
451            to `Image.save()`, such as quality.
452
453        """
454        if pil_not_imported:
455            raise ImportError(
456                "pillow is required to do image extraction. "
457                "It can be installed via 'pip install pypdf[image]'"
458            )
459
460        from ._reader import PdfReader  # noqa: PLC0415
461        from .generic import DictionaryObject, PdfObject  # noqa: PLC0415
462        from .generic._image_xobject import _xobj_to_image  # noqa: PLC0415
463
464        if self.indirect_reference is None:
465            raise TypeError("Cannot update an inline image.")
466        if not hasattr(self.indirect_reference.pdf, "_id_translated"):
467            raise TypeError("Cannot update an image not belonging to a PdfWriter.")
468        if not isinstance(new_image, Image):
469            raise TypeError("new_image shall be a PIL Image")
470        b = BytesIO()
471        new_image.save(b, "PDF", **kwargs)
472        reader = PdfReader(b)
473        page_image = reader.pages[0].images[0]
474        assert page_image.indirect_reference is not None
475        self.indirect_reference.pdf._objects[self.indirect_reference.idnum - 1] = (
476            page_image.indirect_reference.get_object()
477        )
478        cast(
479            PdfObject, self.indirect_reference.get_object()
480        ).indirect_reference = self.indirect_reference
481        # change the object attributes
482        extension, byte_stream, img = _xobj_to_image(
483            cast(DictionaryObject, self.indirect_reference.get_object()),
484            pillow_parameters=kwargs,
485        )
486        assert extension is not None
487        self.name = self.name[: self.name.rfind(".")] + extension
488        self.data = byte_stream
489        self.image = img
490
491    def __str__(self) -> str:
492        return f"{self.__class__.__name__}(name={self.name}, data: {_human_readable_bytes(len(self.data))})"
493
494    def __repr__(self) -> str:
495        return self.__str__()[:-1] + f", hash: {hash(self.data)})"
496
497
498class VirtualListImages(Sequence[ImageFile]):
499    """
500    Provides access to images referenced within a page.
501    Only one copy will be returned if the usage is used on the same page multiple times.
502    See :func:`PageObject.images` for more details.
503    """
504
505    def __init__(
506        self,
507        ids_function: Callable[[], list[str | list[str]]],
508        get_function: Callable[[str | list[str] | tuple[str]], ImageFile],
509    ) -> None:
510        self.ids_function = ids_function
511        self.get_function = get_function
512        self.current = -1
513
514    def __len__(self) -> int:
515        return len(self.ids_function())
516
517    def keys(self) -> list[str | list[str]]:
518        return self.ids_function()
519
520    def items(self) -> list[tuple[str | list[str], ImageFile]]:
521        return [(x, self.get_function(x)) for x in self.ids_function()]
522
523    @overload
524    def __getitem__(self, index: int | str | list[str]) -> ImageFile:
525        ...
526
527    @overload
528    def __getitem__(self, index: slice) -> Sequence[ImageFile]:
529        ...
530
531    def __getitem__(
532        self, index: int | slice | str | list[str] | tuple[str]
533    ) -> ImageFile | Sequence[ImageFile]:
534        lst = self.ids_function()
535        if isinstance(index, slice):
536            indices = range(*index.indices(len(self)))
537            lst = [lst[x] for x in indices]
538            cls = type(self)
539            return cls((lambda: lst), self.get_function)
540        if isinstance(index, (str, list, tuple)):
541            return self.get_function(index)
542        if not isinstance(index, int):
543            raise TypeError("Invalid sequence indices type")
544        len_self = len(lst)
545        if index < 0:
546            # support negative indexes
547            index += len_self
548        if not (0 <= index < len_self):
549            raise IndexError("Sequence index out of range")
550        return self.get_function(lst[index])
551
552    def __iter__(self) -> Iterator[ImageFile]:
553        for image_id in self.ids_function():
554            yield self.get_function(image_id)
555
556    def __str__(self) -> str:
557        p = [f"Image_{i}={n}" for i, n in enumerate(self.ids_function())]
558        return f"[{', '.join(p)}]"
559
560
561class PageObject(DictionaryObject):
562    """
563    PageObject represents a single page within a PDF file.
564
565    Typically these objects will be created by accessing the
566    :attr:`pages<pypdf.PdfReader.pages>` property of the
567    :class:`PdfReader<pypdf.PdfReader>` class, but it is
568    also possible to create an empty page with the
569    :meth:`create_blank_page()<pypdf._page.PageObject.create_blank_page>` static method.
570
571    Args:
572        pdf: PDF file the page belongs to.
573        indirect_reference: Stores the original indirect reference to
574            this object in its source PDF
575
576    """
577
578    original_page: "PageObject"  # very local use in writer when appending
579
580    def __init__(
581        self,
582        pdf: PdfCommonDocProtocol | None = None,
583        indirect_reference: IndirectObject | None = None,
584    ) -> None:
585        DictionaryObject.__init__(self)
586        self.pdf = pdf
587        self._content_stream_images: dict[str, ImageFile | None] | None = None
588        self.indirect_reference = indirect_reference
589        if not is_null_or_none(indirect_reference):
590            assert indirect_reference is not None, "mypy"
591            self.update(cast(DictionaryObject, indirect_reference.get_object()))
592
593    def hash_bin(self) -> int:
594        """
595        Used to detect modified object.
596
597        Note: this function is overloaded to return the same results
598        as a DictionaryObject.
599
600        Returns:
601            Hash considering type and value.
602
603        """
604        return hash(
605            (DictionaryObject, tuple(((k, v.hash_bin()) for k, v in self.items())))
606        )
607
608    def hash_value_data(self) -> bytes:
609        data = super().hash_value_data()
610        data += f"{id(self)}".encode()
611        return data
612
613    @property
614    def user_unit(self) -> float:
615        """
616        A read-only positive number giving the size of user space units.
617
618        It is in multiples of 1/72 inch. Hence a value of 1 means a user
619        space unit is 1/72 inch, and a value of 3 means that a user
620        space unit is 3/72 inch.
621        """
622        return cast(float, self.get(PageAttributes.USER_UNIT, 1))
623
624    @staticmethod
625    def create_blank_page(
626        pdf: PdfCommonDocProtocol | None = None,
627        width: float | Decimal | None = None,
628        height: float | Decimal | None = None,
629    ) -> "PageObject":
630        """
631        Return a new blank page.
632
633        If ``width`` or ``height`` is ``None``, try to get the page size
634        from the last page of *pdf*.
635
636        Args:
637            pdf: PDF file the page is within.
638            width: The width of the new page expressed in default user
639                space units.
640            height: The height of the new page expressed in default user
641                space units.
642
643        Returns:
644            The new blank page
645
646        Raises:
647            PageSizeNotDefinedError: if ``pdf`` is ``None`` or contains
648                no page
649
650        """
651        page = PageObject(pdf)
652
653        # Creates a new page (cf PDF Reference §7.7.3.3)
654        page.__setitem__(NameObject(PageAttributes.TYPE), NameObject("/Page"))
655        page.__setitem__(NameObject(PageAttributes.PARENT), NullObject())
656        page.__setitem__(NameObject(PageAttributes.RESOURCES), DictionaryObject())
657        if width is None or height is None:
658            if pdf is not None and len(pdf.pages) > 0:
659                lastpage = pdf.pages[len(pdf.pages) - 1]
660                width = lastpage.mediabox.width
661                height = lastpage.mediabox.height
662            else:
663                raise PageSizeNotDefinedError
664        page.__setitem__(
665            NameObject(PageAttributes.MEDIABOX), RectangleObject((0, 0, width, height))
666        )
667
668        return page
669
670    def _get_ids_image(
671        self,
672        obj: DictionaryObject | None = None,
673        ancest: list[str] | None = None,
674        call_stack: list[Any] | None = None,
675    ) -> list[str | list[str]]:
676        if call_stack is None:
677            call_stack = []
678        _i = getattr(obj, "indirect_reference", None)
679        if _i in call_stack:
680            return []
681        call_stack.append(_i)
682        if self._content_stream_images is None:
683            self._content_stream_images = self._parse_images_from_content_stream()
684        if obj is None:
685            obj = self
686        if ancest is None:
687            ancest = []
688        lst: list[str | list[str]] = []
689        resources = obj.get(PageAttributes.RESOURCES, NullObject()).get_object()
690        if not isinstance(resources, DictionaryObject):
691            if not is_null_or_none(resources):
692                logger_warning(
693                    "Resources are not a dictionary: %(resources)s",
694                    source=__name__,
695                    resources=resources,
696                )
697            resources = DictionaryObject()
698        if Resources.XOBJECT not in resources:
699            # Forms without XObject resources have no images inside them
700            if len(ancest) > 0:
701                return []
702            # for inline images, cache dict entries are not None
703            return [image_name for image_name, image_value in self._content_stream_images.items() if image_value]
704
705        x_object = resources[Resources.XOBJECT].get_object()
706        if not isinstance(x_object, DictionaryObject):
707            logger_warning(
708                "XObject resources are not a dictionary: %(x_object)s",
709                source=__name__,
710                x_object=x_object,
711            )
712            return []
713
714        # Iterate through all XObject resources
715        for o in x_object:
716            entry = x_object[o]
717            # Skip non-stream objects (only process StreamObject)
718            if not isinstance(entry, StreamObject):
719                continue
720            if entry.get(ImageAttributes.SUBTYPE, "") == "/Image":
721                # If it's an image, add it to lst for further processing
722                lst.append(o if len(ancest) == 0 else [*ancest, o])
723            else:
724                # If it's a form, recursively search for images inside it
725                # Forms may contain images that are Do-referenced in their content stream
726                lst.extend(self._get_ids_image(entry, [*ancest, o], call_stack))
727
728        # Removes duplicates and preserves order
729        deduplicated = lst.copy()
730
731        # Add inline images from _content_stream_images
732        for object_name, object_value in self._content_stream_images.items():
733            # inline images have cache populated
734            if object_name not in deduplicated and object_value:
735                deduplicated.append(object_name)
736
737        return deduplicated
738
739    def _get_image(
740        self,
741        image_id: str | list[str] | tuple[str],
742        obj: DictionaryObject | None = None,
743    ) -> ImageFile:
744        if obj is None:
745            obj = cast(DictionaryObject, self)
746        if isinstance(image_id, tuple):
747            image_id = list(image_id)
748        if isinstance(image_id, list) and len(image_id) == 1:
749            image_id = image_id[0]
750        xobjs: DictionaryObject | None = None
751        resources = obj.get(PageAttributes.RESOURCES, NullObject()).get_object()
752        if isinstance(resources, DictionaryObject) and Resources.XOBJECT in resources:
753            xobjs = cast(DictionaryObject, resources[Resources.XOBJECT])
754        elif not (image_id[0] == "~" and image_id[-1] == "~"):
755            raise KeyError(
756                f"Cannot access image object {image_id} without XObject resources"
757            )
758        if isinstance(image_id, str):
759            if image_id[0] == "~" and image_id[-1] == "~":
760                if self._content_stream_images is None:
761                    self._content_stream_images = self._parse_images_from_content_stream()
762                if image_id not in self._content_stream_images:
763                    raise KeyError(f"Image {image_id} not found")
764                image_file = self._content_stream_images[image_id]
765                assert image_file is not None
766                return image_file
767
768            # Do-referenced image name (non-inline string keys like /Im0)
769            assert xobjs is not None
770            if image_id not in xobjs:
771                raise KeyError(f"Image {image_id} not found")
772            xobj = cast(DictionaryObject, xobjs[image_id])
773            if xobj.get(ImageAttributes.SUBTYPE, "") != "/Image":
774                raise KeyError(f"XObject {image_id} is not an image")
775
776            # Check if displayed (in content stream)
777            is_displayed = self._content_stream_images is not None and image_id in self._content_stream_images
778
779            from .generic._image_xobject import _xobj_to_image  # noqa: PLC0415
780            extension, byte_stream, img = _xobj_to_image(xobj)
781            return ImageFile(
782                name=f"{image_id[1:]}{extension}",
783                data=byte_stream,
784                image=img,
785                indirect_reference=xobj.indirect_reference,
786                is_inline=False,
787                is_displayed=is_displayed,
788            )
789        # in a subobject
790        assert xobjs is not None
791        ids = image_id[1:]
792        return self._get_image(ids, cast(DictionaryObject, xobjs[image_id[0]]))
793
794    @property
795    def images(self) -> VirtualListImages:
796        """
797        Read-only property emulating a list of images on a page.
798
799        Get a list of all images on the page. The key can be:
800        - A string (for the top object)
801        - A tuple (for images within XObject forms)
802        - An integer
803
804        Examples:
805            * `reader.pages[0].images[0]`        # return first image
806            * `reader.pages[0].images['/I0']`    # return image '/I0'
807            * `reader.pages[0].images['/TP1','/Image1']` # return image '/Image1' within '/TP1' XObject form
808            * `for img in reader.pages[0].images:` # loops through all objects
809
810        Example usage:
811
812            >>> from pypdf import PdfWriter
813            >>> writer = PdfWriter()
814            >>> page = writer.add_blank_page(800, 600)
815            >>> images = page.images
816
817        """
818        return VirtualListImages(self._get_ids_image, self._get_image)
819
820    @property
821    def inline_images(self) -> NoReturn:
822        """
823        Return only inline images from the page.
824
825        .. deprecated::
826            Use :attr:`images` and filter by :attr:`ImageFile.is_inline` instead.
827            This property has been removed in pypdf 7.0.
828
829        Examples:
830            >>> from pypdf import PdfWriter
831            >>> writer = PdfWriter()
832            >>> page = writer.add_blank_page(800,600)
833            >>> for image_name, image_file in page.images.items():
834            ...     if image_file.is_inline:
835            ...         print(f"{image_name} is inline")
836        """
837        deprecation_with_replacement(
838            "PageObject.inline_images",
839            "PageObject.images",
840            "7.0.0",
841        )
842
843    @inline_images.setter
844    def inline_images(self, value: dict[str, ImageFile] | None) -> NoReturn:
845        deprecation_no_replacement(
846            "PageObject.inline_images",
847            "7.0.0",
848        )
849
850    def _translate_value_inline_image(self, k: str, v: PdfObject) -> PdfObject:
851        """Translate values used in inline image"""
852        try:
853            v = NameObject(_INLINE_IMAGE_VALUE_MAPPING[cast(str, v)])
854        except (TypeError, KeyError) as exception:
855            if isinstance(v, NameObject):
856                # It is a custom name, thus we have to look in resources.
857                # The only applicable case is for ColorSpace.
858                resources = self.get("/Resources", NullObject()).get_object()
859                if not isinstance(resources, DictionaryObject):
860                    if not is_null_or_none(resources):
861                        logger_warning(
862                            "Resources are not a dictionary: %(resources)s",
863                            source=__name__,
864                            resources=resources,
865                        )
866                    resources = DictionaryObject()
867                if "/ColorSpace" in resources and v in (
868                    color_space := cast(DictionaryObject, resources["/ColorSpace"])
869                ):
870                    return color_space[v]
871                raise PdfReadError(f"Cannot find resource entry {v} for {k}") from exception
872        return v
873
874    def _parse_images_from_content_stream(self) -> dict[str, ImageFile | None]:
875        """Load images from content stream. Includes both inline images and Do-referenced images.
876
877        This method scans the page content stream and extracts:
878
879        1. **Inline images** (~0~, ~1~...): Embedded directly in content stream via BI/EI operators
880           - is_inline=True, is_displayed=True, indirect_reference=None
881
882        2. **Do-referenced objects** (/Im0, /Im1..., /Form1...): Referenced via "Do" operator
883           - is_inline=False, is_displayed=True, indirect_reference=<image object>
884
885        3. **Pure XObject images** (/I0, /Image1...): Defined in Resources only (not in content stream)
886           - is_inline=False, is_displayed=False, indirect_reference=<image object>
887
888        Returns:
889            Dictionary mapping names to ImageFile instances (inline) or None (Do-referenced).
890        """
891        content = self.get_contents()
892        if is_null_or_none(content):
893            return {}
894        imgs_data = []
895        do_image_names: list[bytes] = []
896        assert content is not None, "mypy"
897        for param, ope in content.operations:
898            if ope == b"INLINE IMAGE":
899                imgs_data.append(
900                    {"settings": param["settings"], "__streamdata__": param["data"]}
901                )
902            elif ope == b"Do" and param:
903                do_image_names.append(param[0])  # First operand is the XObject name
904            elif ope in (b"BI", b"EI", b"ID"):  # pragma: no cover
905                raise PdfReadError(
906                    f"{ope!r} operator met whereas not expected, "
907                    "please share use case with pypdf dev team"
908                )
909
910        files: dict[str, ImageFile | None] = {}
911        # Process Do-referenced objects first (images + forms, no subtype check)
912        files = dict.fromkeys(list(map(str, do_image_names)), None)
913
914        # Then process inline images
915        for num, ii in enumerate(imgs_data):
916            init = {
917                "__streamdata__": ii["__streamdata__"],
918                "/Length": len(ii["__streamdata__"]),
919            }
920            for k, v in ii["settings"].items():
921                if k in {"/Length", "/L"}:  # no length is expected
922                    continue
923                if isinstance(v, list):
924                    v = ArrayObject(
925                        [self._translate_value_inline_image(k, x) for x in v]
926                    )
927                else:
928                    v = self._translate_value_inline_image(k, v)
929                if k in _INLINE_IMAGE_KEY_MAPPING:
930                    k = NameObject(_INLINE_IMAGE_KEY_MAPPING[k])
931                else:
932                    logger_warning(
933                        "Unknown inline image key %(key)s, keeping it as-is.",
934                        source=__name__,
935                        key=k,
936                    )
937                    k = NameObject(k)
938                if k not in init:
939                    init[k] = v
940            ii["object"] = EncodedStreamObject.initialize_from_dictionary(init)
941            from .generic._image_xobject import _xobj_to_image  # noqa: PLC0415
942            extension, byte_stream, img = _xobj_to_image(ii["object"])
943            files[f"~{num}~"] = ImageFile(
944                name=f"~{num}~{extension}",
945                data=byte_stream,
946                image=img,
947                indirect_reference=None,
948                is_inline=True,
949                is_displayed=True,
950            )
951
952        return files
953
954    @property
955    def rotation(self) -> int:
956        """
957        The visual rotation of the page.
958
959        This number has to be a multiple of 90 degrees: 0, 90, 180, or 270 are
960        valid values. This property does not affect ``/Contents``.
961        """
962        rotate_obj = self.get(PageAttributes.ROTATE, 0)
963        return rotate_obj if isinstance(rotate_obj, int) else rotate_obj.get_object()
964
965    @rotation.setter
966    def rotation(self, r: float) -> None:
967        self[NameObject(PageAttributes.ROTATE)] = NumberObject((((int(r) + 45) // 90) * 90) % 360)
968
969    def transfer_rotation_to_content(self) -> None:
970        """
971        Apply the rotation of the page to the content and the media/crop/...
972        boxes.
973
974        It is recommended to apply this function before page merging.
975        """
976        r = -self.rotation  # rotation to apply is in the otherway
977        self.rotation = 0
978        mb = RectangleObject(self.mediabox)
979        trsf = (
980            Transformation()
981            .translate(
982                -float(mb.left + mb.width / 2), -float(mb.bottom + mb.height / 2)
983            )
984            .rotate(r)
985        )
986        pt1 = trsf.apply_on(mb.lower_left)
987        pt2 = trsf.apply_on(mb.upper_right)
988        trsf = trsf.translate(-min(pt1[0], pt2[0]), -min(pt1[1], pt2[1]))
989        self.add_transformation(trsf, False)
990        for b in ["/MediaBox", "/CropBox", "/BleedBox", "/TrimBox", "/ArtBox"]:
991            if b in self:
992                rr = RectangleObject(self[b])  # type: ignore[arg-type]
993                pt1 = trsf.apply_on(rr.lower_left)
994                pt2 = trsf.apply_on(rr.upper_right)
995                self[NameObject(b)] = RectangleObject(
996                    (
997                        min(pt1[0], pt2[0]),
998                        min(pt1[1], pt2[1]),
999                        max(pt1[0], pt2[0]),
1000                        max(pt1[1], pt2[1]),
1001                    )
1002                )
1003
1004    def rotate(self, angle: int) -> "PageObject":
1005        """
1006        Rotate a page clockwise by increments of 90 degrees.
1007
1008        Args:
1009            angle: Angle to rotate the page. Must be an increment of 90 deg.
1010
1011        Returns:
1012            The rotated PageObject
1013
1014        """
1015        if angle % 90 != 0:
1016            raise ValueError("Rotation angle must be a multiple of 90")
1017        self[NameObject(PageAttributes.ROTATE)] = NumberObject(self.rotation + angle)
1018        return self
1019
1020    def _merge_resources(
1021        self,
1022        res1: DictionaryObject,
1023        res2: DictionaryObject,
1024        resource: Any,
1025        new_res1: bool = True,
1026    ) -> tuple[dict[str, Any], dict[str, Any]]:
1027        try:
1028            assert isinstance(self.indirect_reference, IndirectObject)
1029            pdf = self.indirect_reference.pdf
1030            is_pdf_writer = hasattr(
1031                pdf, "_add_object"
1032            )  # expect isinstance(pdf, PdfWriter)
1033        except (AssertionError, AttributeError):
1034            pdf = None
1035            is_pdf_writer = False
1036
1037        def compute_unique_key(base_key: str) -> tuple[str, bool]:
1038            """
1039            Find a key that either doesn't already exist or has the same value
1040            (indicated by the bool)
1041
1042            Args:
1043                base_key: An index is added to this to get the computed key
1044
1045            Returns:
1046                A tuple (computed key, bool) where the boolean indicates
1047                if there is a resource of the given computed_key with the same
1048                value.
1049
1050            """
1051            value = page2res.raw_get(base_key)
1052            # TODO: a possible improvement for writer, the indirect_reference
1053            # cannot be found because translated
1054
1055            # try the current key first (e.g. "foo"), but otherwise iterate
1056            # through "foo-0", "foo-1", etc. new_res can contain only finitely
1057            # many keys, thus this'll eventually end, even if it's been crafted
1058            # to be maximally annoying.
1059            computed_key = base_key
1060            idx = 0
1061            while computed_key in new_res:
1062                if new_res.raw_get(computed_key) == value:
1063                    # there's already a resource of this name, with the exact
1064                    # same value
1065                    return computed_key, True
1066                computed_key = f"{base_key}-{idx}"
1067                idx += 1
1068            return computed_key, False
1069
1070        if new_res1:
1071            new_res = DictionaryObject()
1072            new_res.update(res1.get(resource, DictionaryObject()).get_object())
1073        else:
1074            new_res = cast(DictionaryObject, res1[resource])
1075        page2res = cast(
1076            DictionaryObject, res2.get(resource, DictionaryObject()).get_object()
1077        )
1078        rename_res = {}
1079        for key in page2res:
1080            unique_key, same_value = compute_unique_key(key)
1081            newname = NameObject(unique_key)
1082            if key != unique_key:
1083                # we have to use a different name for this
1084                rename_res[key] = newname
1085
1086            if not same_value:
1087                if is_pdf_writer:
1088                    new_res[newname] = page2res.raw_get(key).clone(pdf)
1089                    try:
1090                        new_res[newname] = new_res[newname].indirect_reference
1091                    except AttributeError:
1092                        pass
1093                else:
1094                    new_res[newname] = page2res.raw_get(key)
1095            lst = sorted(new_res.items())
1096            new_res.clear()
1097            for el in lst:
1098                new_res[el[0]] = el[1]
1099        return new_res, rename_res
1100
1101    @staticmethod
1102    def _content_stream_rename(
1103        stream: ContentStream,
1104        rename: dict[Any, Any],
1105        pdf: PdfCommonDocProtocol | None,
1106    ) -> ContentStream:
1107        if not rename:
1108            return stream
1109        stream = ContentStream(stream, pdf)
1110        for operands, _operator in stream.operations:
1111            if isinstance(operands, list):
1112                for i, op in enumerate(operands):
1113                    if isinstance(op, NameObject):
1114                        operands[i] = rename.get(op, op)
1115            elif isinstance(operands, dict):
1116                for i, op in operands.items():
1117                    if isinstance(op, NameObject):
1118                        operands[i] = rename.get(op, op)
1119            else:
1120                raise KeyError(f"Type of operands is {type(operands)}")
1121        return stream
1122
1123    @staticmethod
1124    def _add_transformation_matrix(
1125        contents: Any,
1126        pdf: PdfCommonDocProtocol | None,
1127        ctm: CompressedTransformationMatrix,
1128    ) -> ContentStream:
1129        """Add transformation matrix at the beginning of the given contents stream."""
1130        content_stream = ContentStream(contents, pdf)
1131        content_stream.operations.insert(
1132            0,
1133            (
1134                [FloatObject(x) for x in ctm],
1135                b"cm",
1136            ),
1137        )
1138        return content_stream
1139
1140    def _get_contents_as_bytes(self) -> bytes | None:
1141        """
1142        Return the page contents as bytes.
1143
1144        Returns:
1145            The ``/Contents`` object as bytes, or ``None`` if it doesn't exist.
1146
1147        """
1148        if PageAttributes.CONTENTS in self:
1149            obj = self[PageAttributes.CONTENTS].get_object()
1150            if isinstance(obj, list):
1151                return b"".join(x.get_object().get_data() for x in obj)
1152            return cast(EncodedStreamObject, obj).get_data()
1153        return None
1154
1155    def get_contents(self) -> ContentStream | None:
1156        """
1157        Access the page contents.
1158
1159        Returns:
1160            The ``/Contents`` object, or ``None`` if it does not exist.
1161            ``/Contents`` is optional, as described in §7.7.3.3 of the PDF Reference.
1162
1163        """
1164        if PageAttributes.CONTENTS in self:
1165            try:
1166                pdf = cast(IndirectObject, self.indirect_reference).pdf
1167            except AttributeError:
1168                pdf = None
1169            obj = self[PageAttributes.CONTENTS]
1170            if is_null_or_none(obj):
1171                return None
1172            resolved_object = obj.get_object()
1173            if not isinstance(resolved_object, (ArrayObject, StreamObject)):
1174                logger_warning(
1175                    "Page contents are not a stream or an array: %(contents)s",
1176                    source=__name__,
1177                    contents=resolved_object,
1178                )
1179                return None
1180            return ContentStream(resolved_object, pdf)
1181        return None
1182
1183    def replace_contents(
1184        self, content: ContentStream | EncodedStreamObject | ArrayObject | None
1185    ) -> None:
1186        """
1187        Replace the page contents with the new content and nullify old objects
1188        Args:
1189            content: new content; if None delete the content field.
1190        """
1191        if not hasattr(self, "indirect_reference") or self.indirect_reference is None:
1192            # the page is not attached : the content is directly attached.
1193            self[NameObject(PageAttributes.CONTENTS)] = content
1194            return
1195
1196        from pypdf._writer import PdfWriter  # noqa: PLC0415
1197        if not isinstance(self.indirect_reference.pdf, PdfWriter):
1198            deprecation(
1199                "Calling `PageObject.replace_contents()` for pages not assigned to a writer is deprecated "
1200                "and has been removed in pypdf 7.0.0. Attach the page to the writer first or use "
1201                "`PdfWriter(clone_from=...)` directly. The existing approach has proved being unreliable."
1202            )
1203
1204        writer = self.indirect_reference.pdf
1205        # Resolve /Contents because it may be an indirect reference to an
1206        # ArrayObject. Without resolving it, an indirect contents array is not
1207        # recognized and its stream objects are left in the writer's object list.
1208        old_contents = self.get(PageAttributes.CONTENTS, None)
1209        if old_contents is not None:
1210            old_contents = old_contents.get_object()
1211        if isinstance(old_contents, ArrayObject):
1212            for reference in old_contents:
1213                if not isinstance(reference, IndirectObject):
1214                    # Direct objects are not part of the writer's object list.
1215                    continue
1216                writer._replace_object(indirect_reference=reference, obj=NullObject())
1217
1218        if isinstance(content, ArrayObject):
1219            content = ArrayObject(writer._add_object(obj) for obj in content)
1220
1221        if is_null_or_none(content):
1222            if PageAttributes.CONTENTS not in self:
1223                return
1224            contents_reference = self[PageAttributes.CONTENTS].indirect_reference
1225            assert contents_reference is not None, "mypy"
1226            writer._replace_object(indirect_reference=contents_reference, obj=NullObject())
1227            del self[PageAttributes.CONTENTS]
1228        elif not hasattr(self.get(PageAttributes.CONTENTS, None), "indirect_reference"):
1229            assert content is not None, "mypy"
1230            self[NameObject(PageAttributes.CONTENTS)] = writer._add_object(content)
1231        else:
1232            assert content is not None, "mypy"
1233            content.indirect_reference = self[
1234                PageAttributes.CONTENTS
1235            ].indirect_reference  # TODO: in the future may require generation management
1236            assert content.indirect_reference is not None, "mypy"
1237            writer._replace_object(indirect_reference=content.indirect_reference, obj=content)
1238        # forces recalculation of images
1239        self._content_stream_images = None
1240
1241    def merge_page(
1242        self, page2: "PageObject", expand: bool = False, over: bool = True
1243    ) -> None:
1244        """
1245        Merge the content streams of two pages into one.
1246
1247        Resource references (e.g. fonts) are maintained from both pages.
1248        The mediabox, cropbox, etc of this page are not altered.
1249        The parameter page's content stream will
1250        be added to the end of this page's content stream,
1251        meaning that it will be drawn after, or "on top" of this page.
1252
1253        Args:
1254            page2: The page to be merged into this one. Should be
1255                an instance of :class:`PageObject<PageObject>`.
1256            over: set the page2 content over page1 if True (default) else under
1257            expand: If True, the current page dimensions will be
1258                expanded to accommodate the dimensions of the page to be merged.
1259
1260        """
1261        self._merge_page(page2, over=over, expand=expand)
1262
1263    def _merge_page(
1264        self,
1265        page2: "PageObject",
1266        page2_transformation: Callable[[Any], ContentStream] | None = None,
1267        ctm: CompressedTransformationMatrix | None = None,
1268        over: bool = True,
1269        expand: bool = False,
1270    ) -> None:
1271        # First we work on merging the resource dictionaries. This allows us
1272        # to find out what symbols in the content streams we might need to
1273        # rename.
1274        try:
1275            assert isinstance(self.indirect_reference, IndirectObject)
1276            if hasattr(self.indirect_reference.pdf, "_add_object"):  # to detect PdfWriter
1277                return self._merge_page_writer(
1278                    page2, page2_transformation, ctm, over, expand
1279                )
1280        except (AssertionError, AttributeError):
1281            pass
1282
1283        new_resources = DictionaryObject()
1284        rename: dict[str, Any] = {}
1285        original_resources = cast(DictionaryObject, self.get(PageAttributes.RESOURCES, DictionaryObject()).get_object())
1286        page2_resources = cast(DictionaryObject, page2.get(PageAttributes.RESOURCES, DictionaryObject()).get_object())
1287        new_annots = ArrayObject()
1288
1289        for page in (self, page2):
1290            if PageAttributes.ANNOTS in page:
1291                annots = page[PageAttributes.ANNOTS]
1292                if isinstance(annots, ArrayObject):
1293                    new_annots.extend(annots)
1294        self[NameObject(PageAttributes.ANNOTS)] = new_annots
1295
1296        for res in (
1297            Resources.EXT_G_STATE,
1298            Resources.COLOR_SPACE,
1299            Resources.PATTERN,
1300            Resources.SHADING,
1301            Resources.XOBJECT,
1302            Resources.FONT,
1303            Resources.PROPERTIES,
1304        ):
1305            new, new_resource_name = self._merge_resources(
1306                original_resources, page2_resources, res
1307            )
1308            if new:
1309                new_resources[NameObject(res)] = new
1310                rename.update(new_resource_name)
1311
1312        # Combine /ProcSet sets, making sure there is a consistent order
1313        new_resources[NameObject(Resources.PROC_SET)] = ArrayObject(
1314            sorted(
1315                set(
1316                    original_resources.get(Resources.PROC_SET, ArrayObject()).get_object()
1317                ).union(
1318                    set(page2_resources.get(Resources.PROC_SET, ArrayObject()).get_object())
1319                )
1320            )
1321        )
1322
1323        new_content_array = ArrayObject()
1324        original_content = self.get_contents()
1325        if original_content is not None:
1326            original_content.isolate_graphics_state()
1327            new_content_array.append(original_content)
1328
1329        page2_content = page2.get_contents()
1330        if page2_content is not None:
1331            configuration = get_configuration()
1332            rect = getattr(page2, configuration.page_merge_box)
1333            page2_content.operations.insert(
1334                0,
1335                (
1336                    map(
1337                        FloatObject,
1338                        [
1339                            rect.left,
1340                            rect.bottom,
1341                            rect.width,
1342                            rect.height,
1343                        ],
1344                    ),
1345                    b"re",
1346                ),
1347            )
1348            page2_content.operations.insert(1, ([], b"W"))
1349            page2_content.operations.insert(2, ([], b"n"))
1350            if page2_transformation is not None:
1351                page2_content = page2_transformation(page2_content)
1352            page2_content = PageObject._content_stream_rename(
1353                page2_content, rename, self.pdf
1354            )
1355            page2_content.isolate_graphics_state()
1356            if over:
1357                new_content_array.append(page2_content)
1358            else:
1359                new_content_array.insert(0, page2_content)
1360
1361        # if expanding the page to fit a new page, calculate the new media box size
1362        if expand:
1363            self._expand_mediabox(page2, ctm)
1364
1365        self.replace_contents(ContentStream(new_content_array, self.pdf))
1366        self[NameObject(PageAttributes.RESOURCES)] = new_resources
1367
1368        return None
1369
1370    def _merge_page_writer(
1371        self,
1372        page2: "PageObject",
1373        page2transformation: Callable[[Any], ContentStream] | None = None,
1374        ctm: CompressedTransformationMatrix | None = None,
1375        over: bool = True,
1376        expand: bool = False,
1377    ) -> None:
1378        # First we work on merging the resource dictionaries. This allows us
1379        # to find which symbols in the content streams we might need to
1380        # rename.
1381        assert isinstance(self.indirect_reference, IndirectObject)
1382        pdf = self.indirect_reference.pdf
1383
1384        original_resources = _get_page_resources(self, inherit=False)
1385        if self.get(PageAttributes.RESOURCES, NullObject()).get_object() is not original_resources:
1386            # missing, null or malformed: the merged resources are stored in a new dictionary
1387            self[NameObject(PageAttributes.RESOURCES)] = original_resources
1388        page2resources = _get_page_resources(page2, inherit=False)
1389
1390        rename = {}
1391        for res in (
1392            Resources.EXT_G_STATE,
1393            Resources.COLOR_SPACE,
1394            Resources.PATTERN,
1395            Resources.SHADING,
1396            Resources.XOBJECT,
1397            Resources.FONT,
1398            Resources.PROPERTIES,
1399        ):
1400            if res in page2resources:
1401                if res not in original_resources:
1402                    original_resources[NameObject(res)] = DictionaryObject()
1403                _, newrename = self._merge_resources(
1404                    original_resources, page2resources, res, False
1405                )
1406                rename.update(newrename)
1407        # Combine /ProcSet sets
1408        if Resources.PROC_SET in page2resources:
1409            if Resources.PROC_SET not in original_resources:
1410                original_resources[NameObject(Resources.PROC_SET)] = ArrayObject()
1411            arr = cast(ArrayObject, original_resources[Resources.PROC_SET])
1412            for x in cast(ArrayObject, page2resources[Resources.PROC_SET]):
1413                if x not in arr:
1414                    arr.append(x)
1415            arr.sort()
1416
1417        if not is_null_or_none(page2.get(PageAttributes.ANNOTS, None)):
1418            annots = self.get(PageAttributes.ANNOTS, NullObject()).get_object()
1419            if not isinstance(annots, ArrayObject):
1420                if not is_null_or_none(annots):
1421                    logger_warning(
1422                        "Annotations are not an array: %(annotations)s",
1423                        source=__name__,
1424                        annotations=annots,
1425                    )
1426                annots = ArrayObject()
1427                self[NameObject(PageAttributes.ANNOTS)] = annots
1428            if ctm is None:
1429                trsf = Transformation()
1430            else:
1431                trsf = Transformation(ctm)
1432            # Ensure we are working on a copy of the list. Otherwise, if both pages
1433            # are the same object, we might run into an infinite loop.
1434            for a in cast(ArrayObject, deepcopy(page2[PageAttributes.ANNOTS])):
1435                a = a.get_object()
1436                aa = a.clone(
1437                    pdf,
1438                    ignore_fields=("/P", "/StructParent", "/Parent"),
1439                    force_duplicate=True,
1440                )
1441                r = cast(ArrayObject, a["/Rect"])
1442                pt1 = trsf.apply_on((r[0], r[1]), True)
1443                pt2 = trsf.apply_on((r[2], r[3]), True)
1444                aa[NameObject("/Rect")] = ArrayObject(
1445                    (
1446                        min(pt1[0], pt2[0]),
1447                        min(pt1[1], pt2[1]),
1448                        max(pt1[0], pt2[0]),
1449                        max(pt1[1], pt2[1]),
1450                    )
1451                )
1452                if "/QuadPoints" in a:
1453                    q = cast(ArrayObject, a["/QuadPoints"])
1454                    aa[NameObject("/QuadPoints")] = ArrayObject(
1455                        value
1456                        for i in range(0, len(q), 2)
1457                        for value in trsf.apply_on((q[i], q[i + 1]), True)
1458                    )
1459                # The /Rect update above only repositions and resizes the
1460                # annotation's bounding box; it does not touch the
1461                # appearance stream's own coordinate system. See
1462                # transform_annotation_appearance for why that matters.
1463                from pypdf.generic._appearance_stream import (  # noqa: PLC0415
1464                    transform_annotation_appearance,
1465                )
1466                transform_annotation_appearance(aa, trsf)
1467                try:
1468                    aa["/Popup"][NameObject("/Parent")] = aa.indirect_reference
1469                except KeyError:
1470                    pass
1471                aa[NameObject("/P")] = self.indirect_reference
1472                annots.append(aa.indirect_reference)
1473
1474        new_content_array = ArrayObject()
1475        original_content = self.get_contents()
1476        if original_content is not None:
1477            original_content.isolate_graphics_state()
1478            new_content_array.append(original_content)
1479
1480        page2content = page2.get_contents()
1481        if page2content is not None:
1482            configuration = get_configuration()
1483            rect = getattr(page2, configuration.page_merge_box)
1484            page2content.operations.insert(
1485                0,
1486                (
1487                    map(
1488                        FloatObject,
1489                        [
1490                            rect.left,
1491                            rect.bottom,
1492                            rect.width,
1493                            rect.height,
1494                        ],
1495                    ),
1496                    b"re",
1497                ),
1498            )
1499            page2content.operations.insert(1, ([], b"W"))
1500            page2content.operations.insert(2, ([], b"n"))
1501            if page2transformation is not None:
1502                page2content = page2transformation(page2content)
1503            page2content = PageObject._content_stream_rename(
1504                page2content, rename, self.pdf
1505            )
1506            page2content.isolate_graphics_state()
1507            if over:
1508                new_content_array.append(page2content)
1509            else:
1510                new_content_array.insert(0, page2content)
1511
1512        # if expanding the page to fit a new page, calculate the new media box size
1513        if expand:
1514            self._expand_mediabox(page2, ctm)
1515
1516        self.replace_contents(new_content_array)
1517
1518    def _expand_mediabox(
1519        self, page2: "PageObject", ctm: CompressedTransformationMatrix | None
1520    ) -> None:
1521        corners1 = (
1522            self.mediabox.left.as_numeric(),
1523            self.mediabox.bottom.as_numeric(),
1524            self.mediabox.right.as_numeric(),
1525            self.mediabox.top.as_numeric(),
1526        )
1527        corners2 = (
1528            page2.mediabox.left.as_numeric(),
1529            page2.mediabox.bottom.as_numeric(),
1530            page2.mediabox.left.as_numeric(),
1531            page2.mediabox.top.as_numeric(),
1532            page2.mediabox.right.as_numeric(),
1533            page2.mediabox.top.as_numeric(),
1534            page2.mediabox.right.as_numeric(),
1535            page2.mediabox.bottom.as_numeric(),
1536        )
1537        if ctm is not None:
1538            ctm = tuple(float(x) for x in ctm)  # type: ignore[assignment]
1539            new_x = tuple(
1540                ctm[0] * corners2[i] + ctm[2] * corners2[i + 1] + ctm[4]
1541                for i in range(0, 8, 2)
1542            )
1543            new_y = tuple(
1544                ctm[1] * corners2[i] + ctm[3] * corners2[i + 1] + ctm[5]
1545                for i in range(0, 8, 2)
1546            )
1547        else:
1548            new_x = corners2[0:8:2]
1549            new_y = corners2[1:8:2]
1550        lowerleft = (min(new_x), min(new_y))
1551        upperright = (max(new_x), max(new_y))
1552        lowerleft = (min(corners1[0], lowerleft[0]), min(corners1[1], lowerleft[1]))
1553        upperright = (
1554            max(corners1[2], upperright[0]),
1555            max(corners1[3], upperright[1]),
1556        )
1557
1558        self.mediabox.lower_left = lowerleft
1559        self.mediabox.upper_right = upperright
1560
1561    def merge_transformed_page(
1562        self,
1563        page2: "PageObject",
1564        ctm: CompressedTransformationMatrix | Transformation,
1565        over: bool = True,
1566        expand: bool = False,
1567    ) -> None:
1568        """
1569        Similar to :meth:`~pypdf._page.PageObject.merge_page`, but a transformation
1570        matrix is applied to the merged stream.
1571
1572        Args:
1573          page2: The page to be merged into this one.
1574          ctm: a 6-element tuple containing the operands of the
1575                 transformation matrix
1576          over: set the page2 content over page1 if True (default) else under
1577          expand: Whether the page should be expanded to fit the dimensions
1578            of the page to be merged.
1579
1580        """
1581        if isinstance(ctm, Transformation):
1582            ctm = ctm.ctm
1583        self._merge_page(
1584            page2,
1585            lambda page2_content: PageObject._add_transformation_matrix(
1586                page2_content, page2.pdf, ctm
1587            ),
1588            ctm,
1589            over,
1590            expand,
1591        )
1592
1593    def merge_scaled_page(
1594        self, page2: "PageObject", scale: float, over: bool = True, expand: bool = False
1595    ) -> None:
1596        """
1597        Similar to :meth:`~pypdf._page.PageObject.merge_page`, but the stream to be merged
1598        is scaled by applying a transformation matrix.
1599
1600        Args:
1601          page2: The page to be merged into this one.
1602          scale: The scaling factor
1603          over: set the page2 content over page1 if True (default) else under
1604          expand: Whether the page should be expanded to fit the
1605            dimensions of the page to be merged.
1606
1607        """
1608        op = Transformation().scale(scale, scale)
1609        self.merge_transformed_page(page2, op, over, expand)
1610
1611    def merge_rotated_page(
1612        self,
1613        page2: "PageObject",
1614        rotation: float,
1615        over: bool = True,
1616        expand: bool = False,
1617    ) -> None:
1618        """
1619        Similar to :meth:`~pypdf._page.PageObject.merge_page`, but the stream to be merged
1620        is rotated by applying a transformation matrix.
1621
1622        Args:
1623          page2: The page to be merged into this one.
1624          rotation: The angle of the rotation, in degrees
1625          over: set the page2 content over page1 if True (default) else under
1626          expand: Whether the page should be expanded to fit the
1627            dimensions of the page to be merged.
1628
1629        """
1630        op = Transformation().rotate(rotation)
1631        self.merge_transformed_page(page2, op, over, expand)
1632
1633    def merge_translated_page(
1634        self,
1635        page2: "PageObject",
1636        tx: float,
1637        ty: float,
1638        over: bool = True,
1639        expand: bool = False,
1640    ) -> None:
1641        """
1642        Similar to :meth:`~pypdf._page.PageObject.merge_page`, but the stream to be
1643        merged is translated by applying a transformation matrix.
1644
1645        Args:
1646          page2: the page to be merged into this one.
1647          tx: The translation on X axis
1648          ty: The translation on Y axis
1649          over: set the page2 content over page1 if True (default) else under
1650          expand: Whether the page should be expanded to fit the
1651            dimensions of the page to be merged.
1652
1653        """
1654        op = Transformation().translate(tx, ty)
1655        self.merge_transformed_page(page2, op, over, expand)
1656
1657    def add_transformation(
1658        self,
1659        ctm: Transformation | CompressedTransformationMatrix,
1660        expand: bool = False,
1661    ) -> None:
1662        """
1663        Apply a transformation matrix to the page.
1664
1665        Args:
1666            ctm: A 6-element tuple containing the operands of the
1667                transformation matrix. Alternatively, a
1668                :py:class:`Transformation<pypdf.Transformation>`
1669                object can be passed.
1670
1671        See :doc:`/user/cropping-and-transforming`.
1672
1673        """
1674        if isinstance(ctm, Transformation):
1675            ctm = ctm.ctm
1676        content = self.get_contents()
1677        if content is not None:
1678            content = PageObject._add_transformation_matrix(content, self.pdf, ctm)
1679            content.isolate_graphics_state()
1680            self.replace_contents(content)
1681        # if expanding the page to fit a new page, calculate the new media box size
1682        if expand:
1683            corners = [
1684                self.mediabox.left.as_numeric(),
1685                self.mediabox.bottom.as_numeric(),
1686                self.mediabox.left.as_numeric(),
1687                self.mediabox.top.as_numeric(),
1688                self.mediabox.right.as_numeric(),
1689                self.mediabox.top.as_numeric(),
1690                self.mediabox.right.as_numeric(),
1691                self.mediabox.bottom.as_numeric(),
1692            ]
1693
1694            ctm = tuple(float(x) for x in ctm)  # type: ignore[assignment]
1695            new_x = [
1696                ctm[0] * corners[i] + ctm[2] * corners[i + 1] + ctm[4]
1697                for i in range(0, 8, 2)
1698            ]
1699            new_y = [
1700                ctm[1] * corners[i] + ctm[3] * corners[i + 1] + ctm[5]
1701                for i in range(0, 8, 2)
1702            ]
1703
1704            self.mediabox.lower_left = (min(new_x), min(new_y))
1705            self.mediabox.upper_right = (max(new_x), max(new_y))
1706
1707    def scale(self, sx: float, sy: float) -> None:
1708        """
1709        Scale a page by the given factors by applying a transformation matrix
1710        to its content and updating the page size.
1711
1712        This updates the various page boundaries (bleedbox, trimbox, etc.)
1713        and the contents of the page.
1714
1715        Args:
1716            sx: The scaling factor on horizontal axis.
1717            sy: The scaling factor on vertical axis.
1718
1719        """
1720        self.add_transformation((sx, 0, 0, sy, 0, 0))
1721        self.bleedbox = self.bleedbox.scale(sx, sy)
1722        self.trimbox = self.trimbox.scale(sx, sy)
1723        self.artbox = self.artbox.scale(sx, sy)
1724        self.cropbox = self.cropbox.scale(sx, sy)
1725        self.mediabox = self.mediabox.scale(sx, sy)
1726
1727        if PageAttributes.ANNOTS in self:
1728            annotations = self[PageAttributes.ANNOTS]
1729            if isinstance(annotations, ArrayObject):
1730                for annotation in annotations:
1731                    annotation_obj = annotation.get_object()
1732                    if AnnotationDictionaryAttributes.Rect in annotation_obj:
1733                        rectangle = annotation_obj[AnnotationDictionaryAttributes.Rect]
1734                        if isinstance(rectangle, ArrayObject):
1735                            rectangle[0] = FloatObject(float(rectangle[0]) * sx)
1736                            rectangle[1] = FloatObject(float(rectangle[1]) * sy)
1737                            rectangle[2] = FloatObject(float(rectangle[2]) * sx)
1738                            rectangle[3] = FloatObject(float(rectangle[3]) * sy)
1739
1740        if PageAttributes.VP in self:
1741            viewport = self[PageAttributes.VP]
1742            if isinstance(viewport, ArrayObject):
1743                bbox = viewport[0]["/BBox"]
1744            else:
1745                bbox = viewport["/BBox"]  # type: ignore[index]
1746            scaled_bbox = RectangleObject(
1747                (
1748                    float(bbox[0]) * sx,
1749                    float(bbox[1]) * sy,
1750                    float(bbox[2]) * sx,
1751                    float(bbox[3]) * sy,
1752                )
1753            )
1754            if isinstance(viewport, ArrayObject):
1755                self[NameObject(PageAttributes.VP)][NumberObject(0)][  # type: ignore[index]
1756                    NameObject("/BBox")
1757                ] = scaled_bbox
1758            else:
1759                self[NameObject(PageAttributes.VP)][NameObject("/BBox")] = scaled_bbox  # type: ignore[index]
1760
1761    def scale_by(self, factor: float) -> None:
1762        """
1763        Scale a page by the given factor by applying a transformation matrix to
1764        its content and updating the page size.
1765
1766        Args:
1767            factor: The scaling factor (for both X and Y axis).
1768
1769        """
1770        self.scale(factor, factor)
1771
1772    def scale_to(self, width: float, height: float) -> None:
1773        """
1774        Scale a page to the specified dimensions by applying a transformation
1775        matrix to its content and updating the page size.
1776
1777        Args:
1778            width: The new width.
1779            height: The new height.
1780
1781        """
1782        sx = width / float(self.mediabox.width)
1783        sy = height / float(self.mediabox.height)
1784        self.scale(sx, sy)
1785
1786    def compress_content_streams(self, level: int = -1) -> None:
1787        """
1788        Compress the size of this page by joining all content streams and
1789        applying a FlateDecode filter.
1790
1791        However, it is possible that this function will perform no action if
1792        content stream compression becomes "automatic".
1793        """
1794        content = self.get_contents()
1795        if content is not None:
1796            content_obj = content.flate_encode(level)
1797            try:
1798                content.indirect_reference.pdf._objects[  # type: ignore[union-attr]
1799                    content.indirect_reference.idnum - 1  # type: ignore[union-attr]
1800                ] = content_obj
1801            except AttributeError as exception:
1802                if self.indirect_reference is not None and hasattr(
1803                    self.indirect_reference.pdf, "_add_object"
1804                ):
1805                    self.replace_contents(content_obj)
1806                else:
1807                    raise ValueError("Page must be part of a PdfWriter") from exception
1808
1809    @property
1810    def page_number(self) -> int | None:
1811        """
1812        Read-only property which returns the page number within the PDF file.
1813
1814        Returns:
1815            Page number; None if the page is not attached to a PDF.
1816
1817        """
1818        if self.indirect_reference is None:
1819            return None
1820        # Compare the indirect references, not the pages themselves: two pages
1821        # with identical contents compare equal, so `list.index` would return
1822        # the position of the first match for all of them.
1823        for number, page in enumerate(self.indirect_reference.pdf.pages):
1824            if page.indirect_reference == self.indirect_reference:
1825                return number
1826        return None
1827
1828    def _debug_for_extract(self) -> str:  # pragma: no cover
1829        out = ""
1830        for ope, op in ContentStream(
1831            self["/Contents"].get_object(), self.pdf, "bytes"
1832        ).operations:
1833            if op == b"TJ":
1834                s = [x for x in ope[0] if isinstance(x, str)]
1835            else:
1836                s = []
1837            out += op.decode("utf-8") + " " + "".join(s) + ope.__repr__() + "\n"
1838        out += "\n=============================\n"
1839        try:
1840            for fo in self[PageAttributes.RESOURCES]["/Font"]:  # type: ignore[index]
1841                out += fo + "\n"
1842                out += self[PageAttributes.RESOURCES]["/Font"][fo].__repr__() + "\n"  # type: ignore[index]
1843                try:
1844                    enc_repr = self[PageAttributes.RESOURCES]["/Font"][fo][  # type: ignore[index]
1845                        "/Encoding"
1846                    ].__repr__()
1847                    out += enc_repr + "\n"
1848                except MemoryError:  # pragma: no cover  # TODO: BLE001
1849                    raise
1850                except Exception:
1851                    pass
1852                try:
1853                    out += (
1854                        self[PageAttributes.RESOURCES]["/Font"][fo][  # type: ignore[index]
1855                            "/ToUnicode"
1856                        ]
1857                        .get_data()
1858                        .decode()
1859                        + "\n"
1860                    )
1861                except MemoryError:  # pragma: no cover  # TODO: BLE001
1862                    raise
1863                except Exception:
1864                    pass
1865
1866        except KeyError:
1867            out += "No Font\n"
1868        return out
1869
1870    def _extract_text(
1871        self,
1872        obj: DictionaryObject,
1873        pdf: Any,
1874        orientations: tuple[int, ...] = (0, 90, 180, 270),
1875        space_width: float = 200.0,
1876        content_key: str | None = PageAttributes.CONTENTS,
1877        visitor_operand_before: Callable[[Any, Any, Any, Any], None] | None = None,
1878        visitor_operand_after: Callable[[Any, Any, Any, Any], None] | None = None,
1879        visitor_text: Callable[[Any, Any, Any, Any, Any], None] | None = None,
1880        *,
1881        known_ids: set[int] | None = None,
1882        traversal_state: _TraversalState | None = None
1883    ) -> str:
1884        """
1885        See extract_text for most arguments.
1886
1887        Args:
1888            content_key: indicate the default key where to extract data
1889                None = the object; this allows reusing the function on an XObject
1890                default = "/Content"
1891
1892        """
1893        if known_ids is None:
1894            known_ids = set()
1895        if traversal_state is None:
1896            traversal_state = _TraversalState()
1897
1898        resources_dict = _get_page_resources(obj)
1899        if not resources_dict:
1900            # No resources means no text is possible (no font); we consider the
1901            # file as not damaged, no need to check for TJ or Tj
1902            return ""
1903
1904        font_resources: dict[str, DictionaryObject] = {}
1905        fonts: dict[str, Font] = {}
1906        if font_resources_dict := _get_font_resources(resources_dict):
1907            for font_resource in font_resources_dict:
1908                try:
1909                    font_resource_object = cast(DictionaryObject, font_resources_dict[font_resource].get_object())
1910                    font_resources[font_resource] = font_resource_object
1911                    fonts[font_resource] = Font.from_font_resource(font_resource_object)
1912                    # Override space width, if applicable
1913                    if fonts[font_resource].character_widths.get(fonts[font_resource].space_char, 0) == 0:
1914                        fonts[font_resource].space_width = space_width
1915                except (AttributeError, TypeError):
1916                    pass
1917
1918        from ._text_extraction import _get_content_stream_for_text  # noqa: PLC0415
1919
1920        content = _get_content_stream_for_text(
1921            obj,
1922            pdf,
1923            content_key,
1924            has_visitor=any(
1925                visitor is not None for visitor in (visitor_operand_before, visitor_operand_after, visitor_text)
1926            ),
1927        )
1928        if content is None:
1929            return ""
1930        # We check all strings are TextStringObjects. ByteStringObjects
1931        # are strings where the byte->string encoding was unknown, so adding
1932        # them to the text here would be gibberish.
1933
1934        # Initialize the extractor with the necessary parameters
1935        extractor = TextExtraction()
1936        extractor.initialize_extraction(orientations, visitor_text, font_resources, fonts)
1937
1938        for operands, operator in content.operations:
1939            if visitor_operand_before is not None:
1940                visitor_operand_before(operator, operands, extractor.cm_matrix, extractor.tm_matrix)
1941            # Multiple operators are handled here
1942            if operator == b"'":
1943                extractor.process_operation(b"T*", [])
1944                extractor.process_operation(b"Tj", operands)
1945            elif operator == b'"' and len(operands) >= 3:
1946                extractor.process_operation(b"Tw", [operands[0]])
1947                extractor.process_operation(b"Tc", [operands[1]])
1948                extractor.process_operation(b"T*", [])
1949                extractor.process_operation(b"Tj", operands[2:])
1950            elif operator == b"TJ":
1951                # The space width may be smaller than the font width, so the width should be 95%.
1952                _confirm_space_width = extractor._space_width * 0.95
1953                if operands and isinstance(operands[0], ArrayObject):
1954                    for op in operands[0]:
1955                        # A name is a str too, but not text to show
1956                        if isinstance(op, (str, bytes)) and not isinstance(op, NameObject):
1957                            extractor.process_operation(b"Tj", [op])
1958                        if isinstance(op, (int, float, NumberObject, FloatObject)):
1959                            extractor.process_tj_offset(float(op), _confirm_space_width)
1960            elif operator == b"TD" and len(operands) >= 2:
1961                # a non-numeric ty leaves the leading unchanged, like a non-numeric TL
1962                if isinstance(operands[1], (int, float)):
1963                    extractor.process_operation(b"TL", [-operands[1]])
1964                extractor.process_operation(b"Td", operands)
1965            elif operator == b"Do" and operands:
1966                extractor.output += extractor.text
1967                if visitor_text is not None:
1968                    visitor_text(
1969                        extractor.text,
1970                        extractor.memo_cm,
1971                        extractor.memo_tm,
1972                        extractor.font_resource,
1973                        extractor.font_size,
1974                    )
1975                try:
1976                    if extractor.output[-1] != "\n":
1977                        extractor.output += "\n"
1978                        if visitor_text is not None:
1979                            visitor_text(
1980                                "\n",
1981                                extractor.memo_cm,
1982                                extractor.memo_tm,
1983                                extractor.font_resource,
1984                                extractor.font_size,
1985                            )
1986                except IndexError:
1987                    pass
1988                try:
1989                    xform_text = self._extract_text__xform(
1990                        resources_dict=resources_dict,
1991                        operands=operands,
1992                        orientations=orientations,
1993                        space_width=space_width,
1994                        visitor_operand_before=visitor_operand_before,
1995                        visitor_operand_after=visitor_operand_after,
1996                        visitor_text=visitor_text,
1997                        known_ids=known_ids,
1998                        traversal_state=traversal_state
1999                    )
2000                    if xform_text is not None:
2001                        text = xform_text
2002                        extractor.output += text
2003                        # Nothing else to do: each text piece inside the form has
2004                        # already been reported via visitor_text while the form was
2005                        # being extracted recursively (issue #4079).
2006                except MemoryError:  # pragma: no cover  # TODO: BLE001
2007                    raise
2008                except Exception as exception:
2009                    logger_warning(
2010                        "Impossible to decode XFormObject %(operand)s: %(exception)s",
2011                        source=__name__,
2012                        operand=operands[0],
2013                        exception=exception,
2014                    )
2015                finally:
2016                    extractor.text = ""
2017                    extractor.memo_cm = extractor.cm_matrix.copy()
2018                    extractor.memo_tm = extractor.tm_matrix.copy()
2019            else:
2020                extractor.process_operation(operator, operands)
2021            if visitor_operand_after is not None:
2022                visitor_operand_after(operator, operands, extractor.cm_matrix, extractor.tm_matrix)
2023        extractor.output += extractor.text  # just in case
2024        if extractor.text != "" and visitor_text is not None:
2025            visitor_text(
2026                extractor.text,
2027                extractor.memo_cm,
2028                extractor.memo_tm,
2029                extractor.font_resource,
2030                extractor.font_size,
2031            )
2032        return extractor.output
2033
2034    def _extract_text__xform(
2035        self,
2036        *,
2037        resources_dict: DictionaryObject,
2038        operands: Any,
2039        orientations: tuple[int, ...] = (0, 90, 180, 270),
2040        space_width: float = 200.0,
2041        visitor_operand_before: Callable[[Any, Any, Any, Any], None] | None = None,
2042        visitor_operand_after: Callable[[Any, Any, Any, Any], None] | None = None,
2043        visitor_text: Callable[[Any, Any, Any, Any, Any], None] | None = None,
2044        known_ids: set[int],
2045        traversal_state: _TraversalState
2046    ) -> str | None:
2047        xobj = cast(DictionaryObject, resources_dict["/XObject"])
2048        xform = cast(EncodedStreamObject, xobj[operands[0]])
2049        if xform["/Subtype"] == NameObject("/Image"):
2050            return None
2051
2052        xform_id = id(xform)
2053        if xform_id in known_ids:
2054            logger_warning(
2055                "Detected cyclic form XObject reference, skipping %(operand)s.",
2056                source=__name__,
2057                operand=operands[0]
2058            )
2059            return ""
2060
2061        configuration = get_configuration()
2062        if traversal_state.entry_count >= configuration.xform_maximum_invocations_per_extraction:
2063            if not traversal_state.has_logged:
2064                traversal_state.has_logged = True
2065                logger_warning(
2066                    (
2067                        "Exceeded %(limit)d form XObject invocations while extracting text; "
2068                        "further form content is skipped."
2069                    ),
2070                    source=__name__,
2071                    limit=configuration.xform_maximum_invocations_per_extraction
2072                )
2073            return ""
2074
2075        traversal_state.entry_count += 1
2076        known_ids.add(xform_id)
2077        try:
2078            text = self.extract_xform_text(
2079                xform,
2080                orientations,
2081                space_width,
2082                visitor_operand_before,
2083                visitor_operand_after,
2084                visitor_text,
2085                known_ids=known_ids,
2086                traversal_state=traversal_state,
2087            )
2088        finally:
2089            known_ids.discard(xform_id)
2090        return text
2091
2092    def _layout_mode_fonts(self) -> dict[str, Font]:
2093        """
2094        Get fonts formatted for "layout" mode text extraction.
2095
2096        Returns:
2097            Dict[str, Font]: dictionary of Font instances keyed by font name
2098
2099        """
2100        # Font retrieval logic adapted from pypdf.PageObject._extract_text()
2101        obj: Any = self
2102        fonts: dict[str, Font] = {}
2103        visited: set[int] = set()
2104        while True:
2105            obj_id = id(obj)
2106            if obj_id in visited:
2107                logger_warning("Detected cycle in /Parent hierarchy when retrieving fonts.", source=__name__)
2108                break
2109            visited.add(obj_id)
2110
2111            resources_dict: Any = obj.get(PageAttributes.RESOURCES, DictionaryObject()).get_object()
2112            if not isinstance(resources_dict, DictionaryObject):
2113                logger_warning(
2114                    "Page resources are not a dictionary: %(resources)s",
2115                    source=__name__,
2116                    resources=resources_dict,
2117                )
2118                resources_dict = DictionaryObject()
2119            if self.pdf is not None and (font_resources := _get_font_resources(resources_dict)):
2120                for font_name in font_resources:
2121                    font_object = font_resources[font_name].get_object()
2122                    if isinstance(font_object, DictionaryObject):
2123                        fonts[font_name] = Font.from_font_resource(font_object)
2124
2125            parent = obj.get("/Parent", NullObject()).get_object()
2126            if not isinstance(parent, DictionaryObject):
2127                break
2128            obj = parent
2129
2130        return fonts
2131
2132    def _layout_mode_text(
2133        self,
2134        space_vertically: bool = True,
2135        scale_weight: float = 1.25,
2136        strip_rotated: bool = True,
2137        debug_path: Path | None = None,
2138        font_height_weight: float = 1,
2139    ) -> str:
2140        """
2141        Get text preserving fidelity to source PDF text layout.
2142
2143        Args:
2144            space_vertically: include blank lines inferred from y distance + font
2145                height. Defaults to True.
2146            scale_weight: multiplier for string length when calculating weighted
2147                average character width. Defaults to 1.25.
2148            strip_rotated: Removes text that is rotated w.r.t. to the page from
2149                layout mode output. Defaults to True.
2150            debug_path (Path | None): if supplied, must target a directory.
2151                creates the following files with debug information for layout mode
2152                functions if supplied:
2153                  - fonts.json: output of self._layout_mode_fonts
2154                  - tjs.json: individual text render ops with corresponding transform matrices
2155                  - bts.json: text render ops left justified and grouped by BT/ET operators
2156                  - bt_groups.json: BT/ET operations grouped by rendered y-coord (aka lines)
2157                Defaults to None.
2158            font_height_weight: multiplier for font height when calculating
2159                blank lines. Defaults to 1.
2160
2161        Returns:
2162            str: multiline string containing page text in a fixed width format that
2163                closely adheres to the rendered layout in the source pdf.
2164
2165        """
2166        fonts = self._layout_mode_fonts()
2167        if debug_path:  # pragma: no cover
2168            import json  # noqa: PLC0415
2169
2170            debug_path.joinpath("fonts.json").write_text(
2171                json.dumps(fonts, indent=2, default=asdict),
2172                "utf-8"
2173            )
2174
2175        contents = self.get("/Contents")
2176        if contents is not None:
2177            contents = contents.get_object()
2178        if not isinstance(contents, (ArrayObject, StreamObject)):
2179            # No content can be extracted (certainly an empty page).
2180            return ""
2181
2182        ops = iter(ContentStream(contents, self.pdf, "bytes").operations)
2183        bt_groups = _layout_mode.text_show_operations(
2184            ops, fonts, strip_rotated, debug_path
2185        )
2186
2187        if not bt_groups:
2188            return ""
2189
2190        ty_groups = _layout_mode.y_coordinate_groups(bt_groups, debug_path)
2191
2192        char_width = _layout_mode.fixed_char_width(bt_groups, scale_weight)
2193
2194        return _layout_mode.fixed_width_page(ty_groups, char_width, space_vertically, font_height_weight)
2195
2196    def extract_text(
2197        self,
2198        *args: Any,
2199        orientations: int | tuple[int, ...] = (0, 90, 180, 270),
2200        space_width: float = 200.0,
2201        visitor_operand_before: Callable[[Any, Any, Any, Any], None] | None = None,
2202        visitor_operand_after: Callable[[Any, Any, Any, Any], None] | None = None,
2203        visitor_text: Callable[[Any, Any, Any, Any, Any], None] | None = None,
2204        extraction_mode: Literal["plain", "layout"] = "plain",
2205        **kwargs: Any,
2206    ) -> str:
2207        """
2208        Locate all text drawing commands, in the order they are provided in the
2209        content stream, and extract the text.
2210
2211        This works well for some PDF files, but poorly for others, depending on
2212        the generator used. This will be refined in the future.
2213
2214        Do not rely on the order of text coming out of this function, as it
2215        will change if this function is made more sophisticated.
2216
2217        Arabic and Hebrew are extracted in the correct order.
2218        If required a custom RTL range of characters can be defined;
2219        see function set_custom_rtl.
2220
2221        Additionally you can provide visitor methods to get informed on all
2222        operations and all text objects.
2223        For example in some PDF files this can be useful to parse tables.
2224
2225        Args:
2226            orientations: list of orientations extract_text will look for
2227                default = (0, 90, 180, 270)
2228                note: currently only 0 (up),90 (turned left), 180 (upside down),
2229                270 (turned right)
2230                Silently ignored in "layout" mode.
2231            space_width: force default space width
2232                if not extracted from font (default: 200)
2233                Silently ignored in "layout" mode.
2234            visitor_operand_before: function to be called before processing an operation.
2235                It has four arguments: operator, operand-arguments,
2236                current transformation matrix and text matrix.
2237                Ignored with a warning in "layout" mode.
2238            visitor_operand_after: function to be called after processing an operation.
2239                It has four arguments: operator, operand-arguments,
2240                current transformation matrix and text matrix.
2241                Ignored with a warning in "layout" mode.
2242            visitor_text: function to be called when extracting some text at some position.
2243                It has five arguments: text, current transformation matrix,
2244                text matrix, font-dictionary and font-size.
2245                The font-dictionary may be None in case of unknown fonts.
2246                If not None it may e.g. contain key "/BaseFont" with value "/Arial,Bold".
2247                Ignored with a warning in "layout" mode.
2248            extraction_mode (Literal["plain", "layout"]): "plain" for legacy functionality,
2249                "layout" for experimental layout mode functionality.
2250                NOTE: orientations, space_width, and visitor_* parameters are NOT respected
2251                in "layout" mode.
2252
2253        kwargs:
2254            layout_mode_space_vertically (bool): include blank lines inferred from
2255                y distance + font height. Defaults to True.
2256            layout_mode_scale_weight (float): multiplier for string length when calculating
2257                weighted average character width. Defaults to 1.25.
2258            layout_mode_strip_rotated (bool): layout mode does not support rotated text.
2259                Set to False to include rotated text anyway. If rotated text is discovered,
2260                layout will be degraded and a warning will result. Defaults to True.
2261            layout_mode_debug_path (Path | None): if supplied, must target a directory.
2262                creates the following files with debug information for layout mode
2263                functions if supplied:
2264
2265                  - fonts.json: output of self._layout_mode_fonts
2266                  - tjs.json: individual text render ops with corresponding transform matrices
2267                  - bts.json: text render ops left justified and grouped by BT/ET operators
2268                  - bt_groups.json: BT/ET operations grouped by rendered y-coord (aka lines)
2269            layout_mode_font_height_weight (float): multiplier for font height when calculating
2270                blank lines. Defaults to 1.
2271
2272        Returns:
2273            The extracted text
2274
2275        """
2276        if extraction_mode not in ["plain", "layout"]:
2277            raise ValueError(f"Invalid text extraction mode '{extraction_mode}'")
2278        if extraction_mode == "layout":
2279            for visitor in (
2280                "visitor_operand_before",
2281                "visitor_operand_after",
2282                "visitor_text",
2283            ):
2284                if locals()[visitor]:
2285                    logger_warning(
2286                        "Argument %(visitor)s is ignored in layout mode",
2287                        source=__name__,
2288                        visitor=visitor,
2289                    )
2290            return self._layout_mode_text(
2291                space_vertically=kwargs.get("layout_mode_space_vertically", True),
2292                scale_weight=kwargs.get("layout_mode_scale_weight", 1.25),
2293                strip_rotated=kwargs.get("layout_mode_strip_rotated", True),
2294                debug_path=kwargs.get("layout_mode_debug_path"),
2295                font_height_weight=kwargs.get("layout_mode_font_height_weight", 1)
2296            )
2297        if len(args) >= 1:
2298            if isinstance(args[0], str):
2299                if len(args) >= 3:
2300                    if isinstance(args[2], (tuple, int)):
2301                        orientations = args[2]
2302                    else:
2303                        raise TypeError(f"Invalid positional parameter {args[2]}")
2304                if len(args) >= 4:
2305                    if isinstance(args[3], (float, int)):
2306                        space_width = args[3]
2307                    else:
2308                        raise TypeError(f"Invalid positional parameter {args[3]}")
2309            elif isinstance(args[0], (tuple, int)):
2310                orientations = args[0]
2311                if len(args) >= 2:
2312                    if isinstance(args[1], (float, int)):
2313                        space_width = args[1]
2314                    else:
2315                        raise TypeError(f"Invalid positional parameter {args[1]}")
2316            else:
2317                raise TypeError(f"Invalid positional parameter {args[0]}")
2318
2319        if isinstance(orientations, int):
2320            orientations = (orientations,)
2321
2322        return self._extract_text(
2323            self,
2324            self.pdf,
2325            orientations,
2326            space_width,
2327            PageAttributes.CONTENTS,
2328            visitor_operand_before,
2329            visitor_operand_after,
2330            visitor_text,
2331        )
2332
2333    def extract_xform_text(
2334        self,
2335        xform: EncodedStreamObject,
2336        orientations: tuple[int, ...] = (0, 90, 270, 360),
2337        space_width: float = 200.0,
2338        visitor_operand_before: Callable[[Any, Any, Any, Any], None] | None = None,
2339        visitor_operand_after: Callable[[Any, Any, Any, Any], None] | None = None,
2340        visitor_text: Callable[[Any, Any, Any, Any, Any], None] | None = None,
2341        *,
2342        known_ids: set[int] | None = None,
2343        traversal_state: Any | None = None
2344    ) -> str:
2345        """
2346        Extract text from an XObject.
2347
2348        Args:
2349            xform:
2350            orientations:
2351            space_width:  force default space width (if not extracted from font (default 200)
2352            visitor_operand_before:
2353            visitor_operand_after:
2354            visitor_text:
2355            known_ids:
2356            traversal_state:
2357
2358        Returns:
2359            The extracted text
2360
2361        """
2362        # The type hint would have to use an internal type otherwise, which is not desired.
2363        assert traversal_state is None or isinstance(traversal_state, _TraversalState)
2364        return self._extract_text(
2365            xform,
2366            self.pdf,
2367            orientations,
2368            space_width,
2369            None,
2370            visitor_operand_before,
2371            visitor_operand_after,
2372            visitor_text,
2373            known_ids=known_ids,
2374            traversal_state=traversal_state,
2375        )
2376
2377    def _get_fonts(self) -> tuple[set[str], set[str]]:
2378        """
2379        Get the names of embedded fonts and unembedded fonts.
2380
2381        Returns:
2382            A tuple (set of embedded fonts, set of unembedded fonts)
2383
2384        """
2385        obj = self.get_object()
2386        assert isinstance(obj, DictionaryObject)
2387        fonts: set[str] = set()
2388        embedded: set[str] = set()
2389        fonts, embedded = _get_fonts_walk(obj, fonts, embedded)
2390        unembedded = fonts - embedded
2391        return embedded, unembedded
2392
2393    mediabox = _create_rectangle_accessor(PageAttributes.MEDIABOX, ())
2394    """A :class:`RectangleObject<pypdf.generic.RectangleObject>`, expressed in
2395    default user space units, defining the boundaries of the physical medium on
2396    which the page is intended to be displayed or printed."""
2397
2398    cropbox = _create_rectangle_accessor("/CropBox", (PageAttributes.MEDIABOX,))
2399    """
2400    A :class:`RectangleObject<pypdf.generic.RectangleObject>`, expressed in
2401    default user space units, defining the visible region of default user
2402    space.
2403
2404    When the page is displayed or printed, its contents are to be clipped
2405    (cropped) to this rectangle and then imposed on the output medium in some
2406    implementation-defined manner. Default value: same as
2407    :attr:`mediabox<mediabox>`.
2408    """
2409
2410    bleedbox = _create_rectangle_accessor("/BleedBox", ("/CropBox", PageAttributes.MEDIABOX))
2411    """A :class:`RectangleObject<pypdf.generic.RectangleObject>`, expressed in
2412    default user space units, defining the region to which the contents of the
2413    page should be clipped when output in a production environment."""
2414
2415    trimbox = _create_rectangle_accessor("/TrimBox", ("/CropBox", PageAttributes.MEDIABOX))
2416    """A :class:`RectangleObject<pypdf.generic.RectangleObject>`, expressed in
2417    default user space units, defining the intended dimensions of the finished
2418    page after trimming."""
2419
2420    artbox = _create_rectangle_accessor("/ArtBox", ("/CropBox", PageAttributes.MEDIABOX))
2421    """A :class:`RectangleObject<pypdf.generic.RectangleObject>`, expressed in
2422    default user space units, defining the extent of the page's meaningful
2423    content as intended by the page's creator."""
2424
2425    @property
2426    def annotations(self) -> ArrayObject | None:
2427        if "/Annots" not in self:
2428            return None
2429        annotations = self["/Annots"].get_object()
2430        if not isinstance(annotations, ArrayObject):
2431            logger_warning(
2432                "Annotations are not an array: %(annotations)s",
2433                source=__name__,
2434                annotations=annotations,
2435            )
2436            return None
2437        return annotations
2438
2439    @annotations.setter
2440    def annotations(self, value: ArrayObject | None) -> None:
2441        """
2442        Set the annotations array of the page.
2443
2444        Typically you do not want to set this value, but append to it.
2445        If you append to it, remember to add the object first to the writer
2446        and only add the indirect object.
2447        """
2448        if value is None:
2449            if "/Annots" not in self:
2450                return
2451            del self[NameObject("/Annots")]
2452        else:
2453            self[NameObject("/Annots")] = value
2454
2455    def add_action(self, trigger: PageTrigger, action: Action) -> None:
2456        """
2457        Add an action which will launch on the given trigger event of this page.
2458
2459        Args:
2460            trigger: The action trigger to use.
2461            action: The action to be done.
2462
2463        Example:
2464            >>> from pypdf import PdfWriter
2465            >>> from pypdf.actions import JavaScript, PageTrigger
2466            >>> writer = PdfWriter()
2467            >>> page = writer.add_blank_page(595, 842)
2468            >>> # Display the page number when the page is opened
2469            >>> page.add_action(PageTrigger("open"), JavaScript("app.alert('This is page ' + this.pageNum);"))
2470            >>> # Display the page number when the page is closed
2471            >>> page.add_action(PageTrigger("close"), JavaScript("app.alert('This is page ' + this.pageNum);"))
2472        """
2473        return Action._create_new(self, trigger, action)
2474
2475    def delete_action(self, trigger: PageTrigger) -> None:
2476        """
2477        Delete all actions associated with an open or close trigger event of this page.
2478
2479        Args:
2480            trigger: An open or close trigger.
2481
2482        Example:
2483            >>> from pypdf import PdfWriter
2484            >>> from pypdf.actions import JavaScript, PageTrigger
2485            >>> writer = PdfWriter()
2486            >>> page = writer.add_blank_page(595, 842)
2487            >>> page.add_action(PageTrigger("open"), JavaScript("app.alert('This is page ' + this.pageNum);"))
2488            >>> page.add_action(PageTrigger("close"), JavaScript("app.alert('This is page ' + this.pageNum);"))
2489            >>> # Delete all actions triggered by a page open
2490            >>> page.delete_action(PageTrigger("open"))
2491            >>> # Delete all actions triggered by a page close
2492            >>> page.delete_action(PageTrigger("close"))
2493        """
2494        return Action._delete(self, trigger)
2495
2496
2497class _VirtualList(Sequence[PageObject]):
2498    def __init__(
2499        self,
2500        length_function: Callable[[], int],
2501        get_function: Callable[[int], PageObject],
2502    ) -> None:
2503        self.length_function = length_function
2504        self.get_function = get_function
2505        self.current = -1
2506
2507    def __len__(self) -> int:
2508        return self.length_function()
2509
2510    @overload
2511    def __getitem__(self, index: int) -> PageObject:
2512        ...
2513
2514    @overload
2515    def __getitem__(self, index: slice) -> Sequence[PageObject]:
2516        ...
2517
2518    def __getitem__(
2519        self, index: int | slice
2520    ) -> PageObject | Sequence[PageObject]:
2521        if isinstance(index, slice):
2522            indices = range(*index.indices(len(self)))
2523            cls = type(self)
2524            return cls(indices.__len__, lambda idx: self[indices[idx]])
2525        if not isinstance(index, int):
2526            raise TypeError("Sequence indices must be integers")
2527        len_self = len(self)
2528        if index < 0:
2529            # support negative indexes
2530            index += len_self
2531        if not (0 <= index < len_self):
2532            raise IndexError("Sequence index out of range")
2533        return self.get_function(index)
2534
2535    def __delitem__(self, index: int | slice) -> None:
2536        if isinstance(index, slice):
2537            r = list(range(*index.indices(len(self))))
2538            # pages have to be deleted from last to first
2539            r.sort()
2540            r.reverse()
2541            for p in r:
2542                del self[p]  # recursive call
2543            return
2544        if not isinstance(index, int):
2545            raise TypeError("Index must be integers")
2546        len_self = len(self)
2547        if index < 0:
2548            # support negative indexes
2549            index += len_self
2550        if not (0 <= index < len_self):
2551            raise IndexError("Index out of range")
2552        ind = self[index].indirect_reference
2553        assert ind is not None
2554        parent: PdfObject | None = cast(DictionaryObject, ind.get_object()).get(
2555            "/Parent", None
2556        )
2557        first = True
2558        while parent is not None:
2559            parent = cast(DictionaryObject, parent.get_object())
2560            try:
2561                i = cast(ArrayObject, parent["/Kids"]).index(ind)
2562                del cast(ArrayObject, parent["/Kids"])[i]
2563                first = False
2564                try:
2565                    assert ind is not None
2566                    del ind.pdf.flattened_pages[index]  # case of page in a Reader
2567                except MemoryError:  # pragma: no cover  # TODO: BLE001
2568                    raise
2569                except Exception:  # pragma: no cover
2570                    pass
2571                if "/Count" in parent:
2572                    parent[NameObject("/Count")] = NumberObject(
2573                        cast(int, parent["/Count"]) - 1
2574                    )
2575                if len(cast(ArrayObject, parent["/Kids"])) == 0:
2576                    # No more objects in this part of this subtree
2577                    ind = parent.indirect_reference
2578                parent = parent.get("/Parent", None)
2579            except ValueError as exception:  # from index
2580                if first:
2581                    raise PdfReadError(f"Page not found in page tree: {ind}") from exception
2582                break
2583
2584    def __iter__(self) -> Iterator[PageObject]:
2585        for i in range(len(self)):
2586            yield self[i]
2587
2588    def __str__(self) -> str:
2589        p = [f"PageObject({i})" for i in range(self.length_function())]
2590        return f"[{', '.join(p)}]"
2591
2592
2593def _get_fonts_walk(
2594    obj: DictionaryObject,
2595    fnt: set[str],
2596    emb: set[str],
2597) -> tuple[set[str], set[str]]:
2598    """
2599    Get the set of all fonts and all embedded fonts.
2600
2601    Args:
2602        obj: Page resources dictionary
2603        fnt: font
2604        emb: embedded fonts
2605
2606    Returns:
2607        A tuple (fnt, emb)
2608
2609    If there is a key called 'BaseFont', that is a font that is used in the document.
2610    If there is a key called 'FontName' and another key in the same dictionary object
2611    that is called 'FontFilex' (where x is null, 2, or 3), then that fontname is
2612    embedded.
2613
2614    We create and add to two sets, fnt = fonts used and emb = fonts embedded.
2615
2616    """
2617    fontkeys = ("/FontFile", "/FontFile2", "/FontFile3")
2618
2619    def process_font(f: PdfObject) -> None:
2620        nonlocal fnt, emb
2621        f = cast(DictionaryObject, f.get_object())  # to be sure
2622        if "/BaseFont" in f:
2623            fnt.add(cast(str, f["/BaseFont"]))
2624
2625        if (
2626            ("/CharProcs" in f)
2627            or (
2628                "/FontDescriptor" in f
2629                and any(
2630                    x in cast(DictionaryObject, f["/FontDescriptor"]) for x in fontkeys
2631                )
2632            )
2633            or (
2634                "/DescendantFonts" in f
2635                and "/FontDescriptor"
2636                in cast(
2637                    DictionaryObject,
2638                    cast(ArrayObject, f["/DescendantFonts"])[0].get_object(),
2639                )
2640                and any(
2641                    x
2642                    in cast(
2643                        DictionaryObject,
2644                        cast(
2645                            DictionaryObject,
2646                            cast(ArrayObject, f["/DescendantFonts"])[0].get_object(),
2647                        )["/FontDescriptor"],
2648                    )
2649                    for x in fontkeys
2650                )
2651            )
2652        ):
2653            # the list comprehension ensures there is FontFile
2654            try:
2655                emb.add(cast(str, f["/BaseFont"]))
2656            except KeyError:
2657                emb.add("(" + cast(str, f["/Subtype"]) + ")")
2658
2659    if "/DR" in obj and "/Font" in cast(DictionaryObject, obj["/DR"]):
2660        for f in cast(
2661            DictionaryObject, cast(DictionaryObject, obj["/DR"])["/Font"]
2662        ).values():
2663            process_font(f)
2664    if "/Resources" in obj:
2665        resources = cast(DictionaryObject, obj["/Resources"]).get_object()
2666        if not isinstance(resources, DictionaryObject):
2667            if not is_null_or_none(resources):
2668                logger_warning(
2669                    "Resources are not a dictionary: %(resources)s",
2670                    source=__name__,
2671                    resources=resources,
2672                )
2673            resources = DictionaryObject()
2674        if "/Font" in resources:
2675            for f in cast(DictionaryObject, resources["/Font"]).values():
2676                process_font(f)
2677        if "/XObject" in resources:
2678            for x in cast(DictionaryObject, resources["/XObject"]).values():
2679                _get_fonts_walk(cast(DictionaryObject, x.get_object()), fnt, emb)
2680    if "/Annots" in obj:
2681        for a in cast(ArrayObject, obj["/Annots"]):
2682            _get_fonts_walk(cast(DictionaryObject, a.get_object()), fnt, emb)
2683    if "/AP" in obj:
2684        normal = cast(DictionaryObject, obj["/AP"])["/N"].get_object()
2685        if isinstance(normal, StreamObject):
2686            # /Type is optional in an appearance stream
2687            _get_fonts_walk(normal, fnt, emb)
2688        else:
2689            # One appearance stream per state, e.g. /Off and /Yes of a check box
2690            for a in cast(DictionaryObject, normal).values():
2691                _get_fonts_walk(cast(DictionaryObject, a.get_object()), fnt, emb)
2692    return fnt, emb  # return the sets for each page