terminal.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/core/terminal.py
 
"""
Purpose
-------
Provide shared terminal color support for OCT CLI output.
 
Responsibilities
----------------
- Detect ANSI escape code support (including Windows VT mode).
- Export color constants used by linter, health, and formatter modules.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 - (none) detection runs at import, before diagnostics are active
    L3 - (none) the colour constants are resolved at import
    L4 - (none) the Windows VT probe likewise runs at import
 
Contracts
---------
- Color constants are empty strings when ANSI is not supported.
- Safe to import at module level; no side effects beyond detection.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger; imported but never called, as detection runs at import before init)
"""
 
# OCT-LINT: disable-file=dbg_usage reason="Plan 263: both functions run at module level to resolve the colour constants, so any _dbg call here fires before init() and adds a RuntimeWarning to every oct invocation"
 
import os
import sys
from typing import TextIO
from oct.core.diagnostics import _dbg
 
 
def supports_ansi() -> bool:
    """Return True if the terminal supports ANSI escape codes."""
    return supports_ansi_on(sys.stdout)
 
 
def supports_ansi_on(stream: TextIO) -> bool:
    """Return True if *stream* supports ANSI escape codes."""
    if not hasattr(stream, "isatty") or not stream.isatty():
        return False
    if os.name != "nt":
        return True
    # Windows 10 1511+ supports ANSI if VT mode is enabled
    try:
        import ctypes
        kernel32 = ctypes.windll.kernel32
        # Map stream to the correct console handle
        if stream is sys.stderr:
            handle = kernel32.GetStdHandle(-12)  # STD_ERROR_HANDLE
        else:
            handle = kernel32.GetStdHandle(-11)  # STD_OUTPUT_HANDLE
        mode = ctypes.c_ulong()
        kernel32.GetConsoleMode(handle, ctypes.byref(mode))
        # ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004
        return bool(mode.value & 0x0004)
    except Exception:
        return False
 
 
if supports_ansi():
    CYAN = "\033[96m"
    GREEN = "\033[92m"
    RED = "\033[91m"
    YELLOW = "\033[93m"
    RESET = "\033[0m"
else:
    CYAN = GREEN = RED = YELLOW = RESET = ""