Advanced Topics

Relevant source files

• CHANGELOG.md
• CONTRIBUTORS.md
• docs/source/console.rst
• poetry.lock
• pyproject.toml
• rich/console.py
• tests/test_console.py

This section covers advanced Rich features that extend beyond basic rendering and require deeper understanding of Rich's architecture. These topics are relevant for:

• Building custom renderables with complex layout requirements
• Integrating Rich into applications across different platforms
• Customizing Rich's appearance and behavior
• Capturing and exporting Rich output in various formats

For detailed information, see the child pages:

• 7.1 Measurement and Layout — The Measurement system and ratio-based column width calculation
• 7.2 Themes and Customization — Theme, ThemeStack, DEFAULT_STYLES, and RegexHighlighter
• 7.3 Platform Support — Legacy Windows console, Jupyter notebook rendering, Unicode cell-width tables
• 7.4 Export and Capture — record=True, capture(), export_text/html/svg, and format templates

Advanced Features Overview

Advanced features landscape — key modules and code entities

Sources: rich/measure.py rich/theme.py rich/themes.py rich/highlighter.py rich/_windows.py rich/_win32_console.py rich/_windows_renderer.py rich/cells.py rich/console.py rich/_export_format.py rich/terminal_theme.py

Measurement and Layout

Rich uses a Measurement NamedTuple (defined in rich/measure.py) to calculate the minimum and maximum width that a renderable requires. This feeds into column width distribution for Table, Columns, and Layout.

Key entities:

Symbol	Role
Measurement	NamedTuple with minimum and maximum int fields
Measurement.get()	Class method that queries a renderable's __rich_measure__
measure_renderables()	Aggregates measurements across a list of renderables
Constrain	Wraps a renderable to enforce a maximum width
ratio_resolve()	Resolves ratio-based column widths given available space
ratio_distribute()	Distributes remaining space across ratio-based columns

See page 7.1 for full documentation.

Sources: rich/measure.py rich/console.py475-487

Themes and Customization

Rich's style system is theme-based. Each Console instance holds a ThemeStack (in rich/theme.py) that resolves named styles like "bold", "repr.brace", or "logging.level.info" at render time.

Key entities:

Symbol	Location	Role
Theme	rich/theme.py	Maps style names to Style objects; can be loaded from .ini files
ThemeStack	rich/theme.py	Stack of Theme objects; top theme takes precedence
DEFAULT_STYLES	rich/themes.py	Default namespace covering repr.*, json.*, logging.*, progress.*, etc.
RegexHighlighter	rich/highlighter.py	Base class for creating pattern-based text highlighters
ReprHighlighter	rich/highlighter.py	Default highlighter for Python repr output

Themes can be applied temporarily using Console.use_theme() (a context manager backed by ThemeContext in rich/console.py).

See page 7.2 for full documentation.

Sources: rich/theme.py rich/themes.py rich/highlighter.py rich/console.py349-368

Now let me replace the Windows Support section with a more concise version:

Now let me update the rest. Let me write complete replacement sections:

<old_str>

Windows Support

Rich provides specialized support for Windows terminals, which historically have different capabilities from Unix-like terminals.

Windows Terminal Feature Detection

When running on Windows, Rich automatically detects the terminal's capabilities to determine the optimal rendering approach.

Sources: rich/_windows.py15-61

Rich checks if the Windows terminal supports Virtual Terminal (VT) processing by querying the console mode using the Windows API. If VT processing is enabled, Rich can use ANSI escape sequences for formatting. For newer Windows versions (Windows 10 build 15063 or later with VT support), Rich also enables truecolor support.

The detection logic is implemented in the get_windows_console_features() function, which returns a WindowsConsoleFeatures object containing information about VT and truecolor support.

Legacy Windows Console API

For older Windows environments without VT support, Rich falls back to using the Windows Console API directly through the LegacyWindowsTerm class.

Sources: rich/_win32_console.py29-572 rich/_windows_renderer.py1-56

The LegacyWindowsTerm class provides methods for terminal manipulation using the Windows Console API. It handles:

