Merge pull request #111 from willmcgugan/transparent-progress

add new render hooks for transparent progress

Author: willmcgugan

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2020-06-14
+
+### Added
+
+- Added redirect_stdout and redirect_stderr to Progress
+
+### Changed
+
+- printing to console with an active Progress doesn't break visuals
+
 ## [2.1.0] - 2020-06-11
 
 ### Added

docs/source/progress.rst

@@ -118,7 +118,29 @@ To implement your own columns, extend the :class:`~rich.progress.Progress` and u
 Print / log
 ~~~~~~~~~~~
 
-When a progress display is running, printing or logging anything directly to the console will break the visuals. To work around this, the Progress class provides :meth:`~rich.progress.Progress.print` and :meth:`~rich.progress.Progress.log` which work the same as their counterparts on :class:`~rich.console.Console` but will move the cursor and refresh automatically -- ensure that everything renders properly.
+The Progress class will create an internal Console object which you can access via ``progress.console``. If you print or log to this console, the output will be displayed *above* the progress display. Here's an example::
+
+    with Progress() as progress:
+        task = progress.add_task(total=10)
+        for job in range(10):
+            progress.console.print("Working on job #{job}")
+            run_job(job)
+            progress.advance(task)
+
+If you have another Console object you want to use, pass it in to the :class:`~rich.progress.Progress` constructor. Here's an example::
+
+    from my_project import my_console
+
+    with Progress(console=my_console) as progress:
+        my_console.print("[bold blue]Starting work!")
+        do_work(progress)
+        
+
+Redirecting stdout / stderr
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To avoid breaking the progress display visuals, Rich will redirect ``stdout`` and ``stdout`` so that you can use the builtin ``print`` statement. This feature is enabled by default, but you can disable by setting ``redirect_stdout`` or ``redirect_stderr`` to ``False``
+
 
 Customizing
 ~~~~~~~~~~~

pyproject.toml

@@ -2,7 +2,7 @@
 name = "rich"
 homepage = "https://github.com/willmcgugan/rich"
 documentation = "https://rich.readthedocs.io/en/latest/"
-version = "2.1.0"
+version = "2.2.0"
 description = "Render rich text, tables, progress bars, syntax highlighting, markdown and more to the terminal"
 authors = ["Will McGugan <willmcgugan@gmail.com>"]
 license = "MIT"

rich/console.py

@@ -235,6 +235,25 @@ class ConsoleThreadLocals(threading.local):
     buffer_index: int = 0
 
 
+class RenderHook:
+    """Provides hooks in to the render process."""
+
+    def process_renderables(
+        self, renderables: List[ConsoleRenderable]
+    ) -> List[ConsoleRenderable]:
+        """Called with a list of objects to render.
+
+        This method can return a new list of renderables, or modify and return the same list.
+
+        Args:
+            renderables (List[ConsoleRenderable]): A number of renderable objects.
+
+        Returns:
+            List[ConsoleRenderable]: A replacement list of renderables.
+        """
+        return renderables
+
+
 def detect_legacy_windows() -> bool:
     """Detect legacy Windows."""
     return "WINDIR" in os.environ and "WT_SESSION" not in os.environ
