Support models

Support models are abstracts over “raw” objects within a Pdf. For example, a page in a PDF is a Dictionary with set to /Type of /Page. The Dictionary in that case is the “raw” object. Upon establishing what type of object it is, we can wrap it with a support model that adds features to ensure consistency with the PDF specification.

pikepdf does not currently apply support models to “raw” objects automatically, but might do so in a future release (this would break backward compatibility).

class pikepdf.Page

Support model wrapper around a raw page dictionary object.

To initialize a Page support model:

from pikepdf import Pdf, Page

Pdf = open(...)
page_support_model = Page(pdf.pages[0])

add_content_token_filter(self: pikepdf.Page, tf: pikepdf.TokenFilter) → None 

Attach a pikepdf.TokenFilter to a page’s content stream.

This function applies token filters lazily, if/when the page’s content stream is read for any reason, such as when the PDF is saved. If never access, the token filter is not applied.

Multiple token filters may be added to a page/content stream.

Token filters may not be removed after being attached to a Pdf. Close and reopen the Pdf to remove token filters.

If the page’s contents is an array of streams, it is coalesced.

add_overlay(other, rect=None)

Overlay another object on this page.

Overlays will be drawn after all previous content, potentially drawing on top of existing content.

Parameters

other (Union[pikepdf.objects.Object, pikepdf._qpdf.Page]) – A Page or Form XObject to render as an overlay on top of this page.
rect (Optional[pikepdf._qpdf.Rectangle]) – The PDF rectangle (in PDF units) in which to draw the overlay. If omitted, this page’s trimbox, cropbox or mediabox will be used.

New in version 2.14.

add_resource(res, res_type, name=None, *, prefix='', replace_existing=True)

Adds a new resource to the page’s Resources dictionary.

If the Resources dictionaries do not exist, they will be created.

Parameters

self – The object to add to the resources dictionary.
res (pikepdf.objects.Object) – The dictionary object to insert into the resources dictionary.
res_type (pikepdf.objects.Name) – Should be one of the following Resource dictionary types: ExtGState, ColorSpace, Pattern, Shading, XObject, Font, Properties.
name (Optional[pikepdf.objects.Name]) – The name of the object. If omitted, a random name will be generated with enough randomness to be globally unique.
prefix (str) – A prefix for the name of the object. Allows conveniently namespacing when using random names, e.g. prefix=”Im” for images. Mutually exclusive with name parameter.
replace_existing (bool) – If the name already exists in one of the resource dictionaries, remove it.

Returns

The name of the object.

Return type

pikepdf.objects.Name

Example

>>> resource_name = Page(pdf.pages[0]).add_resource(formxobj, Name.XObject)

New in version 2.3.

Changed in version 2.14: If res does not belong to the same Pdf that owns this page, a copy of res is automatically created and added instead. In previous versions, it was necessary to change for this case manually.

add_underlay(other, rect=None)

Underlay another object beneath this page.

Underlays will be drawn before all other content, so they may be overdrawn partially or completely.

Parameters

other (Union[pikepdf.objects.Object, pikepdf._qpdf.Page]) – A Page or Form XObject to render as an underlay underneath this page.
rect (Optional[pikepdf._qpdf.Rectangle]) – The PDF rectangle (in PDF units) in which to draw the underlay. If omitted, this page’s MediaBox will be used.

New in version 2.14.

as_form_xobject(self: pikepdf.Page, handle_transformations: bool = True) → pikepdf.Object 

Return a form XObject that draws this page.

This is useful for n-up operations, underlay, overlay, thumbnail generation, or any other case in which it is useful to replicate the contents of a page in some other context. The dictionaries are shallow copies of the original page dictionary, and the contents are coalesced from the page’s contents. The resulting object handle is not referenced anywhere.

Parameters: handle_transformations (bool) – If True, the resulting form XObject’s /Matrix will be set to replicate rotation (/Rotate) and scaling (/UserUnit) in the page’s dictionary. In this way, the page’s transformations will be preserved when placing this object on another page.

calc_form_xobject_placement(self: pikepdf.Page, formx: pikepdf.Object, name: pikepdf.Object, rect: pikepdf.Rectangle, *, invert_transformations: bool = True, allow_shrink: bool = True, allow_expand: bool = False) → bytes 

