pdftools_toolbox.pdf.content.content_generator

Classes

ContentGenerator(content, prepend)

class pdftools_toolbox.pdf.content.content_generator.ContentGenerator(content: Content, prepend: bool)

Bases: _NativeObject

__init__(content: Content, prepend: bool)

Create a new content generator for appending or prepending to the content of a group.

Parameters:

• content (pdftools_toolbox.pdf.content.content.Content) – the content object of a page or group

• prepend (bool) – True for prepending to the content (apply content to background of page), False for appending (apply content to foreground of page)

Raises:

• ValueError – if the document associated with content has already been closed

• ValueError – if the page or group associated with the content has already been appended or closed

save() → None

Save the current graphics state

The graphics state is stored on the graphics state stack. The following properties are affected:

• The current transform matrix

• The current clip path

Raises:

• StateError – if the document associated with the content has already been closed

• StateError – if the page/group associated with the content has already been closed

• StateError – if the content object has already been closed

• StateError – if the object has already been closed

restore() → None

Restore the graphics state.

The most recently saved state is restored and removed from the graphics state stack. The following properties are affected:

• The current transform matrix

• The current clip path

Raises:

• StateError – if the document associated with the content has already been closed

• StateError – if the page/group associated with the content has already been closed

• StateError – if the content object has already been closed

• StateError – if the object has already been closed

transform(transform: AffineTransform) → None

Modify the current transform matrix by concatenating the specified matrix.

Parameters:

transform (pdftools_toolbox.geometry.real.affine_transform.AffineTransform) – the transform that is applied to the current transform

Raises:

• StateError – if the document associated with the content has already been closed

• StateError – if the page/group associated with the content has already been closed

• StateError – if the content object has already been closed

• StateError – if the object has already been closed

• ValueError – if the transform object has already been closed

• ValueError – if the transform is non-invertible

tag_as(node: Node, language: str | None = None) → None

Associate content created following this call with the supplied element of the document structure tree.

Parameters:

• node (pdftools_toolbox.pdf.structure.node.Node) – the tag to be applied to the marked content

• language (Optional[str]) –

  The language code that specifies the language of the tagged content.

  Specifying the language is highly recommended for PDF/A level A conformance.

  The codes are defined in BCP 47 and ISO 3166:2013 and can be obtained from the Internet Engineering Task Force and the International Organization for Standardization.

  If no code is set, the language will be specified as unknown.

  Examples:

  • ”en”

  • ”en-US”

  • ”de”

  • ”de-CH”

  • ”fr-FR”

  • ”zxx” (for non linguistic content)

  Default is None (unknown)

Raises:

• StateError – if the document associated with the content has already been closed

• pdftools_toolbox.unsupported_feature_error.UnsupportedFeatureError – if trying to tag in a content generator not associated with a page

• ValueError – if the node has a tag value that is not allowed (not part of PDF 1.7 specification and not in RoleMap)

stop_tagging() → None

Stop tagging content.

Raises:

StateError – if the document associated with the content has already been closed

paint_image(image: Image, target_rect: Rectangle) → None

Paint an image.

Parameters:

• image (pdftools_toolbox.pdf.content.image.Image) – the image to be painted

• targetRect (pdftools_toolbox.geometry.real.rectangle.Rectangle) – the target rectangle in the current coordinate system. If targetRect is None, the unit rectangle [0, 0, 1, 1] is used.

Raises:

• StateError – if the document associated with the content has already been closed

• StateError – if the page/group associated with the content has already been closed

• StateError – if the content object has already been closed

• StateError – if the object has already been closed

• ValueError – if the document associated with image has already been closed

• ValueError – if the image is associated with a different document

paint_image_mask(image_mask: ImageMask, target_rect: Rectangle, paint: Paint) → None

Paint an image (stencil) mask.

An image mask is a monochrome image, in which each sample is specified by a single bit. However, instead of being painted in opaque black and white, the image mask is treated as a stencil mask that is partly opaque and partly transparent. Sample values in the image do not represent black and white pixels; rather, they designate places on the content that should either be marked with the given paint or masked out (not marked at all). Areas that are masked out retain their former content.

The effect is like applying paint in the current color through a cut-out stencil, which allows the paint to reach the page in some places and masks it out in others.

Parameters:

• imageMask (pdftools_toolbox.pdf.content.image_mask.ImageMask) – the image (stencil) mask

• targetRect (pdftools_toolbox.geometry.real.rectangle.Rectangle) – the target rectangle in the current coordinate system. If targetRect is None, the unit rectangle [0, 0, 1, 1] is used.

• paint (pdftools_toolbox.pdf.content.paint.Paint) – the paint for filling marked pixels

Raises:

• StateError – if the document associated with the content has already been closed

• StateError – if the page/group associated with the content has already been closed

• StateError – if the content object has already been closed

• StateError – if the object has already been closed

• ValueError – if the document associated with imageMask has already been closed

• ValueError – if the imageMask object is not an image mask

• ValueError – if the imageMask is associated with a different document

• ValueError – if the document associated with paint has already been closed

• ValueError – if the paint is associated with a different document

