alternate screen

Author: willmcgugan

docs/source/console.rst

@@ -298,6 +298,24 @@ Since the default pager on most platforms don't support color, Rich will strip c
 .. note::
     Rich will use the ``PAGER`` environment variable to get the pager command. On Linux and macOS you can set this to ``less -r`` to enable paging with ANSI styles.
 
+Alternate screen
+----------------
+
+Terminals support an 'alternate screen' mode which consists of a single screen which doesn't scroll. This mode is typically used for more application-like interfaces. Rich supports this mode via the :meth:`~rich.console.Console.set_alt_screen` method, but it is recommended that you use :meth:`~rich.console.Console.screen` which returns a context manager. The context manager ensures that normal terminal operations are restored on exit.
+
+Here's an example of an alternate screen::
+
+    from time import sleep
+    from rich.console import Console
+
+    console = Console()
+    with console.screen():
+        console.print(locals())
+        sleep(5)
+    console.print("Back to normal terminal")
+
+.. node::
+    If you ever find yourself stuck in alternate mode after exiting Python code, type ``reset`` in the terminal
 
 Terminal detection
 ------------------

examples/table_movie.py

@@ -75,7 +75,11 @@ def beat(length: int = 1) -> None:
 console.clear()
 
 with Live(
-    table_centered, console=console, refresh_per_second=10, vertical_overflow="ellipsis"
+    table_centered,
+    console=console,
+    screen=True,
+    refresh_per_second=10,
+    vertical_overflow="ellipsis",
 ):
 
     with beat(10):

rich/console.py

@@ -250,6 +250,22 @@ def __exit__(self, exc_type, exc_val, exc_tb) -> None:
         self._console._exit_buffer()
 
 
+class ScreenContext:
+    """A context manager that enables an alternative screen. See :meth:`~rich.console.Console.screen` for usage."""
+
+    def __init__(self, console: "Console") -> None:
+        self.console = console
+        self._changed = False
+
+    def __enter__(self) -> "ScreenContext":
+        self._changed = self.console.set_alt_screen(True)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        if self._changed:
+            self.console.set_alt_screen(False)
+
+
 class RenderGroup:
     """Takes a group of renderables and returns a renderable object that renders the group.
 
@@ -869,14 +885,43 @@ def status(
         )
         return status_renderable
 
-    def show_cursor(self, show: bool = True) -> None:
+    def show_cursor(self, show: bool = True) -> bool:
         """Show or hide the cursor.
 
         Args:
             show (bool, optional): Set visibility of the cursor.
         """
         if self.is_terminal and not self.legacy_windows:
             self.control("\033[?25h" if show else "\033[?25l")
+            return True
+        return False
+
+    def set_alt_screen(self, enable: bool = True) -> bool:
+        """Enables alternative screen mode.
+
+        Note, if you enable this mode, you should ensure that is disabled before
+        the application exits. See :meth:`~rich.Console.screen` for a context manager
+        that handles this for you.
+
+        Args:
+            enable (bool, optional): [description]. Defaults to True.
+
+        Returns:
+            bool: True if the control codes were written.
+
+        """
+        if self.is_terminal and not self.legacy_windows:
+            self.control("\033[?1049h\033[H" if enable else "\033[?1049l")
+            return True
+        return False
+
+    def screen(self) -> "ScreenContext":
+        """Context manager to enable and disable 'alternative screen' mode.
+
+        Returns:
+            ~ScreenContext: Context which enables alternate screen on enter, and disables it on exit.
+        """
+        return ScreenContext(self)
 
     def render(
         self, renderable: RenderableType, options: ConsoleOptions = None

rich/live.py

@@ -36,6 +36,7 @@ class Live(JupyterMixin, RenderHook):
     Args:
         renderable (RenderableType, optional): The renderable to live display. Defaults to displaying nothing.
         console (Console, optional): Optional Console instance. Default will an internal Console instance writing to stdout.
+        screen (bool, optional): Enable alternate screen mode. Defaults to False.
         auto_refresh (bool, optional): Enable auto refresh. If disabled, you will need to call `refresh()` or `update()` with refresh flag. Defaults to True
         refresh_per_second (float, optional): Number of times per second to refresh the live display. Defaults to 1.
         transient (bool, optional): Clear the renderable on exit. Defaults to False.
@@ -50,6 +51,7 @@ def __init__(
         renderable: RenderableType = None,
         *,
         console: Console = None,
+        screen: bool = False,
         auto_refresh: bool = True,
         refresh_per_second: float = 4,
         transient: bool = False,
@@ -61,6 +63,8 @@ def __init__(
         assert refresh_per_second > 0, "refresh_per_second must be > 0"
         self._renderable = renderable
         self.console = console if console is not None else get_console()
+        self._screen = screen
+        self._alt_screen = False
 
         self._redirect_stdout = redirect_stdout
         self._redirect_stderr = redirect_stderr
@@ -102,6 +106,8 @@ def start(self, refresh=False) -> None:
                 return
             self.console.set_live(self)
             self._started = True
+            if self._screen:
+                self._alt_screen = self.console.set_alt_screen(True)
             self.console.show_cursor(False)
             self._enable_redirect_io()
             self.console.push_render_hook(self)
@@ -128,14 +134,16 @@ def stop(self) -> None:
                 if self.console.is_terminal:
                     self.console.line()
             finally:
-                self.console.show_cursor(True)
                 self._disable_redirect_io()
                 self.console.pop_render_hook()
+                self.console.show_cursor(True)
+                if self._alt_screen:
+                    self.console.set_alt_screen(False)
 
         if self._refresh_thread is not None:
             self._refresh_thread.join()
             self._refresh_thread = None
-        if self.transient:
+        if self.transient and not self._screen:
             self.console.control(self._live_render.restore_cursor())
         if self.ipy_widget is not None:  # pragma: no cover
             if self.transient:
@@ -231,7 +239,9 @@ def process_renderables(
             with self._lock:
                 # determine the control command needed to clear previous rendering
                 renderables = [
-                    self._live_render.position_cursor(),
+                    Control("\033[H")
+                    if self._alt_screen
+                    else self._live_render.position_cursor(),
                     *renderables,
                     self._live_render,
                 ]