Module

utils.terminal_escape

Terminal ANSI escape utilities for Kida template engine.

Provides ANSI sanitization and the Styled safe-string class for terminal mode. Analogous to html.py's html_escape/Markup but for terminal output.

Security:

  • Strips dangerous ANSI sequences (cursor movement, screen manipulation, OSC, device control, bracketed paste) from untrusted input
  • Preserves safe SGR (styling) sequences: colors, bold, underline, etc.
  • Fast path: strings without ESC byte are returned immediately

All operations are O(n) single-pass with no ReDoS risk.

1Class1Function

Classes

Styled 10 ▼
A string subclass marking content as already styled with ANSI codes. The Styled class implements t…

A string subclass marking content as already styled with ANSI codes.

The Styled class implements the__terminal__protocol used by the template engine to identify pre-sanitized terminal content. When combined with regular strings via operators like+, the non-Styled strings are automatically sanitized.

This is the terminal-mode analogue ofMarkupfor HTML mode.

Methods

format 2 Self ▼
Format string, sanitizing non-Styled arguments.
def format(self, *args: Any, **kwargs: Any) -> Self
Parameters
Name Type Description
*args —
**kwargs —
Returns
Self
join 1 Self ▼
Join sequence, sanitizing non-Styled elements.
def join(self, seq: Iterable[str]) -> Self
Parameters
Name Type Description
seq —
Returns
Self
Internal Methods 8 ▼
__new__ 1 Self ▼
Create a Styled string.
def __new__(cls, value: Any = '') -> Self
Parameters
Name Type Description
value —

Content to mark as safe. If it has a__terminal__()method, that method is called to get the string value.

Default:''
Returns
Self Styled instance containing the safe content.
__terminal__ 0 Self ▼
Return self -- already safe content. This method is the ``__terminal__`` proto…
def __terminal__(self) -> Self

Return self -- already safe content.

This method is the__terminal__protocol that the template engine uses to detect pre-sanitized terminal content.

Returns
Self
__repr__ 0 str ▼
def __repr__(self) -> str
Returns
str
__add__ 1 Self ▼
Concatenate, sanitizing ``other`` if not Styled.
def __add__(self, other: str) -> Self
Parameters
Name Type Description
other —
Returns
Self
__radd__ 1 Self ▼
Reverse concatenate, sanitizing ``other`` if not Styled.
def __radd__(self, other: str) -> Self
Parameters
Name Type Description
other —
Returns
Self
__mul__ 1 Self ▼
Repeat string n times.
def __mul__(self, n: SupportsIndex) -> Self
Parameters
Name Type Description
n —
Returns
Self
__mod__ 1 Self ▼
Format string with %-style, sanitizing non-Styled args.
def __mod__(self, args: Any) -> Self
Parameters
Name Type Description
args —
Returns
Self
__format__ 1 Self ▼
Support format() built-in, preserving Styled type.
def __format__(self, format_spec: str) -> Self
Parameters
Name Type Description
format_spec —
Returns
Self

Functions

ansi_sanitize 1 str ▼
Strip dangerous ANSI sequences from untrusted input. Preserves safe SGR (styli…
def ansi_sanitize(value: Any) -> str

Strip dangerous ANSI sequences from untrusted input.

Preserves safe SGR (styling) sequences while stripping cursor movement, screen manipulation, OSC, device control, and other dangerous escapes.

This is the terminal-mode analogue ofhtml_escapefor HTML mode.

Complexity: O(n) single pass. Returns immediately if no ESC byte present.

Parameters
Name Type Description
value Any

Value to sanitize (will be converted to string).
Returns
str