• Text styling (colors and attributes)
• Cursor movement and positioning
• Line erasure
• Cursor visibility
• Window title setting

This class is used when ANSI escape sequences are not supported, ensuring Rich works even on older Windows systems.

Windows Rendering Pipeline

When legacy rendering is required, Rich uses a specialized rendering pipeline to translate its segment-based model to Windows Console API calls.

Sources: rich/_windows_renderer.py7-56

The legacy_windows_render function in _windows_renderer.py processes Rich's segments and translates them to appropriate Windows Console API calls:

1. Text segments with styles are rendered using write_styled()
2. Plain text segments are rendered using write_text()
3. Control segments (cursor movement, line erasure, etc.) are mapped to corresponding API calls

This ensures a consistent user experience across different Windows environments.

Jupyter Integration

Rich provides seamless integration with Jupyter notebooks, allowing you to use Rich's formatting capabilities in notebook cells.

Jupyter Environment Detection

Rich automatically detects when it's running in a Jupyter environment and adjusts its behavior accordingly.

Sources: tests/test_jupyter.py1-32

When running in a Jupyter environment, Rich:

1. Sets the console width to 115 columns (unless overridden)
2. Sets the console height to 100 lines (unless overridden)
3. Enables truecolor support for rich color rendering

These defaults can be customized through:

• The JUPYTER_COLUMNS environment variable to set the width
• The JUPYTER_LINES environment variable to set the height
• Explicit width and height parameters to the Console constructor

Jupyter Output Rendering

In Jupyter notebooks, Rich renders its output as HTML, allowing for rich formatting that matches what you would see in a terminal.

Feature	Jupyter Support	Notes
Colors	Full support	Truecolor (16M colors)
Styles	Full support	Bold, italic, underline, etc.
Tables	Full support	Rendered as HTML tables
Markdown	Full support	Rendered as styled HTML
Progress bars	Limited support	Static representation
Live displays	Limited support	Final state only

Rich's Jupyter integration provides a consistent experience between terminal and notebook environments, making it ideal for data exploration and documentation.

Extension and Customization

Rich is designed to be extensible, allowing you to create custom renderables and extend existing components.

Creating Custom Renderables

The core of Rich's extensibility is the renderable protocol, which allows any object to be rendered by implementing specific methods.

To make an object renderable by Rich, you have two options:

1. Implement __rich__() to return an existing renderable
2. Implement __rich_console__() and __rich_measure__() for direct rendering

The __rich_console__ method generates segments for rendering, while __rich_measure__ provides sizing information for layout calculations.

Extending Rich Components

You can extend Rich's existing components to customize their behavior while retaining core functionality.

Common extension patterns include:

1. Subclassing and overriding methods to modify behavior
2. Creating custom column types for tables and progress bars
3. Implementing specialized rendering logic for specific data types

For example, you might extend the Table class to automatically format financial data, or extend the Progress class to display application-specific metrics.

Platform-Specific Considerations

When using Rich across different platforms, there are several considerations to keep in mind.

Windows-Specific Issues

Windows terminals have evolved significantly but still have some platform-specific behaviors:

1. Legacy Windows consoles (Windows 7 or older Windows 10) use the fallback rendering mechanism
2. Windows Terminal (modern) supports all Rich features including truecolor
3. When redirecting output to files on Windows, Rich automatically disables colored output

Jupyter-Specific Features

When using Rich in Jupyter:

1. Console dimensions respond to JUPYTER_COLUMNS and JUPYTER_LINES environment variables
2. The force_jupyter=True parameter can be used to force Jupyter rendering mode
3. Complex live displays like progress bars are rendered as static representations

Cross-Platform Best Practices

For maximum compatibility across platforms:

1. Use Rich's automatic terminal detection rather than forcing specific features
2. Test on multiple platforms when developing custom renderables
3. Consider using the Console.is_terminal property to detect when output is being redirected
4. Provide graceful fallbacks for advanced features when working with legacy terminals

By understanding these platform-specific considerations, you can create Rich applications that work consistently across environments.

Sources: rich/_windows.py15-61 rich/_win32_console.py1-662 tests/test_jupyter.py1-32 <new_str>

