Is layout.Layout.refresh_screen Stable Across Operating Systems?

[PyWoody]

I have been using layout.Layout.refresh_screen [0] in personal projects for fast layout updates with very low CPU usage with great success. I'm only ever on Mac or Linux boxes, so, before I use it for public facing projects, is refresh_screen stable across operating systems?

The only reference to the method I can find in either the documentation or source code is in the test_layout.py file that claims it does not run on windows [1]

@pytest.mark.skipif(sys.platform == "win32", reason="does not run on windows")

I don't have access to a Windows machine at the moment but I did spin up a Win11 VM in UTM and it appeared to work fine in the default terminal.

Below is a quick demo of using layout.refresh_screen compared to relying on Live's default auto refresh.

The first run, which uses refresh_screen, will update instantaneously while also using very little CPU. The second run, which relies on Live's default refresh_per_second setting of 4, will be "chunkier" in its updates, since it's only updating 4 times per second, but it will also use considerably more CPU.

I understand that Live will be more responsive in the sense that it will automatically adjust the Panel sizes when the terminal is resized but that's easy enough to track manually and call Live.update when needed.

I initially did a test calling Live.update manually on each iteration but it consumed so much CPU it was not a feasible solution.

If refresh_screen is stable across operating systems, I would be glad to write a quick example for the examples folder.

import itertools
import random
import shutil
import time

from rich import box
from rich.layout import Layout
from rich.live import Live
from rich.panel import Panel


def build_layout(height, width):
    layout = Layout(name='top')
    layout['top'].split_column(
        *(Layout(name=f'Row-{y}') for y in range(height))
    )
    panel = Panel('', box=box.MINIMAL)
    for y in range(height):
        layout[f'Row-{y}'].split_row(
            *(Layout(panel, name=f'Row-{y}_Col-{x}') for x in range(width))
        )
    return layout


def run():
    width, height = shutil.get_terminal_size()
    panels = itertools.cycle(
        Panel('', style=f'on color({i})', box=box.MINIMAL) for i in range(256)
    )

    setup_cords = [(y, x) for y in range(height) for x in range(width)]
    random.shuffle(setup_cords)

    clear_cords = [(y, x) for y in range(height) for x in range(width)]
    random.shuffle(clear_cords)

    empty_panel = Panel('', box=box.MINIMAL)

    # Manually updating via layout.refresh_screen
    layout = build_layout(height, width)
    with Live(layout, auto_refresh=False, screen=True) as live:
        for y, x in setup_cords:
            if _layout := layout.get(f'Row-{y}_Col-{x}'):
                _layout.update(next(panels))
                layout.refresh_screen(
                    live.console, f'Row-{y}_Col-{x}'
                )
            time.sleep(.001)

        for y, x in clear_cords:
            if _layout := layout.get(f'Row-{y}_Col-{x}'):
                _layout.update(empty_panel)
                layout.refresh_screen(
                    live.console, f'Row-{y}_Col-{x}'
                )
            time.sleep(.001)

    # Default refresh
    layout = build_layout(height, width)
    with Live(layout, screen=True):
        for y, x in setup_cords:
            if _layout := layout.get(f'Row-{y}_Col-{x}'):
                _layout.update(next(panels))
            time.sleep(.001)

        for y, x in clear_cords:
            if _layout := layout.get(f'Row-{y}_Col-{x}'):
                _layout.update(empty_panel)
            time.sleep(.001)


if __name__ == '__main__':
    run()

[0] https://github.com/Textualize/rich/blob/master/rich/layout.py#L328
[1] https://github.com/Textualize/rich/blob/master/tests/test_layout.py#L86