Generate content stream segment to place a Form XObject on this page.

The content stream segment must be then be added to the page’s content stream.

The default keyword parameters will preserve the aspect ratio.

Parameters

formx – The Form XObject to place.
name – The name of the Form XObject in this page’s /Resources dictionary.
rect – Rectangle describing the desired placement of the Form XObject.
invert_transformations – Apply /Rotate and /UserUnit scaling when determining FormX Object placement.
allow_shrink – Allow the Form XObject to take less than the full dimensions of rect.
allow_expand – Expand the Form XObject to occupy all of rect.

New in version 2.14.

contents_add(*args, **kwargs)

Overloaded function.

contents_add(self: pikepdf.Page, contents: pikepdf.Object, prepend: bool = False) -> None

Append or prepend to an existing page’s content stream using an existing stream object.

New in version 2.14.
contents_add(self: pikepdf.Page, contents: bytes, *, prepend: bool = False) -> None

Append or prepend to an existing page’s content stream from bytes.

New in version 2.14.

contents_coalesce(self: pikepdf.Page) → None 

Coalesce a page’s content streams.

A page’s content may be a stream or an array of streams. If this page’s content is an array, concatenate the streams into a single stream. This can be useful when working with files that split content streams in arbitrary spots, such as in the middle of a token, as that can confuse some software.

property cropbox

This page’s effective /CropBox, in PDF units.

If the /CropBox is not defined, the /MediaBox is returned.

externalize_inline_images(self: pikepdf.Page, min_size: int = 0) → None 

Convert inlines image to normal (external) images.

Parameters: min_size (int) – minimum size in bytes

get_filtered_contents(self: pikepdf.Page, tf: TokenFilter) → bytes 

Apply a pikepdf.TokenFilter to a content stream, without modifying it.

This may be used when the results of a token filter do not need to be applied, such as when filtering is being used to retrieve information rather than edit the content stream.

Note that it is possible to create a subclassed TokenFilter that saves information of interest to its object attributes; it is not necessary to return data in the content stream.

To modify the content stream, use pikepdf.Page.add_content_token_filter().

Returns: the modified content stream
Return type: bytes

property index

Returns the zero-based index of this page in the pages list.

That is, returns n such that pdf.pages[n] == this_page. A ValueError exception is thrown if the page is not attached to a Pdf.

Requires O(n) search.

New in version 2.2.

property label

Returns the page label for this page, accounting for section numbers.

For example, if the PDF defines a preface with lower case Roman numerals (i, ii, iii…), followed by standard numbers, followed by an appendix (A-1, A-2, …), this function returns the appropriate label as a string.

It is possible for a PDF to define page labels such that multiple pages have the same labels. Labels are not guaranteed to be unique.

Note that this requires a O(n) search over all pages, to look up the page’s index.

New in version 2.2.

Changed in version 2.9: Returns the ordinary page number if no special rules for page numbers are defined.

property mediabox: This page’s /MediaBox, in PDF units.

property obj: Get the underlying pikepdf.Object.

parse_contents(self: pikepdf.Page, arg0: pikepdf.StreamParser) → None 

Parse a page’s content streams using a pikepdf.StreamParser.

The content stream may be interpreted by the StreamParser but is not altered.

If the page’s contents is an array of streams, it is coalesced.

remove_unreferenced_resources(self: pikepdf.Page) → None 

Removes from the resources dictionary any object not referenced in the content stream.

A page’s resources dictionary maps names to objects elsewhere in the file. This method walks through a page’s contents and keeps tracks of which resources are referenced somewhere in the contents. Then it removes from the resources dictionary any object that is not referenced in the contents. This method is used by page splitting code to avoid copying unused objects in files that used shared resource dictionaries across multiple pages.

property resources: Return this pages resources dictionary.

rotate(self: pikepdf.Page, angle: int, relative: bool) → None 

Rotate a page.

If relative is False, set the rotation of the page to angle. Otherwise, add angle to the rotation of the page. angle must be a multiple of 90. Adding 90 to the rotation rotates clockwise by 90 degrees.

property trimbox

This page’s effective /TrimBox, in PDF units.

If the /TrimBox is not defined, the /CropBox is returned (and if /CropBox is not defined, /MediaBox is returned).

