pyhanko.stamp package

Submodules

pyhanko.stamp.appearances module

class pyhanko.stamp.appearances.CoordinateSystem(*values)

Bases: Enum

Positioning convention for stamps.

PAGE_DEFAULT = 1: Always treat the stamp’s position in the page’s default coordinate system, by defensively forcing a restore to the original graphics state.

Note

This is the default behaviour since 0.27.0.

AMBIENT = 2: Apply the stamp in the ambient frame of reference set by the existing page content. This may yield unpredictable results depending on the input document.

Note

This was the default behaviour prior to 0.27.0.

pyhanko.stamp.art module

pyhanko.stamp.art.STAMP_ART_CONTENT = <pyhanko.pdf_utils.content.RawContent object>: Hardcoded stamp background that will render a stylised image of a stamp using PDF graphics operators (see below).

pyhanko.stamp.base module

class pyhanko.stamp.base.BaseStampStyle(border_width: int = 3, border_color: Tuple[float, float, float] | None=None, background: PdfContent | None = None, background_layout: SimpleBoxLayoutRule = SimpleBoxLayoutRule(x_align=<AxisAlignment.ALIGN_MID: 2>, y_align=<AxisAlignment.ALIGN_MID: 2>, margins=Margins(left=5, right=5, top=5, bottom=5), inner_content_scaling=<InnerScaling.SHRINK_TO_FIT: 4>), background_opacity: float = 0.6)

Bases: ConfigurableMixin

Base class for stamp styles.

border_width: int = 3: Border width in user units (for the stamp, not the text box).

border_color: Tuple[float, float, float] | None = None: Border color specified as an RGB tuple taking values between 0.0 and 1.0.

Warning

There is currently no direct support for non-RGB color spaces.

background: PdfContent | None = None: PdfContent instance that will be used to render the stamp’s background.

background_layout: SimpleBoxLayoutRule = SimpleBoxLayoutRule(x_align=<AxisAlignment.ALIGN_MID: 2>, y_align=<AxisAlignment.ALIGN_MID: 2>, margins=Margins(left=5, right=5, top=5, bottom=5), inner_content_scaling=<InnerScaling.SHRINK_TO_FIT: 4>)

Layout rule to render the background inside the stamp’s bounding box. Only used if the background has a fully specified PdfContent.box.

Otherwise, the renderer will position the cursor at (left_margin, bottom_margin) and render the content as-is.

background_opacity: float = 0.6: Opacity value to render the background at. This should be a floating-point number between 0 and 1.

classmethod process_entries(config_dict): This implementation of process_entries() processes the background configuration value. This can either be a path to an image file, in which case it will be turned into an instance of PdfImage, or the special value __stamp__, which is an alias for STAMP_ART_CONTENT.

create_stamp(writer: BasePdfFileWriter, box: BoxConstraints, text_params: dict) → BaseStamp | None

class pyhanko.stamp.base.BaseStamp(writer: BasePdfFileWriter, style, box: BoxConstraints | None = None)

Bases: AppearanceContent

render(): Compile the content to graphics operators.

apply(dest_page: int, x: int, y: int, *, coords: CoordinateSystem = CoordinateSystem.PAGE_DEFAULT)

Apply a stamp to a particular page in the PDF writer attached to this BaseStamp instance.

Parameters:

dest_page – Index of the page to which the stamp is to be applied (starting at 0).
x – Horizontal position of the stamp’s lower left corner on the page.
y – Vertical position of the stamp’s lower left corner on the page.
coords – The coordinate convention to use.

Returns:

A reference to the affected page object, together with a (width, height) tuple describing the dimensions of the stamp.

pyhanko.stamp.functions module

pyhanko.stamp.functions.qr_stamp_file(input_name: str, output_name: str, style: QRStampStyle, dest_page: int, x: int, y: int, url: str, text_params=None)

Add a QR stamp to a file.

Parameters:

input_name – Path to the input file.
output_name – Path to the output file.
style – QR stamp style to use.
dest_page – Index of the page to which the stamp is to be applied (starting at 0).
x – Horizontal position of the stamp’s lower left corner on the page.
y – Vertical position of the stamp’s lower left corner on the page.
url – URL for the QR code to point to.
text_params – Additional parameters for text template interpolation.

pyhanko.stamp.functions.text_stamp_file(input_name: str, output_name: str, style: TextStampStyle, dest_page: int, x: int, y: int, text_params=None)

Add a text stamp to a file.

Parameters:

input_name – Path to the input file.
output_name – Path to the output file.
style – Text stamp style to use.
dest_page – Index of the page to which the stamp is to be applied (starting at 0).
x – Horizontal position of the stamp’s lower left corner on the page.
y – Vertical position of the stamp’s lower left corner on the page.
text_params – Additional parameters for text template interpolation.

pyhanko.stamp.qr module