Platform Support

Rich handles rendering differences across Windows legacy consoles, modern terminals, and Jupyter notebooks. The key detection and dispatch logic lives in rich/console.py, rich/_windows.py, rich/_win32_console.py, and rich/_windows_renderer.py.

Platform detection and rendering dispatch

Sources: rich/console.py582-688 rich/_windows.py15-61 rich/_win32_console.py29-572 rich/_windows_renderer.py1-56

Windows

detect_legacy_windows() in rich/console.py calls get_windows_console_features() from rich/_windows.py. That function returns a WindowsConsoleFeatures dataclass with .vt (Virtual Terminal processing available) and .truecolor fields.

When .vt is False, the Console sets legacy_windows=True and the output path uses legacy_windows_render() from rich/_windows_renderer.py, which translates Segment objects into LegacyWindowsTerm API calls rather than ANSI escape sequences.

Jupyter

_is_jupyter() in rich/console.py detects Google Colab, Databricks, and ZMQInteractiveShell environments. When Jupyter mode is active:

• Default width is JUPYTER_DEFAULT_COLUMNS (115) unless JUPYTER_COLUMNS env var is set
• Default height is JUPYTER_DEFAULT_LINES (100) unless JUPYTER_LINES env var is set
• Color system is forced to ColorSystem.TRUECOLOR

Feature	Jupyter Support	Notes
Colors	Full (truecolor)	16M colors
Styles	Full	Bold, italic, underline, etc.
Tables	Full	Rendered as HTML
Markdown	Full	Rendered as styled HTML
Progress bars	Limited	Static representation
Live displays	Limited	Final state only

See page 7.3 for full documentation of platform support.

Sources: rich/console.py511-528 rich/console.py663-688

Export and Capture

When record=True is set on the Console constructor, Rich accumulates a copy of all rendered Segment objects in _record_buffer. This data can then be exported in three formats.

Export and capture code path

Sources: rich/console.py316-346 rich/_export_format.py rich/terminal_theme.py

Capture context manager

Console.capture() returns a Capture context manager (defined in rich/console.py). Inside the with block, output is diverted to an internal buffer. After the block exits, Capture.get() returns the captured string.

Recording and export methods

Method	Output format	Notes
export_text()	Plain text	Strips all ANSI/styles
export_html()	HTML document	Uses CONSOLE_HTML_FORMAT template
export_svg()	SVG document	Uses CONSOLE_SVG_FORMAT template; accepts TerminalTheme
save_text(path)	Plain text file	Writes export_text() result
save_html(path)	HTML file	Writes export_html() result
save_svg(path)	SVG file	Writes export_svg() result

SVG export accepts a theme parameter using one of the TerminalTheme presets from rich/terminal_theme.py (e.g., MONOKAI, DEFAULT_TERMINAL_THEME, SVG_EXPORT_THEME).

See page 7.4 for full documentation of export and capture.

Sources: rich/console.py316-346 rich/console.py1680-1800 rich/_export_format.py rich/terminal_theme.py

Windows Support

Rich provides specialized support for Windows terminals, which historically have different capabilities from Unix-like terminals.

Windows Terminal Feature Detection

When running on Windows, Rich automatically detects the terminal's capabilities to determine the optimal rendering approach.

Sources: rich/_windows.py15-61

Rich checks if the Windows terminal supports Virtual Terminal (VT) processing by querying the console mode using the Windows API. If VT processing is enabled, Rich can use ANSI escape sequences for formatting. For newer Windows versions (Windows 10 build 15063 or later with VT support), Rich also enables truecolor support.

The detection logic is implemented in the get_windows_console_features() function, which returns a WindowsConsoleFeatures object containing information about VT and truecolor support.

Legacy Windows Console API

For older Windows environments without VT support, Rich falls back to using the Windows Console API directly through the LegacyWindowsTerm class.

Sources: rich/_win32_console.py29-572 rich/_windows_renderer.py1-56

The LegacyWindowsTerm class provides methods for terminal manipulation using the Windows Console API. It handles:

