Implementation:Iterative Dvc Ui Console

Knowledge Sources	Iterative_Dvc
Domains	User_Interface, CLI
Last Updated	2026-02-10 10:00 GMT

Overview

Concrete tool for console output with styled text, tables, JSON rendering, progress bars, and user prompts. The module defines the Formatter class for applying color/style themes, the Console class as the primary UI interface, and a global singleton ui instance used throughout the DVC codebase.

Source: dvc/ui/__init__.py (377 lines)

Signature

class Formatter:
    def __init__(self, theme: Optional[dict] = None, defaults: Optional[dict] = None) -> None: ...
    def format(self, message: str, style: Optional[str] = None, **kwargs) -> str: ...

class Console:
    def __init__(self, formatter: Optional[Formatter] = None, enable: bool = False) -> None: ...
    def enable(self) -> None: ...
    def success(self, message: str) -> None: ...
    def error(self, message: str) -> None: ...
    def warn(self, message: str) -> None: ...
    def error_write(self, *objects, style=None, sep=None, end=None, styled=False, force=True) -> None: ...
    def write_json(self, data, indent=None, highlight=None, stderr=False, ...) -> None: ...
    def rich_print(self, *objects, sep=" ", end="\n", stderr=False, style=None, ...) -> None: ...
    def write(self, *objects, style=None, sep=None, end=None, stderr=False, force=False, styled=False, file=None) -> None: ...
    def progress(*args, **kwargs) -> "Tqdm": ...
    def pager(self, styles: bool = True) -> Iterator[None]: ...
    def prompt(self, text: str, choices=None, password=False) -> Optional[str]: ...
    def confirm(self, statement: str) -> bool: ...
    def table(self, data, headers=None, markdown=False, rich_table=False, ...) -> None: ...
    def status(self, status: str, **kwargs) -> "Status": ...
    def isatty() -> bool: ...
    def open_browser(self, file) -> int: ...

ui = Console()

Import

from dvc.ui import ui

Description

The Console class provides a unified interface for all DVC user-facing output. It wraps Python's built-in print() and the Rich library's console capabilities behind a consistent API. Output is gated by an _enabled flag (or a force parameter) to allow silent operation when DVC is used as a library.

Output Methods

Method	Description
`write(*objects, style, sep, end, stderr, force, styled, file)`	Primary output method. Formats objects using `Formatter` and prints to stdout or stderr. When `styled=True` or inside a pager context, delegates to `rich_print()`. Wraps output in `Tqdm.external_write_mode()` to avoid conflicts with progress bars.
`success(message)`	Writes a message with the `"success"` style (green, bold)
`error(message)`	Writes a message to stderr with the `"error"` style (red, bold)
`warn(message)`	Writes a message to stderr with the `"warn"` style (yellow)
`error_write(*objects, ...)`	Delegates to `write()` with `stderr=True` and `force=True`
`write_json(data, indent, highlight, ...)`	Renders JSON data using `rich.json.JSON`. Auto-detects TTY for indentation and syntax highlighting. Disables colorama when highlighting is off to prevent ANSI stripping.
`rich_print(*objects, ...)`	Directly prints via Rich's `Console.print()` with full styling support

Interactive Methods

Method	Description
`prompt(text, choices, password)`	Prompts for user input via `rich_console.input()`. If `choices` is provided, loops until the user enters a valid choice. Returns `None` on `EOFError`.
`confirm(statement)`	Asks a yes/no question using `prompt()`. Returns `True` if the answer starts with `"y"`.

Data Display Methods

Method	Description
`table(data, headers, markdown, rich_table, ...)`	Renders tabular data. Supports plain text tables (via `tabulate`), Rich tables, and Markdown-formatted tables. Delegates to `dvc.ui.table.rich_table()` or `dvc.ui.table.plain_table()`.
`progress(args, *kwargs)`	Static method returning a `Tqdm` progress bar instance
`pager(styles)`	Context manager that redirects Rich console output through a pager (`DvcPager`) for paginated display
`status(status, **kwargs)`	Returns a Rich `Status` spinner on the error console

Utility Methods

Method	Description
`isatty()`	Static method checking if stdout is a TTY via `dvc.utils.isatty()`
`open_browser(file)`	Opens a file in the default web browser. On WSL, uses a relative path; otherwise uses a `file://` URI. Returns 0 on success, 1 on failure.

I/O

write(): Outputs to stdout or stderr with optional styling via the Formatter
table(): Renders tabular data to stdout with optional markdown or Rich formatting
prompt(): Reads from stdin via Rich console input; returns user response as a lowercase string
write_json(): Renders structured data as formatted JSON to stdout or stderr

Formatter Class

The Formatter class applies color and style themes to messages using dvc.utils.colorize(). The default theme defines three styles:

theme = {
    "success": {"color": "green", "style": "bold"},
    "warn": {"color": "yellow"},
    "error": {"color": "red", "style": "bold"},
}

Context Manager: disable_colorama

@contextmanager
def disable_colorama():
    """Temporarily deinitialize colorama, flushing stdout/stderr on exit."""

Used by write_json() when syntax highlighting is disabled, to prevent colorama from stripping ANSI codes from Rich's plain-text JSON output.

Dependencies

Dependency	Usage
`colorama`	ANSI color support on Windows; temporarily disabled during non-highlighted JSON output
`rich.console.Console`	Underlying Rich console for styled output, input, and pager support
`rich.json.JSON`	JSON rendering with syntax highlighting
`dvc.progress.Tqdm`	Progress bar integration and external write mode
`dvc.utils.colorize`	Colorama-based message formatting
`dvc.utils.objects.cached_property`	Lazy initialization of Rich console instances
`dvc.ui.table`	Table rendering (plain and Rich)
`dvc.ui.pager.DvcPager`	Custom pager for paginated output

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment