The PageObject Class

class PyPDF2._page.PageObject(pdf: Optional[PdfReaderProtocol] = None, indirect_reference: Optional[IndirectObject] = None, indirect_ref: Optional[IndirectObject] = None)[source]

Bases: DictionaryObject

PageObject represents a single page within a PDF file.

Typically this object will be created by accessing the get_page() method of the PdfReader class, but it is also possible to create an empty page with the create_blank_page() static method.

Parameters

pdf – PDF file the page belongs to.
indirect_reference – Stores the original indirect reference to this object in its source PDF

addTransformation(ctm: Tuple[float, float, float, float, float, float]) → None[source]: Deprecated since version 1.28.0: Use add_transformation() instead.

add_transformation(ctm: Union[Transformation, Tuple[float, float, float, float, float, float]], expand: bool = False) → None[source]

Apply a transformation matrix to the page.

Parameters: ctm – A 6-element tuple containing the operands of the transformation matrix. Alternatively, a Transformation object can be passed.

See Cropping and Transforming PDFs.

property annotations: Optional[ArrayObject]

property artBox: RectangleObject: Deprecated since version 1.28.0.

Use artbox instead.

property artbox: A RectangleObject, expressed in default user space units, defining the extent of the page’s meaningful content as intended by the page’s creator.

property bleedBox: RectangleObject: Deprecated since version 1.28.0.

Use bleedbox instead.

property bleedbox: A RectangleObject, expressed in default user space units, defining the region to which the contents of the page should be clipped when output in a production environment.

compressContentStreams() → None[source]: Deprecated since version 1.28.0: Use compress_content_streams() instead.

compress_content_streams() → None[source]

Compress the size of this page by joining all content streams and applying a FlateDecode filter.

However, it is possible that this function will perform no action if content stream compression becomes “automatic”.

static createBlankPage(pdf: Optional[Any] = None, width: Optional[Union[float, Decimal]] = None, height: Optional[Union[float, Decimal]] = None) → PageObject[source]: Deprecated since version 1.28.0: Use create_blank_page() instead.

static create_blank_page(pdf: Optional[Any] = None, width: Optional[Union[float, Decimal]] = None, height: Optional[Union[float, Decimal]] = None) → PageObject[source]

Return a new blank page.

If width or height is None, try to get the page size from the last page of pdf.

Parameters

pdf – PDF file the page belongs to
width – The width of the new page expressed in default user space units.
height – The height of the new page expressed in default user space units.

Returns

The new blank page

Raises

PageSizeNotDefinedError – if pdf is None or contains no page

property cropBox: RectangleObject: Deprecated since version 1.28.0.

Use cropbox instead.

property cropbox: A RectangleObject, expressed in default user space units, defining the visible region of default user space. When the page is displayed or printed, its contents are to be clipped (cropped) to this rectangle and then imposed on the output medium in some implementation-defined manner. Default value: same as mediabox.

extractText(Tj_sep: str = '', TJ_sep: str = '') → str[source]: Deprecated since version 1.28.0: Use extract_text() instead.

extract_text(*args: Any, Tj_sep: Optional[str] = None, TJ_sep: Optional[str] = None, orientations: Union[int, Tuple[int, ...]] = (0, 90, 180, 270), space_width: float = 200.0, visitor_operand_before: Optional[Callable[[Any, Any, Any, Any], None]] = None, visitor_operand_after: Optional[Callable[[Any, Any, Any, Any], None]] = None, visitor_text: Optional[Callable[[Any, Any, Any, Any, Any], None]] = None) → str[source]

Locate all text drawing commands, in the order they are provided in the content stream, and extract the text.

This works well for some PDF files, but poorly for others, depending on the generator used. This will be refined in the future.

Do not rely on the order of text coming out of this function, as it will change if this function is made more sophisticated.

Arabic, Hebrew,… are extracted in the good order. If required an custom RTL range of characters can be defined; see function set_custom_rtl

Additionally you can provide visitor-methods to get informed on all operands and all text-objects. For example in some PDF files this can be useful to parse tables.

Parameters

Tj_sep – Deprecated. Kept for compatibility until PyPDF2 4.0.0
TJ_sep – Deprecated. Kept for compatibility until PyPDF2 4.0.0
orientations – list of orientations text_extraction will look for default = (0, 90, 180, 270) note: currently only 0(Up),90(turned Left), 180(upside Down), 270 (turned Right)
space_width – force default space width if not extracted from font (default: 200)
visitor_operand_before – function to be called before processing an operand. It has four arguments: operand, operand-arguments, current transformation matrix and text matrix.
visitor_operand_after – function to be called after processing an operand. It has four arguments: operand, operand-arguments, current transformation matrix and text matrix.
visitor_text – function to be called when extracting some text at some position. It has five arguments: text, current transformation matrix, text matrix, font-dictionary and font-size. The font-dictionary may be None in case of unknown fonts. If not None it may e.g. contain key “/BaseFont” with value “/Arial,Bold”.

