`padding` Module#

Classes#

`Padding`	Render output padding.
`AlignedPadding`	Aligned render output padding.
`ExactPadding`	Exact render output padding.

class term_image.padding.Padding(fill=' ')[source]#

Bases: object

Render output padding.

Parameters:

fill (str) –

Determines the string with which render outputs will be padded.

May be any string that occupies exactly one column on a terminal screen, or an empty string. If empty, the padding simply advances the cursor without overwriting existing content on the terminal screen.

Attention

This is an abstract base class. Hence, only concrete subclasses can be instantiated.

See also

Padding: Padding‘s Extension API

Attributes:

fill

Fill string

Instance Methods:

`get_padded_size`	Computes an expected padded render size.
`pad`	Pads a render output.
`to_exact`	Converts the padding to an exact padding for the given render size.

fill: str#: Fill string

get_padded_size(render_size)[source]#

Computes an expected padded render size.

Parameters:: render_size (Size) – Render size.
Returns:: The size of the render output that would be produced by using this instance to pad a render output with the given size.
Return type:: Size

pad(render, render_size)[source]#

Pads a render output.

Parameters:

render (str) – A render output, in the form specified to be returned by Renderable._render_().
render_size (Size) – Render size of render.

Returns:

The padded render output.

This is also in the form specified to be returned by Renderable._render_(), provided render is.

Return type:

str

to_exact(render_size)[source]#

Converts the padding to an exact padding for the given render size.

Parameters:: render_size (Size) – Render size.
Returns:: An equivalent exact padding, with respect to the given render size i.e one that would produce the same result as the padding being converted, for the given render size.
Return type:: ExactPadding

This is useful to avoid recomputing the exact padding dimensions for the same render size.

class term_image.padding.AlignedPadding(width, height, h_align=HAlign.CENTER, v_align=VAlign.MIDDLE, fill=' ')[source]#

Bases: Padding

Aligned render output padding.

Parameters:

width (int) – Minimum render width.
height (int) – Minimum render height.
h_align (HAlign) – Horizontal alignment.
v_align (VAlign) – Vertical alignment.

If width or height is:

positive, it is absolute and used as-is.
non-positive, it is relative to the corresponding terminal dimension (at the point of resolution) and equivalent to the absolute dimension max(terminal_dimension + relative_dimension, 1).

The padded render dimension (i.e the dimension of a render output after it’s padded) on each axis is given by:

padded_dimension = max(render_dimension, absolute_minimum_dimension)

In words… If the absolute minimum render dimension on an axis is less than or equal to the corresponding render dimension, there is no padding on that axis and the padded render dimension on that axis is equal to the render dimension. Otherwise, the render output will be padded along that axis and the padded render dimension on that axis is equal to the minimum render dimension.

The amount of padding to each side depends on the alignment, defined by h_align and v_align.

Important

RelativePaddingDimensionError is raised if any padding-related computation/operation (basically, calling any method other than resolve()) is performed on an instance with relative minimum render dimension(s) i.e if relative is True.

Note

Any interface receiving an instance with relative dimension(s) should typically resolve it/them upon reception.

Tip

Instances are immutable and hashable.
Instances with equal fields compare equal.

Attributes:

`width`	Minimum render width
`height`	Minimum render height
`h_align`	Horizontal alignment
`v_align`	Vertical alignment
`relative`	`True` if either or both minimum render dimension(s) is/are relative i.e non-positive.

Instance Properties:

size

Minimum render size

Instance Methods:

`get_padded_size`	Computes an expected padded render size.
`resolve`	Resolves relative minimum render dimensions.

width: int#: Minimum render width

height: int#: Minimum render height

h_align: HAlign#: Horizontal alignment

v_align: VAlign#: Vertical alignment

relative: bool#: True if either or both minimum render dimension(s) is/are relative i.e non-positive. Otherwise, False.

property size: RawSize#

Minimum render size

GET:: Returns the minimum render dimensions.

get_padded_size(render_size)[source]#

Computes an expected padded render size.

See Padding.get_padded_size().

Raises:: RelativePaddingDimensionError – Relative minimum render dimension(s).

resolve(terminal_size)[source]#

Resolves relative minimum render dimensions.

Parameters:: terminal_size (terminal_size) – The terminal size against which to resolve relative dimensions.
Returns:: An instance with equivalent absolute dimensions.
Return type:: AlignedPadding

class term_image.padding.ExactPadding(left=0, top=0, right=0, bottom=0, fill=' ')[source]#

Bases: Padding

Exact render output padding.

Parameters:

left (int) – Left padding dimension
top (int) – Top padding dimension.
right (int) – Right padding dimension
bottom (int) – Bottom padding dimension

Raises:

ValueError – A dimension is negative.

Pads a render output on each side by the specified amount of lines or columns.

Tip

Instances are immutable and hashable.
Instances with equal fields compare equal.

Attributes:

`left`	Left padding dimension
`top`	Top padding dimension
`right`	Right padding dimension
`bottom`	Bottom padding dimension

Instance Properties:

dimensions

Padding dimensions

left: int#: Left padding dimension

top: int#: Top padding dimension

right: int#: Right padding dimension

bottom: int#: Bottom padding dimension

property dimensions: tuple[int, int, int, int]#

Padding dimensions

GET:: Returns the padding dimensions, (left, top, right, bottom).

Enumerations#

`HAlign`	Horizontal alignment enumeration
`VAlign`	Vertical alignment enumeration

class term_image.padding.HAlign[source]#

Bases: IntEnum

Horizontal alignment enumeration

LEFT#

Left horizontal alignment

CENTER#

Center horizontal alignment

RIGHT#

Right horizontal alignment

class term_image.padding.VAlign[source]#

Bases: IntEnum

Vertical alignment enumeration

TOP#

Top vertical alignment

MIDDLE#

Middle vertical alignment

BOTTOM#

Bottom vertical alignment

Exceptions#

`PaddingError`	Base exception class for padding errors.
`RelativePaddingDimensionError`	Raised when a padding operation is performed on an `AlignedPadding` instance with relative minimum render dimension(s).

exception term_image.padding.PaddingError[source]#

Bases: TermImageError

Base exception class for padding errors.

exception term_image.padding.RelativePaddingDimensionError[source]#

Bases: PaddingError

Raised when a padding operation is performed on an AlignedPadding instance with relative minimum render dimension(s).

Extension API#

Note

The following definitions are provided and required only for extended use of the interfaces defined above.

Everything required for normal usage should typically be exposed in the public API.

Padding#

class term_image.padding.Padding[source]

See Padding for the public API.

Note

Instances of subclasses should be immutable to avoid inconsistent results in asynchronous render operations that perform padding.

Instance Methods:

_get_exact_dimensions_

Returns the exact padding dimensions for the given render size.

abstract _get_exact_dimensions_(render_size)[source]#

Returns the exact padding dimensions for the given render size.

Parameters:: render_size (Size) – Render size.
Returns:: Returns the exact padding dimensions, (left, top, right, bottom).
Return type:: tuple[int, int, int, int]

This is called to implement operations in the public API.

padding Module#

Classes#

Enumerations#

Exceptions#

Extension API#

Padding#

`padding` Module#