• Text styling (colors and attributes)
• Cursor movement and positioning
• Line erasure
• Cursor visibility
• Window title setting

This class is used when ANSI escape sequences are not supported, ensuring Rich works even on older Windows systems.

Windows Rendering Pipeline

When legacy rendering is required, Rich uses a specialized rendering pipeline to translate its segment-based model to Windows Console API calls.

Sources: rich/_windows_renderer.py7-56

The legacy_windows_render function in _windows_renderer.py processes Rich's segments and translates them to appropriate Windows Console API calls:

1. Text segments with styles are rendered using write_styled()
2. Plain text segments are rendered using write_text()
3. Control segments (cursor movement, line erasure, etc.) are mapped to corresponding API calls

This ensures a consistent user experience across different Windows environments.

Jupyter Integration

Rich provides seamless integration with Jupyter notebooks, allowing you to use Rich's formatting capabilities in notebook cells.

Jupyter Environment Detection

Rich automatically detects when it's running in a Jupyter environment and adjusts its behavior accordingly.

Sources: tests/test_jupyter.py1-32

When running in a Jupyter environment, Rich:

1. Sets the console width to 115 columns (unless overridden)
2. Sets the console height to 100 lines (unless overridden)
3. Enables truecolor support for rich color rendering

These defaults can be customized through:

• The JUPYTER_COLUMNS environment variable to set the width
• The JUPYTER_LINES environment variable to set the height
• Explicit width and height parameters to the Console constructor

Jupyter Output Rendering

In Jupyter notebooks, Rich renders its output as HTML, allowing for rich formatting that matches what you would see in a terminal.

Feature	Jupyter Support	Notes
Colors	Full support	Truecolor (16M colors)
Styles	Full support	Bold, italic, underline, etc.
Tables	Full support	Rendered as HTML tables
Markdown	Full support	Rendered as styled HTML
Progress bars	Limited support	Static representation
Live displays	Limited support	Final state only

Rich's Jupyter integration provides a consistent experience between terminal and notebook environments, making it ideal for data exploration and documentation.

Extension and Customization

Rich is designed to be extensible, allowing you to create custom renderables and extend existing components.

Creating Custom Renderables

The core of Rich's extensibility is the renderable protocol, which allows any object to be rendered by implementing specific methods.

To make an object renderable by Rich, you have two options:

1. Implement __rich__() to return an existing renderable
2. Implement __rich_console__() and __rich_measure__() for direct rendering

The __rich_console__ method generates segments for rendering, while __rich_measure__ provides sizing information for layout calculations.

Extending Rich Components

You can extend Rich's existing components to customize their behavior while retaining core functionality.

Common extension patterns include:

1. Subclassing and overriding methods to modify behavior
2. Creating custom column types for tables and progress bars
3. Implementing specialized rendering logic for specific data types

For example, you might extend the Table class to automatically format financial data, or extend the Progress class to display application-specific metrics.

Platform-Specific Considerations

When using Rich across different platforms, there are several considerations to keep in mind.

Windows-Specific Issues

Windows terminals have evolved significantly but still have some platform-specific behaviors:

1. Legacy Windows consoles (Windows 7 or older Windows 10) use the fallback rendering mechanism
2. Windows Terminal (modern) supports all Rich features including truecolor
3. When redirecting output to files on Windows, Rich automatically disables colored output

Jupyter-Specific Features

When using Rich in Jupyter:

1. Console dimensions respond to JUPYTER_COLUMNS and JUPYTER_LINES environment variables
2. The force_jupyter=True parameter can be used to force Jupyter rendering mode
3. Complex live displays like progress bars are rendered as static representations

Cross-Platform Best Practices

For maximum compatibility across platforms:

1. Use Rich's automatic terminal detection rather than forcing specific features
2. Test on multiple platforms when developing custom renderables
3. Consider using the Console.is_terminal property to detect when output is being redirected
4. Provide graceful fallbacks for advanced features when working with legacy terminals

By understanding these platform-specific considerations, you can create Rich applications that work consistently across environments.

Sources: rich/_windows.py15-61 rich/_win32_console.py1-662 tests/test_jupyter.py1-32