euporie.core.layout.containers

Overrides for PTK containers with optimized rendering.

This module provides enhanced versions of prompt_toolkit containers that: - Only render visible lines rather than the entire content - Use cached dimension calculations for better performance - Support bounded write positions to clip rendering - Share padding window instances for efficiency - Apply cursor line styles more efficiently

Functions

DummyContainer([width, height])	A minimal container with fixed dimensions.
NamedTuple(typename[, fields])	Typed version of namedtuple.
distribute_dimensions(size, dimensions)	Return the heights/widths for all rows/columns, or None when there is not enough space.
explode_text_fragments(fragments)	Turn a list of (style_str, text) tuples into another list where each string is exactly one character.
fragment_list_width(fragments)	Return the character width of this text fragment list.
get_app()	Get the current active (running) Application.
get_cwidth(string)	Return width of a string.
lru_cache([maxsize, typed])	Least-recently-used cache decorator.
take_using_weights(items, weights)	Generator that keeps yielding items from the items list, in proportion to their weight. For instance::.
to_formatted_text(value[, style, auto_convert])	Convert the given value (which can be formatted text) into a list of text fragments.
to_str(value)	Turn callable or string into string.

Classes

BoundedWritePosition(xpos, ypos, width, height)	A write position which also hold bounding box information.
Container()	Base class for user interface layout.
DiInt([top, right, bottom, left])	A tuple of four integers with directions.
Dimension([min, max, weight, preferred])	Specified dimension (width/height) of a user control or window.
DimensionTuple(min, max, preferred[, weight])	A hashable representation of a PTK Dimension.
DummyControl()	A dummy control object that doesn't paint any content.
FloatContainer(content, floats[, modal, ...])	A FloatContainer which uses :py`BoundedWritePosition`s.
FormattedTextControl([text, style, ...])	Control that displays formatted text.
HSplit(children[, window_too_small, align, ...])	Several layouts, one stacked above/under the other.
HorizontalAlign(*values)	Alignment for VSplit.
MouseEvent(position, event_type, button, ...)	Mouse event, sent to UIControl.mouse_handler.
MouseEventType(*values)
Point(x, y)
PtkDummyControl	alias of DummyControl
UIContent(get_line, StyleAndTextTuples] = >, ...)	Content generated by a user control.
VSplit(children[, window_too_small, align, ...])	Several layouts, one stacked left/right of the other.
VerticalAlign(*values)	Alignment for HSplit.
Window(*args, **kwargs)	Container that holds a control.
WindowAlign(*values)	Alignment of the Window content.
WindowRenderInfo(window, ui_content, ...)	Render information for the last render time of this control.
partial(func, /, *args, **keywords)	Create a new function with partial application of the given arguments and keywords.

class euporie.core.layout.containers.DimensionTuple(min: int, max: int, preferred: int, weight: int = 1)

Bases: NamedTuple

A hashable representation of a PTK Dimension.

This allows caching dimension calculations by making them hashable. Used internally by distribute_dimensions() for performance optimization.

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

max: int

Alias for field number 1

min: int

Alias for field number 0

preferred: int

Alias for field number 2

weight: int

Alias for field number 3

euporie.core.layout.containers.DummyContainer(width: int = 0, height: int = 0) → None

A minimal container with fixed dimensions.

This is a more efficient version of prompt_toolkit’s DummyContainer that: - Supports explicit width/height - Uses caching for better performance - Avoids unnecessary style calculations

class euporie.core.layout.containers.FloatContainer(content: AnyContainer, floats: list[Float], modal: bool = False, key_bindings: KeyBindingsBase | None = None, style: str | Callable[[], str] = '', z_index: int | None = None)

Bases: FloatContainer

A FloatContainer which uses :py`BoundedWritePosition`s.

get_children() → list[Container]

Return the list of child Container objects.

get_key_bindings() → KeyBindingsBase | None

Returns a KeyBindings object. These bindings become active when any user control in this container has the focus, except if any containers between this container and the focused user control is modal.

is_modal() → bool

When this container is modal, key bindings from parent containers are not taken into account if a user control in this container is focused.

preferred_height(width: int, max_available_height: int) → Dimension

Return the preferred height of the float container. (We don’t care about the height of the floats, they should always fit into the dimensions provided by the container.)

preferred_width(max_available_width: int) → Dimension

Return a Dimension that represents the desired width for this container.

reset() → None

Reset the state of this container and all the children. (E.g. reset scroll offsets, etc…)

write_to_screen(screen: Screen, mouse_handlers: MouseHandlers, write_position: WritePosition, parent_style: str, erase_bg: bool, z_index: int | None) → None

Write the actual content to the screen.

Parameters:

