pyhanko.stamp module¶
Utilities for stamping PDF files.
Here ‘stamping’ loosely refers to adding small overlays (QR codes, text boxes, etc.) on top of already existing content in PDF files.
The code in this module is also used by the sign
module to render
signature appearances.
-
class
pyhanko.stamp.
AnnotAppearances
(normal: pyhanko.pdf_utils.generic.IndirectObject, rollover: Optional[pyhanko.pdf_utils.generic.IndirectObject] = None, down: Optional[pyhanko.pdf_utils.generic.IndirectObject] = None)¶ Bases:
object
Convenience abstraction to set up an appearance dictionary for a PDF annotation.
Annotations can have three appearance streams, which can be roughly characterised as follows:
normal: the only required one, and the default one;
rollover: used when mousing over the annotation;
down: used when clicking the annotation.
These are given as references to form XObjects.
Note
This class only covers the simple case of an appearance dictionary for an annotation with only one appearance state.
See § 12.5.5 in ISO 32000-1 for further information.
-
as_pdf_object
() → pyhanko.pdf_utils.generic.DictionaryObject¶ Convert the
AnnotationAppearances
instance to a PDF dictionary.- Returns
A
DictionaryObject
that can be plugged into the/AP
entry of an annotation dictionary.
-
class
pyhanko.stamp.
TextStampStyle
(text_box_style: pyhanko.pdf_utils.text.TextBoxStyle = TextBoxStyle(font=<pyhanko.pdf_utils.font.SimpleFontEngine object>, font_size=10, leading=None, text_sep=10, border_width=0, vertical_center=True), border_width: int = 3, stamp_text: str = '%(ts)s', timestamp_format: str = '%Y-%m-%d %H:%M:%S %Z', background: Optional[pyhanko.pdf_utils.content.PdfContent] = None, background_opacity: float = 0.6)¶ Bases:
pyhanko.pdf_utils.config_utils.ConfigurableMixin
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
: pyhanko.pdf_utils.text.TextBoxStyle = TextBoxStyle(font=<pyhanko.pdf_utils.font.SimpleFontEngine object>, font_size=10, leading=None, text_sep=10, border_width=0, vertical_center=True)¶ The text box style for the internal text box used.
-
border_width
: int = 3¶ Border width in user units (for the stamp, not the text box).
-
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 theTextStamp
class in thetext_params
argument.
-
timestamp_format
: str = '%Y-%m-%d %H:%M:%S %Z'¶ Datetime format used to render the timestamp.
-
background
: pyhanko.pdf_utils.content.PdfContent = None¶ PdfContent
instance that will be used to render the stamp’s background.
-
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)¶ The implementation of
process_entries()
callsTextBoxStyle.from_config()
to parse thetext_box_style
configuration entry, if present.Then, it processes the background specified. 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 forSTAMP_ART_CONTENT
.See
ConfigurableMixin.process_entries()
for general documentation about this method.
-
-
class
pyhanko.stamp.
QRStampStyle
(text_box_style: pyhanko.pdf_utils.text.TextBoxStyle = TextBoxStyle(font=<pyhanko.pdf_utils.font.SimpleFontEngine object>, font_size=10, leading=None, text_sep=10, border_width=0, vertical_center=True), border_width: int = 3, stamp_text: str = 'Digital version available at\nthis url: %(url)s\nTimestamp: %(ts)s', timestamp_format: str = '%Y-%m-%d %H:%M:%S %Z', background: Optional[pyhanko.pdf_utils.content.PdfContent] = None, background_opacity: float = 0.6, innsep: int = 3, stamp_qrsize: float = 0.25)¶ Bases:
pyhanko.stamp.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 parameterurl
is available. This parameter will be replaced with the URL that the QR code points to.
-
stamp_qrsize
: float = 0.25¶ Indicates the proportion of the width of the stamp that should be taken up by the QR code.
-
-
pyhanko.stamp.
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).
-
class
pyhanko.stamp.
TextStamp
(writer: pyhanko.pdf_utils.incremental_writer.IncrementalPdfFileWriter, style, text_params=None, box: Optional[pyhanko.pdf_utils.layout.BoxConstraints] = None)¶ Bases:
pyhanko.pdf_utils.content.PdfContent
Class that renders a text stamp as specified by an instance of
TextStampStyle
.-
extra_commands
() → list¶ Render extra graphics commands to be used after painting the inner text box, but before drawing the border.
- Returns
A list of
bytes
objects.
-
get_stamp_width
() → int¶ Compute the stamp’s total width.
- Returns
The width of the stamp in user units.
-
get_stamp_height
() → int¶ Compute the stamp’s total height.
- Returns
The height of the stamp in user units.
-
text_box_x
() → int¶ Text box x-coordinate.
- Returns
The horizontal position of the internal text box’s lower left corner inside the stamp’s bounding box.
-
text_box_y
()¶ Text box y-coordinate.
- Returns
The horizontal position of the internal text box’s lower left corner inside the stamp’s bounding box.
-
get_default_text_params
()¶ Compute values for the default string interpolation parameters to be applied to the template string string specified in the he stamp style. This method does not take into account the
text_params
init parameter yet.- Returns
A dictionary containing the parameters and their values.
-
render
()¶ Compile the content to graphics operators.
-
register
() → pyhanko.pdf_utils.generic.IndirectObject¶ Register the stamp with the writer coupled to this instance, and cache the returned reference.
This works by calling
PdfContent.as_form_xobject()
.- Returns
An indirect reference to the form XObject containing the stamp.
-
apply
(dest_page: int, x: int, y: int)¶ Apply a stamp to a particular page in the PDF writer attached to this
TextStamp
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.
- Returns
A reference to the affected page object, together with a
(width, height)
tuple describing the dimensions of the stamp.
-
as_appearances
() → pyhanko.stamp.AnnotAppearances¶ Turn this stamp into an appearance dictionary for an annotation (or a form field widget), after rendering it. Only the normal appearance will be defined.
- Returns
An instance of
AnnotAppearances
.
-
-
class
pyhanko.stamp.
QRStamp
(writer: pyhanko.pdf_utils.incremental_writer.IncrementalPdfFileWriter, url: str, style: pyhanko.stamp.QRStampStyle, text_params=None, box: Optional[pyhanko.pdf_utils.layout.BoxConstraints] = None)¶ Bases:
pyhanko.stamp.TextStamp
-
qr_default_width
= 30¶ Default value for the QR code’s width in user units. This value is only used if the stamp’s bounding box does not have a defined width, in which case the
QRStampStyle.stamp_qrsize
attribute is unusable.You can safely override this attribute if you so desire.
-
property
qr_size
¶ Compute the effective size of the QR code.
- Returns
The size of the QR code in user units.
-
extra_commands
()¶ Render extra graphics commands to be used after painting the inner text box, but before drawing the border.
- Returns
A list of
bytes
objects.
-
text_box_x
()¶ Text box x-coordinate.
- Returns
The horizontal position of the internal text box’s lower left corner inside the stamp’s bounding box.
-
get_stamp_height
()¶ Compute the stamp’s total height.
- Returns
The height of the stamp in user units.
-
get_default_text_params
()¶ Compute values for the default string interpolation parameters to be applied to the template string string specified in the he 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)¶ Apply a stamp to a particular page in the PDF writer attached to this
TextStamp
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.
- Returns
A reference to the affected page object, together with a
(width, height)
tuple describing the dimensions of the stamp.
-
-
pyhanko.stamp.
text_stamp_file
(input_name: str, output_name: str, style: pyhanko.stamp.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_stamp_file
(input_name: str, output_name: str, style: pyhanko.stamp.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.