# terminal_escape

URL: /kida/api/utils/terminal_escape/
Section: utils
Description: 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.

---

> For a complete page index, fetch /kida/llms.txt.

Open LLM text
(/kida/api/utils/terminal_escape/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Fterminal_escape%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Fterminal_escape%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Fterminal_escape%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Fterminal_escape%2Findex.txt)

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 of`Markup`for 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 of`html_escape`for 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`