pyhanko.stamp.qr.DEFAULT_QR_SCALE = 0.2: If the layout & other bounding boxes don’t impose another size requirement, render QR codes at ~20% of their natural size in QR canvas units. At scale 1, this produces codes of about 2cm x 2cm for a 25-module QR code, which is probably OK.

class pyhanko.stamp.qr.QRPosition(*values)

Bases: Enum

QR positioning constants, with the corresponding default content layout rule.

LEFT_OF_TEXT = SimpleBoxLayoutRule(x_align=<AxisAlignment.ALIGN_MIN: 1>, y_align=<AxisAlignment.ALIGN_MID: 2>, margins=Margins(left=0, right=0, top=0, bottom=0), inner_content_scaling=<InnerScaling.SHRINK_TO_FIT: 4>)

RIGHT_OF_TEXT = SimpleBoxLayoutRule(x_align=<AxisAlignment.ALIGN_MAX: 3>, y_align=<AxisAlignment.ALIGN_MID: 2>, margins=Margins(left=0, right=0, top=0, bottom=0), inner_content_scaling=<InnerScaling.SHRINK_TO_FIT: 4>)

ABOVE_TEXT = SimpleBoxLayoutRule(x_align=<AxisAlignment.ALIGN_MID: 2>, y_align=<AxisAlignment.ALIGN_MAX: 3>, margins=Margins(left=0, right=0, top=0, bottom=0), inner_content_scaling=<InnerScaling.SHRINK_TO_FIT: 4>)

BELOW_TEXT = SimpleBoxLayoutRule(x_align=<AxisAlignment.ALIGN_MID: 2>, y_align=<AxisAlignment.ALIGN_MIN: 1>, margins=Margins(left=0, right=0, top=0, bottom=0), inner_content_scaling=<InnerScaling.SHRINK_TO_FIT: 4>)

property horizontal_flow

classmethod from_config(config_str) → QRPosition

Convert from a configuration string.

Parameters:: config_str – A string: ‘left’, ‘right’, ‘top’, ‘bottom’
Returns:: An QRPosition value.
Raises:: ConfigurationError – on unexpected string inputs.

class pyhanko.stamp.qr.QRStamp(writer: BasePdfFileWriter, url: str, style: QRStampStyle, text_params=None, box: BoxConstraints | None = None)

Bases: TextStamp

get_default_text_params()

Compute values for the default string interpolation parameters to be applied to the template string specified in the stamp style. This method does not take into account the text_params init parameter yet.

Returns:: A dictionary containing the parameters and their values.

apply(dest_page, x, y, *, coords: CoordinateSystem = CoordinateSystem.PAGE_DEFAULT)

Apply a stamp to a particular page in the PDF writer attached to this BaseStamp instance.

Parameters:

dest_page – Index of the page to which the stamp is to be applied (starting at 0).
x – Horizontal position of the stamp’s lower left corner on the page.
y – Vertical position of the stamp’s lower left corner on the page.
coords – The coordinate convention to use.

Returns:

A reference to the affected page object, together with a (width, height) tuple describing the dimensions of the stamp.

class pyhanko.stamp.qr.QRStampStyle(border_width: int = 3, border_color: Tuple[float, float, float] | None=None, background: PdfContent | None = None, background_layout: SimpleBoxLayoutRule = SimpleBoxLayoutRule(x_align=<AxisAlignment.ALIGN_MID: 2>, y_align=<AxisAlignment.ALIGN_MID: 2>, margins=Margins(left=5, right=5, top=5, bottom=5), inner_content_scaling=<InnerScaling.SHRINK_TO_FIT: 4>), background_opacity: float = 0.6, text_box_style: TextBoxStyle = TextBoxStyle(font=<pyhanko.pdf_utils.font.basic.SimpleFontEngineFactory object>, font_size=10, leading=None, border_width=0, box_layout_rule=None, vertical_text=False, text_color=None), inner_content_layout: SimpleBoxLayoutRule | None = None, stamp_text: str = 'Digital version available at\nthis url: %(url)s\nTimestamp: %(ts)s', timestamp_format: str = '%Y-%m-%d %H:%M:%S %Z', innsep: int = 3, qr_inner_size: int | None = None, qr_position: QRPosition = QRPosition.LEFT_OF_TEXT, qr_inner_content: PdfContent | None = None)

Bases: TextStampStyle

Style for text-based stamps together with a QR code.

This is exactly the same as a text stamp, except that the text box is rendered with a QR code to the left of it.

innsep: int = 3: Inner separation inside the stamp.

stamp_text: str = 'Digital version available at\nthis url: %(url)s\nTimestamp: %(ts)s': Text template for the stamp. The description of TextStampStyle.stamp_text still applies, but an additional default interpolation parameter url is available. This parameter will be replaced with the URL that the QR code points to.

qr_inner_size: int | None = None

Size of the QR code in the inner layout. By default, this is in user units, but if the stamp has a fully defined bounding box, it may be rescaled depending on inner_content_layout.

If unspecified, a reasonable default will be used.

