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