Returns

The extracted text

extract_xform_text(xform: EncodedStreamObject, orientations: Tuple[int, ...] = (0, 90, 270, 360), space_width: float = 200.0, visitor_operand_before: Optional[Callable[[Any, Any, Any, Any], None]] = None, visitor_operand_after: Optional[Callable[[Any, Any, Any, Any], None]] = None, visitor_text: Optional[Callable[[Any, Any, Any, Any, Any], None]] = None) → str[source]

Extract text from an XObject.

Parameters: space_width – force default space width (if not extracted from font (default 200)
Returns: The extracted text

getContents() → Optional[ContentStream][source]: Deprecated since version 1.28.0: Use get_contents() instead.

get_contents() → Optional[ContentStream][source]

Access the page contents.

Returns: the /Contents object, or None if it doesn’t exist. /Contents is optional, as described in PDF Reference 7.7.3.3

hash_value_data() → bytes[source]

property images: List[File]

Get a list of all images of the page.

This requires pillow. You can install it via ‘pip install PyPDF2[image]’.

For the moment, this does NOT include inline images. They will be added in future.

property indirect_ref: Optional[IndirectObject]

property mediaBox: RectangleObject: Deprecated since version 1.28.0.

Use mediabox instead.

property mediabox: A RectangleObject, expressed in default user space units, defining the boundaries of the physical medium on which the page is intended to be displayed or printed.

mergePage(page2: PageObject) → None[source]: Deprecated since version 1.28.0: Use merge_page() instead.

mergeRotatedPage(page2: PageObject, rotation: float, expand: bool = False) → None[source]

mergeRotatedPage is similar to merge_page, but the stream to be merged is rotated by applying a transformation matrix.

Parameters

page2 (PageObject) – the page to be merged into this one. Should be an instance of PageObject.
rotation (float) – The angle of the rotation, in degrees
expand (bool) – Whether the page should be expanded to fit the dimensions of the page to be merged.

Deprecated since version 1.28.0: Use add_transformation() and merge_page() instead.

mergeRotatedScaledPage(page2: PageObject, rotation: float, scale: float, expand: bool = False) → None[source]

mergeRotatedScaledPage is similar to merge_page, but the stream to be merged is rotated and scaled by applying a transformation matrix.

Parameters

page2 (PageObject) – the page to be merged into this one. Should be an instance of PageObject.
rotation (float) – The angle of the rotation, in degrees
scale (float) – The scaling factor
expand (bool) – Whether the page should be expanded to fit the dimensions of the page to be merged.

Deprecated since version 1.28.0: Use add_transformation() and merge_page() instead.

mergeRotatedScaledTranslatedPage(page2: PageObject, rotation: float, scale: float, tx: float, ty: float, expand: bool = False) → None[source]

mergeRotatedScaledTranslatedPage is similar to merge_page, but the stream to be merged is translated, rotated and scaled by applying a transformation matrix.

Parameters

page2 (PageObject) – the page to be merged into this one. Should be an instance of PageObject.
tx (float) – The translation on X axis
ty (float) – The translation on Y axis
rotation (float) – The angle of the rotation, in degrees
scale (float) – The scaling factor
expand (bool) – Whether the page should be expanded to fit the dimensions of the page to be merged.

Deprecated since version 1.28.0: Use add_transformation() and merge_page() instead.

mergeRotatedTranslatedPage(page2: PageObject, rotation: float, tx: float, ty: float, expand: bool = False) → None[source]

mergeRotatedTranslatedPage is similar to merge_page, but the stream to be merged is rotated and translated by applying a transformation matrix.

Parameters

page2 (PageObject) – the page to be merged into this one. Should be an instance of PageObject.
tx (float) – The translation on X axis
ty (float) – The translation on Y axis
rotation (float) – The angle of the rotation, in degrees
expand (bool) – Whether the page should be expanded to fit the dimensions of the page to be merged.

Deprecated since version 1.28.0: Use add_transformation() and merge_page() instead.

mergeScaledPage(page2: PageObject, scale: float, expand: bool = False) → None[source]

mergeScaledPage is similar to merge_page, but the stream to be merged is scaled by applying a transformation matrix.

Parameters

page2 (PageObject) – The page to be merged into this one. Should be an instance of PageObject.
scale (float) – The scaling factor
expand (bool) – Whether the page should be expanded to fit the dimensions of the page to be merged.

Deprecated since version 1.28.0: Use add_transformation() and merge_page() instead.

mergeScaledTranslatedPage(page2: PageObject, scale: float, tx: float, ty: float, expand: bool = False) → None[source]

mergeScaledTranslatedPage is similar to merge_page, but the stream to be merged is translated and scaled by applying a transformation matrix.

Parameters

page2 (PageObject) – the page to be merged into this one. Should be an instance of PageObject.
scale (float) – The scaling factor
tx (float) – The translation on X axis
ty (float) – The translation on Y axis
expand (bool) – Whether the page should be expanded to fit the dimensions of the page to be merged.

Deprecated since version 1.28.0: Use add_transformation() and merge_page() instead.

mergeTransformedPage(page2: PageObject, ctm: Union[Tuple[float, float, float, float, float, float], Transformation], expand: bool = False) → None[source]

mergeTransformedPage is similar to merge_page, but a transformation matrix is applied to the merged stream.

Parameters

page2 (PageObject) – The page to be merged into this one. Should be an instance of PageObject.
ctm (tuple) – a 6-element tuple containing the operands of the transformation matrix
expand (bool) – Whether the page should be expanded to fit the dimensions of the page to be merged.

Deprecated since version 1.28.0: Use add_transformation() and merge_page() instead.

mergeTranslatedPage(page2: PageObject, tx: float, ty: float, expand: bool = False) → None[source]

mergeTranslatedPage is similar to merge_page, but the stream to be merged is translated by applying a transformation matrix.

Parameters

page2 (PageObject) – the page to be merged into this one. Should be an instance of PageObject.
tx (float) – The translation on X axis
ty (float) – The translation on Y axis
expand (bool) – Whether the page should be expanded to fit the dimensions of the page to be merged.

Deprecated since version 1.28.0: Use add_transformation() and merge_page() instead.

merge_page(page2: PageObject, expand: bool = False) → None[source]

Merge the content streams of two pages into one.

Resource references (i.e. fonts) are maintained from both pages. The mediabox/cropbox/etc of this page are not altered. The parameter page’s content stream will be added to the end of this page’s content stream, meaning that it will be drawn after, or “on top” of this page.

Parameters

page2 – The page to be merged into this one. Should be an instance of PageObject.
expand – If true, the current page dimensions will be expanded to accommodate the dimensions of the page to be merged.

original_page: PageObject

rotate(angle: int) → PageObject[source]

Rotate a page clockwise by increments of 90 degrees.

Parameters: angle – Angle to rotate the page. Must be an increment of 90 deg.

rotateClockwise(angle: int) → PageObject[source]: Deprecated since version 1.28.0: Use rotate_clockwise() instead.

rotateCounterClockwise(angle: int) → PageObject[source]: Deprecated since version 1.28.0: Use rotate_clockwise() with a negative argument instead.

rotate_clockwise(angle: int) → PageObject[source]

property rotation: int

The VISUAL rotation of the page.

This number has to be a multiple of 90 degrees: 0,90,180,270 This property does not affect “/Contents”

scale(sx: float, sy: float) → None[source]

Scale a page by the given factors by applying a transformation matrix to its content and updating the page size.

This updates the mediabox, the cropbox, and the contents of the page.

Parameters

sx – The scaling factor on horizontal axis.
sy – The scaling factor on vertical axis.

scaleBy(factor: float) → None[source]: Deprecated since version 1.28.0: Use scale_by() instead.

scaleTo(width: float, height: float) → None[source]: Deprecated since version 1.28.0: Use scale_to() instead.

scale_by(factor: float) → None[source]

Scale a page by the given factor by applying a transformation matrix to its content and updating the page size.

Parameters: factor – The scaling factor (for both X and Y axis).

scale_to(width: float, height: float) → None[source]

Scale a page to the specified dimensions by applying a transformation matrix to its content and updating the page size.

Parameters

width – The new width.
height – The new height.

transfer_rotation_to_content() → None[source]

Apply the rotation of the page to the content and the media/crop/… boxes.

It’s recommended to apply this function before page merging.

property trimBox: RectangleObject: Deprecated since version 1.28.0.

Use trimbox instead.

property trimbox: A RectangleObject, expressed in default user space units, defining the intended dimensions of the finished page after trimming.

property user_unit: float

A read-only positive number giving the size of user space units.

It is in multiples of 1/72 inch. Hence a value of 1 means a user space unit is 1/72 inch, and a value of 3 means that a user space unit is 3/72 inch.