• screen – Screen

• mouse_handlers – MouseHandlers.

• parent_style – Style string to pass to the Window object. This will be applied to all content of the windows. VSplit and HSplit can use it to pass their style down to the windows that they contain.

• z_index – Used for propagating z_index from parent to child.

class euporie.core.layout.containers.HSplit(children: Sequence[AnyContainer], window_too_small: Container | None = None, align: VerticalAlign = VerticalAlign.JUSTIFY, padding: AnyDimension = 0, padding_char: str | None = None, padding_style: str = '', width: AnyDimension = None, height: AnyDimension = None, z_index: int | None = None, modal: bool = False, key_bindings: KeyBindingsBase | None = None, style: str | Callable[[], str] = '')

Bases: HSplit

Several layouts, one stacked above/under the other.

get_children() → list[Container]

Return the list of child Container objects.

get_key_bindings() → KeyBindingsBase | None

Returns a KeyBindings object. These bindings become active when any user control in this container has the focus, except if any containers between this container and the focused user control is modal.

is_modal() → bool

When this container is modal, key bindings from parent containers are not taken into account if a user control in this container is focused.

property pad_window: Window

Create a single instance of the padding window.

preferred_height(width: int, max_available_height: int) → Dimension

Return a Dimension that represents the desired height for this container.

preferred_width(max_available_width: int) → Dimension

Return a Dimension that represents the desired width for this container.

reset() → None

Reset the state of this container and all the children. (E.g. reset scroll offsets, etc…)

write_to_screen(screen: Screen, mouse_handlers: MouseHandlers, write_position: WritePosition, parent_style: str, erase_bg: bool, z_index: int | None) → None

Render the prompt to a Screen instance.

Parameters:

screen – The Screen class to which the output has to be written.

class euporie.core.layout.containers.VSplit(children: Sequence[AnyContainer], window_too_small: Container | None = None, align: HorizontalAlign = HorizontalAlign.JUSTIFY, padding: AnyDimension = 0, padding_char: str | None = None, padding_style: str = '', width: AnyDimension = None, height: AnyDimension = None, z_index: int | None = None, modal: bool = False, key_bindings: KeyBindingsBase | None = None, style: str | Callable[[], str] = '')

Bases: VSplit

Several layouts, one stacked left/right of the other.

get_children() → list[Container]

Return the list of child Container objects.

get_key_bindings() → KeyBindingsBase | None

Returns a KeyBindings object. These bindings become active when any user control in this container has the focus, except if any containers between this container and the focused user control is modal.

is_modal() → bool

When this container is modal, key bindings from parent containers are not taken into account if a user control in this container is focused.

property pad_window: Window

Create a single instance of the padding window.

preferred_height(width: int, max_available_height: int) → Dimension

Return a Dimension that represents the desired height for this container.

preferred_width(max_available_width: int) → Dimension

Return a Dimension that represents the desired width for this container.

reset() → None

Reset the state of this container and all the children. (E.g. reset scroll offsets, etc…)

write_to_screen(screen: Screen, mouse_handlers: MouseHandlers, write_position: WritePosition, parent_style: str, erase_bg: bool, z_index: int | None) → None

Render the prompt to a Screen instance.

Parameters:

screen – The Screen class to which the output has to be written.

class euporie.core.layout.containers.Window(*args: Any, **kwargs: Any)

Bases: Window

Container that holds a control.

get_children() → list[Container]

Return the list of child Container objects.

get_key_bindings() → KeyBindingsBase | None

Returns a KeyBindings object. These bindings become active when any user control in this container has the focus, except if any containers between this container and the focused user control is modal.

is_modal() → bool

When this container is modal, key bindings from parent containers are not taken into account if a user control in this container is focused.

preferred_height(width: int, max_available_height: int) → Dimension

Calculate the preferred height for this window.

preferred_width(max_available_width: int) → Dimension

Calculate the preferred width for this window.

reset() → None

Reset the state of this container and all the children. (E.g. reset scroll offsets, etc…)

write_to_screen(screen: Screen, mouse_handlers: MouseHandlers, write_position: WritePosition, parent_style: str, erase_bg: bool, z_index: int | None) → None

Write window to screen.

euporie.core.layout.containers.distribute_dimensions(size: int, dimensions: tuple[DimensionTuple, ...]) → list[int] | None

Return the heights/widths for all rows/columns, or None when there is not enough space.

This is a cached version of prompt_toolkit’s dimension distribution logic that improves performance by memoizing calculations based on the input dimensions.

Parameters:

• size – Total size to distribute

• dimensions – Tuple of DimensionTuple objects specifying min/max/preferred sizes

Returns:

List of distributed sizes or None if not enough space