ddp_utils.console.terminal

import ddp_utils.console.terminal

Detect terminal capabilities without mutating process-wide streams.

The console renderer uses capability detection rather than operating-system version checks. Windows Server 2012 R2 can therefore use the classic Win32 console path, while modern terminals use VT sequences and redirected output uses a stable plain-text path.

Examples

Select the safest renderer for the current standard streams:

capabilities = detect_terminal_capabilities()
print(capabilities.mode.value)

class ddp_utils.console.terminal.TerminalCapabilities(mode: TerminalMode, interactive: bool, color: bool, unicode: bool, cursor_addressing: bool, reason: str)

Bases: object

Describe the effective terminal behavior selected for one stream.

Parameters

Name	Type	Description
mode	TerminalMode	Effective rendering mode after auto-detection.
interactive	bool	Whether the output stream is an interactive terminal.
color	bool	Whether styled color output is safe.
unicode	bool	Whether Unicode animation and drawing characters are safe.
cursor_addressing	bool	Whether existing screen rows can be rewritten.
reason	str	Human-readable reason for the selected mode.

Examples

Disable animation when cursor addressing is unavailable:

if not capabilities.cursor_addressing:
    render_plain_status()

class ddp_utils.console.terminal.TerminalMode(value)

Bases: str, Enum

Identify the terminal control strategy used by Console.

VT uses ANSI/VT sequences, WIN32 uses the classic Windows console API, and PLAIN never moves the cursor.

Examples

Request automatic capability detection:

mode = TerminalMode.AUTO

ddp_utils.console.terminal.detect_terminal_capabilities(stream: TextIO | None = None, requested: TerminalMode | str = TerminalMode.AUTO) → TerminalCapabilities

Select a safe terminal renderer for one output stream.

Parameters

Name	Type	Description
stream	TextIO | None	Destination stream. Defaults to sys.stdout.
requested	TerminalMode | str	auto, vt, win32, or plain. An explicitly requested unsafe dynamic mode degrades to plain.

Returns

Type	Description
TerminalCapabilities	Immutable capability description used by the console renderer.

Raises

Exception	Description
ValueError	requested is not a supported terminal mode.

Examples

Detect capabilities without changing global stream configuration:

caps = detect_terminal_capabilities(requested="auto")