qr_position: QRPosition = SimpleBoxLayoutRule(x_align=<AxisAlignment.ALIGN_MIN: 1>, y_align=<AxisAlignment.ALIGN_MID: 2>, margins=Margins(left=0, right=0, top=0, bottom=0), inner_content_scaling=<InnerScaling.SHRINK_TO_FIT: 4>): Position of the QR code relative to the text box.

qr_inner_content: PdfContent | None = None: Inner graphics content to be included in the QR code (experimental).

classmethod process_entries(config_dict): This implementation of process_entries() processes the background configuration value. This can either be a path to an image file, in which case it will be turned into an instance of PdfImage, or the special value __stamp__, which is an alias for STAMP_ART_CONTENT.

create_stamp(writer: BasePdfFileWriter, box: BoxConstraints, text_params: dict) → QRStamp

pyhanko.stamp.static module

class pyhanko.stamp.static.StaticContentStamp(writer: BasePdfFileWriter, style: StaticStampStyle, box: BoxConstraints)

Bases: BaseStamp

Class representing stamps with static content.

class pyhanko.stamp.static.StaticStampStyle(border_width: int = 3, border_color: Tuple[float, float, float] | None=None, background: PdfContent | None = None, background_layout: SimpleBoxLayoutRule = SimpleBoxLayoutRule(x_align=<AxisAlignment.ALIGN_MID: 2>, y_align=<AxisAlignment.ALIGN_MID: 2>, margins=Margins(left=5, right=5, top=5, bottom=5), inner_content_scaling=<InnerScaling.SHRINK_TO_FIT: 4>), background_opacity: float = 1.0)

Bases: BaseStampStyle

Stamp style that does not include any custom parts; it only renders the background.

background_opacity: float = 1.0: Opacity value to render the background at. This should be a floating-point number between 0 and 1.

classmethod from_pdf_file(file_name, page_ix=0, **kwargs) → StaticStampStyle

Create a StaticStampStyle from a page from an external PDF document. This is a convenience wrapper around ImportedPdfContent.

The remaining keyword arguments are passed to StaticStampStyle’s init method.

Parameters:

file_name – File name of the external PDF document.
page_ix – Page index to import. The default is 0, i.e. the first page.

create_stamp(writer: BasePdfFileWriter, box: BoxConstraints, text_params: dict) → StaticContentStamp

pyhanko.stamp.text module

class pyhanko.stamp.text.TextStamp(writer: BasePdfFileWriter, style, text_params=None, box: BoxConstraints | None = None)

Bases: BaseStamp

Class that renders a text stamp as specified by an instance of TextStampStyle.

text_box: TextBox | None

get_default_text_params()

Compute values for the default string interpolation parameters to be applied to the template string specified in the stamp style. This method does not take into account the text_params init parameter yet.

Returns:: A dictionary containing the parameters and their values.

class pyhanko.stamp.text.TextStampStyle(border_width: int = 3, border_color: Tuple[float, float, float] | None=None, background: PdfContent | None = None, background_layout: SimpleBoxLayoutRule = SimpleBoxLayoutRule(x_align=<AxisAlignment.ALIGN_MID: 2>, y_align=<AxisAlignment.ALIGN_MID: 2>, margins=Margins(left=5, right=5, top=5, bottom=5), inner_content_scaling=<InnerScaling.SHRINK_TO_FIT: 4>), background_opacity: float = 0.6, text_box_style: TextBoxStyle = TextBoxStyle(font=<pyhanko.pdf_utils.font.basic.SimpleFontEngineFactory object>, font_size=10, leading=None, border_width=0, box_layout_rule=None, vertical_text=False, text_color=None), inner_content_layout: SimpleBoxLayoutRule | None = None, stamp_text: str = '%(ts)s', timestamp_format: str = '%Y-%m-%d %H:%M:%S %Z')

Bases: BaseStampStyle

Style for text-based stamps.

Roughly speaking, this stamp type renders some predefined (but parametrised) piece of text inside a text box, and possibly applies a background to it.

text_box_style: TextBoxStyle = TextBoxStyle(font=<pyhanko.pdf_utils.font.basic.SimpleFontEngineFactory object>, font_size=10, leading=None, border_width=0, box_layout_rule=None, vertical_text=False, text_color=None): The text box style for the internal text box used.

inner_content_layout: SimpleBoxLayoutRule | None = None: Rule determining the position and alignment of the inner text box within the stamp.

Warning

This only affects the position of the box, not the alignment of the text within.

stamp_text: str = '%(ts)s'

Text template for the stamp. The template can contain an interpolation parameter ts that will be replaced by the stamping time.

Additional parameters may be added if necessary. Values for these must be passed to the __init__() method of the TextStamp class in the text_params argument.

timestamp_format: str = '%Y-%m-%d %H:%M:%S %Z': Datetime format used to render the timestamp.

create_stamp(writer: BasePdfFileWriter, box: BoxConstraints, text_params: dict) → TextStamp