class pikepdf.PdfMatrix(*args)

Support class for PDF content stream matrices

PDF content stream matrices are 3x3 matrices summarized by a shorthand (a, b, c, d, e, f) which correspond to the first two column vectors. The final column vector is always (0, 0, 1) since this is using homogenous coordinates.

PDF uses row vectors. That is, vr @ A' gives the effect of transforming a row vector vr=(x, y, 1) by the matrix A'. Most textbook treatments use A @ vc where the column vector vc=(x, y, 1)'.

(@ is the Python matrix multiplication operator.)

Addition and other operations are not implemented because they’re not that meaningful in a PDF context (they can be defined and are mathematically meaningful in general).

PdfMatrix objects are immutable. All transformations on them produce a new matrix.

a

b

c

d

e

f: Return one of the six “active values” of the affine matrix. e and f correspond to x- and y-axis translation respectively. The other four letters are a 2×2 matrix that can express rotation, scaling and skewing; a=1 b=0 c=0 d=1 is the identity matrix.

encode(): Encode this matrix in binary suitable for including in a PDF

static identity(): Constructs and returns an identity matrix

rotated(angle_degrees_ccw): Concatenates a rotation matrix on this matrix

scaled(x, y): Concatenates a scaling matrix on this matrix

property shorthand: Return the 6-tuple (a,b,c,d,e,f) that describes this matrix

translated(x, y): Translates this matrix

class pikepdf.PdfImage(obj)

Support class to provide a consistent API for manipulating PDF images

The data structure for images inside PDFs is irregular and flexible, making it difficult to work with without introducing errors for less typical cases. This class addresses these difficulties by providing a regular, Pythonic API similar in spirit (and convertible to) the Python Pillow imaging library.

as_pil_image()

Extract the image as a Pillow Image, using decompression as necessary

Returns: PIL.Image.Image

extract_to(*, stream=None, fileprefix='')

Attempt to extract the image directly to a usable image file

If possible, the compressed data is extracted and inserted into a compressed image file format without transcoding the compressed content. If this is not possible, the data will be decompressed and extracted to an appropriate format.

Because it is not known until attempted what image format will be extracted, users should not assume what format they are getting back. When saving the image to a file, use a temporary filename, and then rename the file to its final name based on the returned file extension.

Examples

>>> im.extract_to(stream=bytes_io)
'.png'

>>> im.extract_to(fileprefix='/tmp/image00')
'/tmp/image00.jpg'

Parameters

stream – Writable stream to write data to.
fileprefix (str or Path) – The path to write the extracted image to, without the file extension.

Returns

If fileprefix was provided, then the fileprefix with the appropriate extension. If no fileprefix, then an extension indicating the file type.

Return type:: str

get_stream_buffer(decode_level=<StreamDecodeLevel.specialized: 2>): Access this image with the buffer protocol

property icc

If an ICC profile is attached, return a Pillow object that describe it.

Most of the information may be found in icc.profile.

Returns: PIL.ImageCms.ImageCmsProfile

property is_inline: False for image XObject

read_bytes(decode_level=<StreamDecodeLevel.specialized: 2>): Decompress this image and return it as unencoded bytes

show(): Show the image however PIL wants to

class pikepdf.PdfInlineImage(*, image_data, image_object)

Support class for PDF inline images

Parameters: image_object (tuple) –

class pikepdf.models.PdfMetadata(pdf, pikepdf_mark=True, sync_docinfo=True, overwrite_invalid_xml=True)

Read and edit the metadata associated with a PDF

The PDF specification contain two types of metadata, the newer XMP (Extensible Metadata Platform, XML-based) and older DocumentInformation dictionary. The PDF 2.0 specification removes the DocumentInformation dictionary.

This primarily works with XMP metadata, but includes methods to generate XMP from DocumentInformation and will also coordinate updates to DocumentInformation so that the two are kept consistent.

XMP metadata fields may be accessed using the full XML namespace URI or the short name. For example metadata['dc:description'] and metadata['{http://purl.org/dc/elements/1.1/}description'] both refer to the same field. Several common XML namespaces are registered automatically.

See the XMP specification for details of allowable fields.

To update metadata, use a with block.

Example

>>> with pdf.open_metadata() as records:
        records['dc:title'] = 'New Title'