pyhanko.pdf_utils.layout module

Layout utilities (to be expanded)

exception pyhanko.pdf_utils.layout.LayoutError

Bases: ValueError

Indicates an error in a layout computation.

exception pyhanko.pdf_utils.layout.BoxSpecificationError

Bases: pyhanko.pdf_utils.layout.LayoutError

Raised when a box constraint is over/underspecified.

class pyhanko.pdf_utils.layout.BoxConstraints(width=None, height=None, aspect_ratio: Optional[fractions.Fraction] = None)

Bases: object

Represents a box of potentially variable width and height. Among other uses, this can be leveraged to produce a variably sized box with a fixed aspect ratio.

If width/height are not defined yet, they can be set by assigning to the width and height attributes.

property width: int

Returns: The width of the box.
Raises: BoxSpecificationError – if the box’s width could not be determined.

property width_defined: bool

Returns: True if the box currently has a well-defined width, False otherwise.

property height: int

Returns: The height of the box.
Raises: BoxSpecificationError – if the box’s height could not be determined.

property height_defined: bool

Returns: True if the box currently has a well-defined height, False otherwise.

property aspect_ratio: fractions.Fraction

Returns: The aspect ratio of the box.
Raises: BoxSpecificationError – if the box’s aspect ratio could not be determined.

property aspect_ratio_defined: bool

Returns: True if the box currently has a well-defined aspect ratio, False otherwise.

class pyhanko.pdf_utils.layout.AxisAlignment(value)

Bases: enum.Enum

Class representing one-dimensional alignment along an axis.

ALIGN_MIN = 1: Align maximally towards the negative end of the axis.

ALIGN_MID = 2: Center content along the axis.

ALIGN_MAX = 3: Align maximally towards the positive end of the axis.

classmethod from_x_align(align_str: str) → pyhanko.pdf_utils.layout.AxisAlignment

Convert from a horizontal alignment config string.

Parameters: align_str – A string: ‘left’, ‘mid’ or ‘right’.
Returns: An AxisAlignment value.
Raises: ConfigurationError – on unexpected string inputs.

classmethod from_y_align(align_str: str) → pyhanko.pdf_utils.layout.AxisAlignment

Convert from a vertical alignment config string.

Parameters: align_str – A string: ‘bottom’, ‘mid’ or ‘top’.
Returns: An AxisAlignment value.
Raises: ConfigurationError – on unexpected string inputs.

property flipped

align(container_len: int, inner_len: int, pre_margin, post_margin) → int

class pyhanko.pdf_utils.layout.Margins(left: int = 0, right: int = 0, top: int = 0, bottom: int = 0)

Bases: pyhanko.pdf_utils.config_utils.ConfigurableMixin

Class describing a set of margins.

left: int = 0

right: int = 0

top: int = 0

bottom: int = 0

classmethod uniform(num)

Return a set of uniform margins.

Parameters: num – The uniform margin to apply to all four sides.
Returns: Margins(num, num, num, num)

static effective(dim_name, container_len, pre, post): Internal helper method to compute effective margins.

effective_width(width)

Compute width without margins.

Parameters: width – The container width.
Returns: The width after subtracting the left and right margins.
Raises: LayoutError – if the container width is too short to accommodate the margins.

effective_height(height)

Compute height without margins.

Parameters: height – The container height.
Returns: The height after subtracting the top and bottom margins.
Raises: LayoutError – if the container height is too short to accommodate the margins.

classmethod from_config(config_dict)

Attempt to instantiate an object of the class on which it is called, by means of the configuration settings passed in.

First, we check that the keys supplied in the dictionary correspond to data fields on the current class. Then, the dictionary is processed using the process_entries() method. The resulting dictionary is passed to the initialiser of the current class as a kwargs dict.

Parameters: config_dict – A dictionary containing configuration values.
Returns: An instance of the class on which it is called.
Raises: ConfigurationError – when an unexpected configuration key is encountered or left unfilled, or when there is a problem processing one of the config values.

class pyhanko.pdf_utils.layout.InnerScaling(value)

Bases: enum.Enum

Class representing a scaling convention.

NO_SCALING = 1: Never scale content.

STRETCH_FILL = 2: Scale content to fill the entire container.

STRETCH_TO_FIT = 3: Scale content while preserving aspect ratio until either the maximal width or maximal height is reached.

SHRINK_TO_FIT = 4: Scale content down to fit in the container, while preserving the original aspect ratio.

classmethod from_config(config_str: str) → pyhanko.pdf_utils.layout.InnerScaling

Convert from a configuration string.

Parameters: config_str – A string: ‘none’, ‘stretch-fill’, ‘stretch-to-fit’, ‘shrink-to-fit’
Returns: An InnerScaling value.
Raises: ConfigurationError – on unexpected string inputs.

class pyhanko.pdf_utils.layout.SimpleBoxLayoutRule(x_align: pyhanko.pdf_utils.layout.AxisAlignment, y_align: pyhanko.pdf_utils.layout.AxisAlignment, margins: pyhanko.pdf_utils.layout.Margins = Margins(left=0, right=0, top=0, bottom=0), inner_content_scaling: pyhanko.pdf_utils.layout.InnerScaling = InnerScaling.SHRINK_TO_FIT)

Bases: pyhanko.pdf_utils.config_utils.ConfigurableMixin

Class describing alignment, scaling and margin rules for a box positioned inside another box.

x_align: pyhanko.pdf_utils.layout.AxisAlignment: Horizontal alignment settings.

y_align: pyhanko.pdf_utils.layout.AxisAlignment: Vertical alignment settings.

margins: pyhanko.pdf_utils.layout.Margins = Margins(left=0, right=0, top=0, bottom=0): Container (inner) margins. Defaults to all zeroes.

inner_content_scaling: pyhanko.pdf_utils.layout.InnerScaling = 4: Inner content scaling rule.

classmethod process_entries(config_dict)

Hook method that can modify the configuration dictionary to overwrite or tweak some of their values (e.g. to convert string parameters into more complex Python objects)

Subclasses that override this method should call super().process_entries(), and leave keys that they do not recognise untouched.

Parameters: config_dict – A dictionary containing configuration values.
Raises: ConfigurationError – when there is a problem processing a relevant entry.

substitute_margins(new_margins: pyhanko.pdf_utils.layout.Margins) → pyhanko.pdf_utils.layout.SimpleBoxLayoutRule

fit(container_box: pyhanko.pdf_utils.layout.BoxConstraints, inner_nat_width: int, inner_nat_height: int) → pyhanko.pdf_utils.layout.Positioning

Position and possibly scale a box within a container, according to this layout rule.

Parameters

container_box – BoxConstraints describing the container.
inner_nat_width – The inner box’s natural width.
inner_nat_height – The inner box’s natural height.

Returns

A Positioning describing the scaling & position of the lower left corner of the inner box.

class pyhanko.pdf_utils.layout.Positioning(x_pos: int, y_pos: int, x_scale: float, y_scale: float)

Bases: pyhanko.pdf_utils.config_utils.ConfigurableMixin

Class describing the position and scaling of an object in a container.

x_pos: int: Horizontal coordinate

y_pos: int: Vertical coordinate

x_scale: float: Horizontal scaling

y_scale: float: Vertical scaling

as_cm()

Convenience method to convert this Positioning into a PDF cm operator.

Returns: A byte string representing the cm operator corresponding to this Positioning.