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