paint_path(path: Path, fill: Fill | None, stroke: Stroke | None) → None

Paint a path.

The path is first filled and then stroked The blend mode for filling and stroking must be the same.

Parameters:

• path (pdftools_toolbox.pdf.content.path.Path) – the path to be painted

• fill (Optional[pdftools_toolbox.pdf.content.fill.Fill]) – the fill properties or None if the path should not be filled

• stroke (Optional[pdftools_toolbox.pdf.content.stroke.Stroke]) – the stroke properties or None if the path should not be stroked

Raises:

• StateError – if the document associated with the content has already been closed

• StateError – if the page/group associated with the content has already been closed

• StateError – if the content object has already been closed

• StateError – if the object has already been closed

• ValueError – if the fill and stroke arguments are both None.

• ValueError – if the document associated with the fill object has already been closed

• ValueError – if the fill object belongs to a different document

• ValueError – if the property pdftools_toolbox.pdf.content.stroke.Stroke.paint of argument stroke is None.

• ValueError – if the document associated with the property pdftools_toolbox.pdf.content.stroke.Stroke.paint of argument stroke has already been closed.

• ValueError – if the stroke argument belongs to a different document

• OperationError – if the pdftools_toolbox.pdf.content.paint.Paint objects for filling and stroking use different blend modes

paint_text(text: Text) → None

Paint text.

Parameters:

text (pdftools_toolbox.pdf.content.text.Text) – the text to be painted

Raises:

• StateError – if the document associated with the content has already been closed

• StateError – if the page/group associated with the content has already been closed

• StateError – if the content object has already been closed

• StateError – if the object has already been closed

• ValueError – if the text is associated with a different document

• pdftools_toolbox.generic_error.GenericError – if for some of the requested characters to paint the font’s encoding is not defined or no glyph exists in the font

clip_with_path(path: Path, inside_rule: InsideRule) → None

Intersect clip path with path.

Update the current clip path by intersecting with the given path.

Parameters:

• path (pdftools_toolbox.pdf.content.path.Path) – the path to intersect with the current clip path

• insideRule (pdftools_toolbox.pdf.content.inside_rule.InsideRule) – the inside rule of the path argument

Raises:

• StateError – if the document associated with the content has already been closed

• StateError – if the page/group associated with the content has already been closed

• StateError – if the content object has already been closed

• StateError – if the object has already been closed

• ValueError – if the path is associated with a different document

clip_with_text(text: Text) → None

Intersect clip path with text.

Update the current clip path by intersecting with the given text.

Parameters:

text (pdftools_toolbox.pdf.content.text.Text) – the text to intersect with the current clip path

Raises:

• StateError – if the document associated with the content has already been closed

• StateError – if the page/group associated with the content has already been closed

• StateError – if the content object has already been closed

• StateError – if the object has already been closed

• ValueError – if the document associated with the text object has already been closed

• ValueError – if the text is associated with a different document

• pdftools_toolbox.generic_error.GenericError – if for some of the requested characters to paint the font’s encoding is not defined or no glyph exists in the font

paint_group(group: Group, target_rect: Rectangle | None, transparency: Transparency | None) → None

Paint a group.

Parameters:

• group (pdftools_toolbox.pdf.content.group.Group) – the group to be painted

• targetRect (Optional[pdftools_toolbox.geometry.real.rectangle.Rectangle]) – the target rectangle in the current coordinate system. If targetRect is None, a default rectangle [0, 0, width, height] is used, where width and height are the dimensions of the given group’s Size

• transparency (Optional[pdftools_toolbox.pdf.content.transparency.Transparency]) – the transparency to be used when painting the group. If Transparency is None, then the group is painted opaquely.

Raises:

• StateError – if the document associated with the content has already been closed

• StateError – if the page/group associated with the content has already been closed

• StateError – if the content object has already been closed

• StateError – if the object has already been closed

• ValueError – if the document associated with the group object has already been closed

• ValueError – if the group is associated with a different document

• ValueError – if the group contains no content or the content generator has not been closed yet

• ValueError – if the group contains interactive elements (see pdftools_toolbox.pdf.content.group.Group.copy_from_page() ) and it has been painted before.

• ValueError – if the group contains interactive elements (see pdftools_toolbox.pdf.content.group.Group.copy_from_page() ) and the content of the content generator belongs to an annotation.

• pdftools_toolbox.conformance_error.ConformanceError – if the transparency argument is not None and has properties pdftools_toolbox.pdf.content.transparency.Transparency.alpha other than 1.0 or pdftools_toolbox.pdf.content.transparency.Transparency.blend_mode other than pdftools_toolbox.pdf.content.blend_mode.BlendMode.NORMAL , and the explicitly specified conformance does not support transparency (PDF/A-1, PDF 1.0 - 1.3).

append_content_element(content_element: ContentElement) → None

Paint a content element

Parameters:

contentElement (pdftools_toolbox.pdf.content.content_element.ContentElement) – the content element to be painted

Raises:

• StateError – if the document associated with the content has already been closed

• StateError – if the contentElement object has already been closed

• StateError – if the content object has already been closed

• ValueError – if the contentElement is associated with a different document