padding
Module#
Classes#
Render output padding. |
|
Aligned render output padding. |
|
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.
Attributes:
Fill string
Instance Methods:
Computes an expected padded render size.
Pads a render output.
Converts the padding to an exact padding for the given render size.
- 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:
- 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:
- 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:
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 thanresolve()
) is performed on an instance with relative minimum render dimension(s) i.e ifrelative
isTrue
.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:
Minimum render width
Minimum render height
Horizontal alignment
Vertical alignment
True
if either or both minimum render dimension(s) is/are relative i.e non-positive.Instance Properties:
Minimum render size
Instance Methods:
Computes an expected padded render size.
Resolves relative minimum render dimensions.
- width: int#
Minimum render width
- height: int#
Minimum render height
- 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:
- class term_image.padding.ExactPadding(left=0, top=0, right=0, bottom=0, fill=' ')[source]#
Bases:
Padding
Exact render output padding.
- Parameters:
- 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 padding dimension
Top padding dimension
Right padding dimension
Bottom padding dimension
Instance Properties:
Padding dimensions
Enumerations#
- 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#
Base exception class for padding errors. |
|
Raised when a padding operation is performed on an |
- 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:
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:
This is called to implement operations in the public API.