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)

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)

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.