@@ -325,6 +344,7 @@ def __init__(
         self._record_buffer_lock = threading.RLock()
         self._thread_locals = ConsoleThreadLocals()
         self._record_buffer: List[Segment] = []
+        self._render_hooks: List[RenderHook] = []
 
     def __repr__(self) -> str:
         return f"<console width={self.width} {str(self._color_system)}>"
@@ -368,6 +388,19 @@ def _exit_buffer(self) -> None:
         self._buffer_index -= 1
         self._check_buffer()
 
+    def push_render_hook(self, hook: RenderHook) -> None:
+        """Add a new render hook to the stack.
+
+        Args:
+            hook (RenderHook): Render hook instance.
+        """
+
+        self._render_hooks.append(hook)
+
+    def pop_render_hook(self) -> None:
+        """Pop the last renderhook from the stack."""
+        self._render_hooks.pop()
+
     def __enter__(self) -> "Console":
         """Own context manager to enter buffer context."""
         self._enter_buffer()
@@ -754,7 +787,7 @@ def print(
             end (str, optional): String to write at end of print data. Defaults to "\n".
             style (Union[str, Style], optional): A style to apply to output. Defaults to None.
             justify (str, optional): Justify method: "default", "left", "right", "center", or "full". Defaults to ``None``.
-            overflow (str, optional): Overflow method: "crop", "fold", or "ellipisis". Defaults to None.
+            overflow (str, optional): Overflow method: "crop", "fold", or "ellipsis". Defaults to None.
             no_wrap (Optional[bool], optional): Disable word wrapping. Defaults to None.
             emoji (Optional[bool], optional): Enable emoji code, or ``None`` to use console default. Defaults to ``None``.
             markup (Optional[bool], optional): Enable markup, or ``None`` to use console default. Defaults to ``None``.
@@ -775,6 +808,8 @@ def print(
                 markup=markup,
                 highlight=highlight,
             )
+            for hook in self._render_hooks:
+                renderables = hook.process_renderables(renderables)
             render_options = self.options.update(
                 justify=justify, overflow=overflow, width=width, no_wrap=no_wrap
             )
@@ -843,35 +878,39 @@ def log(
         if not objects:
             self.line()
             return
-        renderables = self._collect_renderables(
-            objects,
-            sep,
-            end,
-            justify=justify,
-            emoji=emoji,
-            markup=markup,
-            highlight=highlight,
-        )
-
-        caller = inspect.stack()[_stack_offset]
-        path = caller.filename.rpartition(os.sep)[-1]
-        line_no = caller.lineno
-        if log_locals:
-            locals_map = {
-                key: value
-                for key, value in caller.frame.f_locals.items()
-                if not key.startswith("__")
-            }
-            renderables.append(tabulate_mapping(locals_map, title="Locals"))
-
         with self:
-            self._buffer.extend(
-                self.render(
-                    self._log_render(self, renderables, path=path, line_no=line_no),
-                    self.options,
-                )
+            renderables = self._collect_renderables(
+                objects,
+                sep,
+                end,
+                justify=justify,
+                emoji=emoji,
+                markup=markup,
+                highlight=highlight,
             )
 
+            caller = inspect.stack()[_stack_offset]
+            path = caller.filename.rpartition(os.sep)[-1]
+            line_no = caller.lineno
+            if log_locals:
+                locals_map = {
+                    key: value
+                    for key, value in caller.frame.f_locals.items()
+                    if not key.startswith("__")
+                }
+                renderables.append(tabulate_mapping(locals_map, title="Locals"))
+
+            renderables = [
+                self._log_render(self, renderables, path=path, line_no=line_no)
+            ]
+            for hook in self._render_hooks:
+                renderables = hook.process_renderables(renderables)
+            extend = self._buffer.extend
+            render = self.render
+            render_options = self.options
+            for renderable in renderables:
+                extend(render(renderable, render_options))
+
     def _check_buffer(self) -> None:
         """Check if the buffer may be rendered."""
         with self._lock:
@@ -883,7 +922,8 @@ def _check_buffer(self) -> None:
                     del self._buffer[:]
                 else:
                     text = self._render_buffer()
-                    self.file.write(text)
+                    if text:
+                        self.file.write(text)
                     self.file.flush()
 
     def _render_buffer(self) -> str:

rich/live_render.py

@@ -36,10 +36,7 @@ def position_cursor(self) -> Control:
         """
         if self._shape is not None:
             _, height = self._shape
-            if height > 1:
-                return Control(f"\r\x1b[{height - 1}A\x1b[2K")
-            else:
-                return Control("\r\x1b[2K")
+            return Control("\r\x1b[2K" + "\x1b[1A\x1b[2K" * (height - 1))
         return Control("")
 
     def restore_cursor(self) -> Control:

rich/logging.py

@@ -3,6 +3,7 @@
 from logging import Handler, LogRecord
 from pathlib import Path
 
+from . import get_console
 from rich._log_render import LogRender
 from rich.console import Console
 from rich.highlighter import ReprHighlighter
@@ -25,7 +26,7 @@ class RichHandler(Handler):
 
     def __init__(self, level: int = logging.NOTSET, console: Console = None) -> None:
         super().__init__(level=level)
-        self.console = Console() if console is None else console
+        self.console = console or get_console()
         self.highlighter = ReprHighlighter()
         self._log_render = LogRender(show_level=True)