Add option to skip final newline in Live

[darlingm]

I have a table that can be displayed instantly, except for one column which takes a while to determine. I used Live to instantly print the table with the slow column blank, and backfill the empty cells as they're determined. This allows not waiting for the slow data before being able to see the rest of it. This worked great, except when it finishes and exits, the screen scrolls a line for the bash prompt to display. It's a bit jarring when I'm reading for it to scroll a line.

So, I tried:

1. Including a blank line in the Live renderable, immediately reserving the line for the shell prompt, with Group(table, Text("")).
2. After Live.stop() executed, manually moving the cursor up a line, moving to column 0, and clearing the line with console.file.write("\x1b[1A\r\x1b[2K").

This didn't quite work. During the slow Live updating, there was the trailing blank line (intended for the shell prompt.) But, afterward, Rich emitted another newline which caused the table to scroll again even though the shell prompt wound up on the line after the table, with a blank line after it.

I'd like to submit an issue and a PR to give Live an optional argument to skip printing the final newline when it's done. It would default to the current behavior of printing it so there's no change in behavior unless someone uses the new argument.

live_final_newline_demo.py, included below, can run without any changes to Rich and demonstrate what I'm talking about. It immediately prints the table, sleeps a second to simulate the slowness, and updates the last column. It shows the scrolling that seems jarring to me. With the proposed implementation on my feature/live/optional-final-newline branch, you can run this with --final-newline false to make the prompt land on the already reserved line.

An alternative implementation would be to give Live an option like reserve_final_line=False as a default, but when set to true it would automatically display a final blank line and leave the cursor on it when it's done. Then, the caller wouldn't have to emit an empty Text line and wouldn't have to manually move the cursor. That would be a larger set of changes. I'd be happy to do it and submit it that way, but my first instinct was to keep the change smaller.

live_final_newline_demo.py

"""Demo for Rich Live's optional final newline behavior.

Run with released Rich:

    python live_final_newline_demo.py

Run with the patched Rich branch:

    python live_final_newline_demo.py --final-newline false

The program intentionally prints nothing after the Live display exits. The
observable behavior is where the shell prompt appears after the final table.
"""

from __future__ import annotations

import argparse
import inspect
from time import sleep

from rich.console import Console, Group
from rich.live import Live
from rich.table import Table
from rich.text import Text


def build_table(phase: str, final_newline: str, supported: bool) -> Table:
    table = Table(title="Live final newline demo")
    table.add_column("Field")
    table.add_column("Value")
    table.add_row("phase", phase)
    table.add_row("final_newline", final_newline)
    table.add_row("supported", "yes" if supported else "no")
    return table


def build_renderable(phase: str, final_newline: str, supported: bool) -> Group:
    return Group(build_table(phase, final_newline, supported), Text(""))


def supports_final_newline() -> bool:
    return "final_newline" in inspect.signature(Live).parameters


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Display a short Live table, update it once, and exit without printing after the table.",
    )
    parser.add_argument(
        "--final-newline",
        choices=("default", "true", "false"),
        default="default",
        help=(
            "Live final newline mode. 'default' passes no argument and works on released Rich; "
            "'false' demonstrates the patched behavior when supported."
        ),
    )
    return parser.parse_args()


def main() -> int:
    args = parse_args()
    console = Console()
    supported = supports_final_newline()
    final_newline_label = args.final_newline

    live_options = {
        "console": console,
        "refresh_per_second": 12,
        "transient": False,
    }
    if args.final_newline != "default":
        if supported:
            live_options["final_newline"] = args.final_newline == "true"
        else:
            final_newline_label = f"{args.final_newline} requested, unsupported"

    with Live(build_renderable("initial", final_newline_label, supported), **live_options) as live:
        sleep(1)
        live.update(build_renderable("updated", final_newline_label, supported), refresh=True)

    if console.is_terminal:
        console.file.write("\r\x1b[2K")
        console.file.flush()

    return 0


if __name__ == "__main__":
    raise SystemExit(main())

EDIT: Follow-up to #4185 (fair enough!)