ANSI API Reference¶

def fg(color: str | int | tuple[int, int, int]) -> str:
    """Return an ANSI escape for the given foreground color.

    Args:
        color: A color name (``"red"``, ``"bright_cyan"``), hex string
            (``"#ff8800"``), 256-color index (``0``–``255``), or RGB
            tuple (``(255, 136, 0)``).

    Returns:
        An ANSI escape string.

    Example::

        print(fg("red") + "error" + RESET)
        print(fg("#00ff00") + "green" + RESET)
        print(fg(214) + "orange" + RESET)
        print(fg((100, 200, 50)) + "custom" + RESET)
    """
    return _parse_color(color, 38)

def bg(color: str | int | tuple[int, int, int]) -> str:
    """Return an ANSI escape for the given background color.

    Args:
        color: Same formats as :func:`fg`.

    Returns:
        An ANSI escape string.
    """
    return _parse_color(color, 48)

def style(
    text: str,
    *,
    fg: str | int | tuple[int, int, int] | None = None,  # noqa: A002
    bg: str | int | tuple[int, int, int] | None = None,  # noqa: A002
    bold: bool = False,
    dim: bool = False,
    italic: bool = False,
    underline: bool = False,
    strikethrough: bool = False,
    reverse: bool = False,
    reset: bool = True,
) -> str:
    """Wrap *text* with ANSI escape codes.

    Args:
        text: The string to style.
        fg: Foreground color (name, hex, 256-index, or RGB tuple).
        bg: Background color (same formats as *fg*).
        bold: Apply bold weight.
        dim: Apply dim/faint rendering.
        italic: Apply italic style.
        underline: Apply underline decoration.
        strikethrough: Apply strikethrough decoration.
        reverse: Swap foreground and background.
        reset: Append a ``RESET`` sequence after *text* (default ``True``).

    Returns:
        The styled string.

    Example::

        style("Error!", fg="red", bold=True)
        style("note", fg="cyan", italic=True)
        style("warn", fg="yellow", bg="black", underline=True)
    """
    parts: list[str] = []
    if bold:
        parts.append(BOLD)
    if dim:
        parts.append(DIM)
    if italic:
        parts.append(ITALIC)
    if underline:
        parts.append(UNDERLINE)
    if strikethrough:
        parts.append(STRIKETHROUGH)
    if reverse:
        parts.append(REVERSE)
    if fg is not None:
        parts.append(_parse_color(fg, 38))
    if bg is not None:
        parts.append(_parse_color(bg, 48))

    if not parts:
        return text

    prefix = "".join(parts)
    suffix = RESET if reset else ""
    return f"{prefix}{text}{suffix}"

def supports_color(stream: Any = None) -> bool:
    """Check if the output stream supports ANSI color codes.

    Respects the ``NO_COLOR`` environment variable
    (see `<https://no-color.org/>`_) and the ``FORCE_COLOR`` variable.

    Args:
        stream: The output stream to check.  Defaults to ``sys.stderr``.

    Returns:
        True if the stream is a color-capable terminal.
    """
    if os.environ.get("FORCE_COLOR"):
        return True
    if os.environ.get("NO_COLOR"):
        return False
    s = stream or sys.stderr
    if not hasattr(s, "isatty") or not s.isatty():
        return False
    if os.environ.get("TERM", "") == "dumb":
        return False
    return True

def color_depth(stream: Any = None) -> int:
    """Detect the color depth of the terminal.

    Args:
        stream: The output stream to check.  Defaults to ``sys.stderr``.

    Returns:
        - ``0`` — no color support
        - ``16`` — standard 16 colors
        - ``256`` — 256 color palette
        - ``16777216`` — 24-bit true color
    """
    if not supports_color(stream):
        return 0

    colorterm = os.environ.get("COLORTERM", "").lower()
    if _TRUECOLOR_RE.search(colorterm):
        return 16_777_216

    term = os.environ.get("TERM", "")
    if "256color" in term:
        return 256

    # Most modern terminals support at least 16 colors.
    return 16

def strip_ansi(text: str) -> str:
    """Remove all ANSI escape sequences from *text*.

    Args:
        text: A string potentially containing ANSI escapes.

    Returns:
        The plain text without escape sequences.

    Example::

        strip_ansi("\\033[1m\\033[31mhello\\033[0m")  # "hello"
    """
    return _ANSI_ESCAPE_RE.sub("", text)

def visible_len(text: str) -> int:
    """Return the visible character count of *text*, ignoring ANSI escapes.

    Useful for aligning columns when text contains color codes.

    Args:
        text: A string potentially containing ANSI escapes.

    Returns:
        The number of visible characters.
    """
    return len(strip_ansi(text))

def cursor_move(n: int = 1, direction: str = "up") -> str:
    """Return an ANSI escape to move the cursor.

    Args:
        n: Number of positions to move.
        direction: One of ``"up"``, ``"down"``, ``"forward"``, ``"back"``.

    Returns:
        An ANSI escape string.

    Raises:
        ValueError: If *direction* is not recognised.
    """
    codes = {"up": "A", "down": "B", "forward": "C", "back": "D"}
    if direction not in codes:
        raise ValueError(f"Unknown direction: {direction!r}. Valid: {', '.join(codes)}")
    return f"\033[{n}{codes[direction]}"