Module

utils.ansi_width

ANSI-aware string width operations for Kida template engine.

ANSI escape sequences are zero-width but occupy bytes. Any padding, truncation, or wrapping must count visible characters, not raw string length. This module provides width-correct alternatives to str.ljust, str.rjust, str.center, and basic truncation/word-wrap.

All operations are pure Python with no dependencies outside stdlib.

1Class7Functions

Classes

WidthStrategy 2 ▼
Controls how ambiguous-width characters are measured.

Controls how ambiguous-width characters are measured.

Attributes

Name Type Description
ambiguous_width int

Width to assign East Asian Ambiguous ("A") characters and symbol characters above U+2000 with Neutral ("N") width. Use 1 for most Western terminals, 2 for CJK-locale terminals or terminals that render these symbols at double width.
_wcwidth_fn Any

Optionalwcwidth.wcwidthfunction. When set, this takes precedence over the heuristic for non-wide characters.

Functions

configure_width 2 WidthStrategy ▼
Configure the global character width measurement strategy. Called by ``_init_t…
def configure_width(ambiguous_width: int = 1, use_wcwidth: bool = True) -> WidthStrategy

Configure the global character width measurement strategy.

Called by_init_terminal_mode()during Environment setup. The resolved strategy is stored at module level and automatically used by all width functions (visible_len, ansi_ljust, padfilter, etc.).

Parameters
Name Type Description
ambiguous_width int

Width for ambiguous characters (1 or 2).

Default:1
use_wcwidth bool

If True, attempt to importwcwidthfor precise per-character widths. Falls back gracefully if not installed.

Default:True
Returns
WidthStrategy
visible_len 1 int ▼
Return the visible character count, ignoring ANSI escape sequences. Uses a pre…
def visible_len(s: str) -> int

Return the visible character count, ignoring ANSI escape sequences.

Uses a pre-compiled regex to strip all ANSI escapes before measuring.

Parameters
Name Type Description
s str

String potentially containing ANSI escape sequences.
Returns
int
ansi_ljust 3 str ▼
Left-justify (right-pad) to *width* visible characters. If the visible length …
def ansi_ljust(s: str, width: int, fillchar: str = ' ') -> str

Left-justify (right-pad) to width visible characters.

If the visible length already meets or exceeds width, return as-is.

Parameters
Name Type Description
s str

String potentially containing ANSI escape sequences.
width int

Target visible width.
fillchar str

Character used for padding (default space).

Default:' '
Returns
str
ansi_rjust 3 str ▼
Right-justify (left-pad) to *width* visible characters. If the visible length …
def ansi_rjust(s: str, width: int, fillchar: str = ' ') -> str

Right-justify (left-pad) to width visible characters.

If the visible length already meets or exceeds width, return as-is.

Parameters
Name Type Description
s str

String potentially containing ANSI escape sequences.
width int

Target visible width.
fillchar str

Character used for padding (default space).

Default:' '
Returns
str
ansi_center 3 str ▼
Center within *width* visible characters. If the visible length already meets …
def ansi_center(s: str, width: int, fillchar: str = ' ') -> str

Center within width visible characters.

If the visible length already meets or exceeds width, return as-is. When the padding is odd, the extra character goes on the right.

Parameters
Name Type Description
s str

String potentially containing ANSI escape sequences.
width int

Target visible width.
fillchar str

Character used for padding (default space).

Default:' '
Returns
str
ansi_truncate 3 str ▼
Truncate to *width* visible characters. Walks the string character by characte…
def ansi_truncate(s: str, width: int, suffix: str = '…') -> str

Truncate to width visible characters.

Walks the string character by character, tracking visible count while preserving ANSI sequences that appear before the cutoff point. If truncation occurs, appends suffix and a reset code (\033[0m) to close any open styles.

Parameters
Name Type Description
s str

String potentially containing ANSI escape sequences.
width int

Maximum visible width.
suffix str

String appended when truncation occurs (default ellipsis).

Default:'…'
Returns
str
ansi_wrap 2 str ▼
Word-wrap at *width* visible characters. Tracks active ANSI style state and re…
def ansi_wrap(s: str, width: int) -> str

Word-wrap at width visible characters.

Tracks active ANSI style state and re-applies it at the start of each new line after a break. Words are split on spaces. Lines already shorter than width are left as-is.

Parameters
Name Type Description
s str

String potentially containing ANSI escape sequences.
width int

Maximum visible width per line.
Returns
str