# ansi_width URL: /kida/api/utils/ansi_width/ Section: utils Description: 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. --- > For a complete page index, fetch /kida/llms.txt. Open LLM text (/kida/api/utils/ansi_width/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Fansi_width%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Fansi_width%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Fansi_width%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Fansi_width%2Findex.txt) 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` Optional`wcwidth.wcwidth`function. 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`, `pad`filter, etc.). ##### Parameters Name Type Description `ambiguous_width` `int` Width for ambiguous characters (1 or 2). Default:`1` `use_wcwidth` `bool` If True, attempt to import`wcwidth`for 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`