Module

environment.terminal

Terminal capabilities, color utilities, and rich error messages.

Provides:

  • TerminalCaps: Detected terminal capabilities (color, size, unicode)
  • _detect_terminal_caps(): Auto-detect capabilities from the environment
  • _make_hr_func(): Factory for hr()horizontal-rule template global
  • _init_terminal_mode(): Configure Environment for autoescape="terminal"
  • ANSI color codes with automatic TTY detection and NO_COLOR support
1Class18Functions

Classes

TerminalCaps 6 ▼
Detected terminal capabilities.

Detected terminal capabilities.

Attributes

Name Type Description
is_tty bool —
color str —
unicode bool —
width int —
height int —
ambiguous_width int —

Functions

_should_use_colors 0 bool ▼
Check if terminal supports colors and user allows them. **Respects:** - NO_COL…
def _should_use_colors() -> bool

Check if terminal supports colors and user allows them.

Respects:

  • NO_COLOR environment variable (https://no-color.org/)
  • FORCE_COLOR environment variable (overrides NO_COLOR)
  • sys.stdout.isatty() for TTY detection
Returns
bool
supports_color 0 bool ▼
Check if current terminal supports color output.
def supports_color() -> bool
Returns
bool
colorize 2 str ▼
Apply ANSI color codes to text.
def colorize(text: str, *colors: ColorName) -> str
Parameters
Name Type Description
text str

Text to colorize *colors: One or more color names to apply
*colors ColorName
Returns
str
strip_colors 1 str ▼
Remove ANSI color codes from text.
def strip_colors(text: str) -> str
Parameters
Name Type Description
text str

Text potentially containing ANSI codes
Returns
str
error_code 1 str ▼
Color text as an error code (bright red + bold).
def error_code(text: str) -> str
Parameters
Name Type Description
text str
Returns
str
location 1 str ▼
Color text as a file location (cyan).
def location(text: str) -> str
Parameters
Name Type Description
text str
Returns
str
line_number 1 str ▼
Color text as a line number (yellow).
def line_number(text: str) -> str
Parameters
Name Type Description
text str
Returns
str
error_line 1 str ▼
Color text as an error line (bright red).
def error_line(text: str) -> str
Parameters
Name Type Description
text str
Returns
str
hint 1 str ▼
Color text as a hint/suggestion (green).
def hint(text: str) -> str
Parameters
Name Type Description
text str
Returns
str
suggestion 1 str ▼
Color text as a 'Did you mean?' suggestion (bright_green + bold).
def suggestion(text: str) -> str
Parameters
Name Type Description
text str
Returns
str
dim_text 1 str ▼
Color text as dimmed/secondary (dim).
def dim_text(text: str) -> str
Parameters
Name Type Description
text str
Returns
str
docs_url 1 str ▼
Color text as a documentation URL (bright_blue).
def docs_url(text: str) -> str
Parameters
Name Type Description
text str
Returns
str
format_error_header 2 str ▼
Format error header with optional code.
def format_error_header(code: str | None, message: str) -> str
Parameters
Name Type Description
code str | None

Optional error code (e.g., "K-RUN-001")
message str

Error message
Returns
str
format_source_line 4 str ▼
Format a source line with colors.
def format_source_line(lineno: int, content: str, is_error: bool = False, show_marker: bool = True) -> str
Parameters
Name Type Description
lineno int

Line number
content str

Line content
is_error bool

True if this is the error line

Default:False
show_marker bool

True to show '>' marker for error line

Default:True
Returns
str
_detect_terminal_caps 0 TerminalCaps ▼
Detect terminal capabilities from the environment.
def _detect_terminal_caps() -> TerminalCaps
Returns
TerminalCaps
_make_hr_func 2 Callable ▼
Create an ``hr()`` function for terminal templates.
def _make_hr_func(width: int, unicode: bool) -> Callable
Parameters
Name Type Description
width int
unicode bool
Returns
Callable
_resolve_ambiguous_width 2 int ▼
Resolve the ambiguous character width using a fallback chain. Resolution order…
def _resolve_ambiguous_width(explicit: int | None, is_tty: bool) -> int

Resolve the ambiguous character width using a fallback chain.

Resolution order:

  1. Explicit user override (Environment(ambiguous_width=2))
  2. Terminal probe (queries the actual terminal for rendered width)
  3. wcwidthlibrary (if installed)
  4. Locale heuristic (CJK locale → 2)
  5. Default: 1
Parameters
Name Type Description
explicit int | None
is_tty bool
Returns
int
_init_terminal_mode 5 TerminalCaps ▼
Configure Environment for ``autoescape="terminal"`` mode. Detects terminal cap…
def _init_terminal_mode(env: Any, terminal_color: str | None, terminal_width: int | None, terminal_unicode: bool | None, ambiguous_width: int | None = None) -> TerminalCaps

Configure Environment forautoescape="terminal"mode.

Detects terminal capabilities, applies user overrides, registers terminal-specific filters and globals. Returns the resolved TerminalCapsso the caller can store it.

Parameters
Name Type Description
env Any
terminal_color str | None
terminal_width int | None
terminal_unicode bool | None
ambiguous_width int | None Default:None
Returns
TerminalCaps