progress improvements

Author: willmcgugan

CHANGELOG.md

@@ -10,6 +10,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Added -p switch to python -m rich.markdown to page output
+- Added Console.control to output control codes
+
+### Changed
+
+- Changed Console log_time_format to no longer require a space at the end
+- Added print and log to Progress to render terminal output when progress is active
 
 ## [1.1.1] - 2020-05-12
 

docs/source/progress.rst

@@ -81,6 +81,24 @@ The following column objects are available:
 - :class:`~rich.progress.DownloadColumn` Displays download progress (assumes the steps are bytes).
 - :class:`~rich.progress.TransferSpeedColumn` Displays transfer speed (assumes the steps are bytes.
 
+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.
+
+
+Extending
+~~~~~~~~~
+
+If the progress API doesn't offer exactly what you need in terms of a progress display, you can extend the :class:`~rich.progress.Progress` class by overriding the :class:`~rich.progress.Progress.get_renderables` method. For example, the following class will render a :class:`~rich.panel.Panel` around the progress display::
+
+    from rich.panel import Panel
+    from rich.progress import Progress
+
+    class MyProgress(Progress):
+        def get_renderables(self):
+            yield Panel(self.make_tasks_table(self.tasks))            
+
 
 Example
 -------

rich/console.py

@@ -129,10 +129,10 @@ def __console__(
 
 
 """A type that may be rendered by Console."""
-RenderableType = Union[ConsoleRenderable, RichCast, Control, str]
+RenderableType = Union[ConsoleRenderable, RichCast, str]
 
 """The result of calling a __console__ method."""
-RenderResult = Iterable[Union[RenderableType, Segment, Control]]
+RenderResult = Iterable[Union[RenderableType, Segment]]
 
 
 _null_highlighter = NullHighlighter()
@@ -207,15 +207,14 @@ class ConsoleThreadLocals(threading.local):
 
     buffer: List[Segment] = field(default_factory=list)
     buffer_index: int = 0
-    control: List[str] = field(default_factory=list)
 
 
 def detect_legacy_windows() -> bool:
     """Detect legacy Windows."""
     return "WINDIR" in os.environ and "WT_SESSION" not in os.environ
 
 
-if detect_legacy_windows():
+if detect_legacy_windows():  # pragma: no cover
     from colorama import init
 
     init()
@@ -274,18 +273,16 @@ def __init__(
 
         self._color_system: Optional[ColorSystem]
         self._force_terminal = force_terminal
-        if self.legacy_windows:
-            self.file = file or sys.stdout
-            self._color_system = COLOR_SYSTEMS["windows"]
+        self.file = file or sys.stdout
+
+        if color_system is None:
+            self._color_system = None
+        elif color_system == "auto":
+            self._color_system = self._detect_color_system()
         else:
-            self.file = file or sys.stdout
-            if color_system is None:
-                self._color_system = None
-            elif color_system == "auto":
-                self._color_system = self._detect_color_system()
-            else:
-                self._color_system = COLOR_SYSTEMS[color_system]
+            self._color_system = COLOR_SYSTEMS[color_system]
 
+        self._lock = threading.RLock()
         self._log_render = LogRender(
             show_time=log_time, show_path=log_path, time_format=log_time_format
         )
@@ -312,15 +309,12 @@ def _buffer_index(self) -> int:
     def _buffer_index(self, value: int) -> None:
         self._thread_locals.buffer_index = value
 
-    @property
-    def _control(self) -> List[str]:
-        """Get control codes buffer."""
-        return self._thread_locals.control
-
     def _detect_color_system(self) -> Optional[ColorSystem]:
         """Detect color system from env vars."""
         if not self.is_terminal:
             return None
+        if self.legacy_windows:  # pragma: no cover
+            return ColorSystem.WINDOWS
         color_term = os.environ.get("COLORTERM", "").strip().lower()
         return (
             ColorSystem.TRUECOLOR
@@ -402,10 +396,8 @@ def size(self) -> ConsoleDimensions:
             return ConsoleDimensions(self._width, self._height)
 
         width, height = shutil.get_terminal_size()
-        if self.legacy_windows:
-            width -= 1
         return ConsoleDimensions(
-            width if self._width is None else self._width,
+            (width - self.legacy_windows) if self._width is None else self._width,
             height if self._height is None else self._height,
         )
 
@@ -441,9 +433,7 @@ def show_cursor(self, show: bool = True) -> None:
         self.file.write("\033[?25h" if show else "\033[?25l")
 
     def _render(
-        self,
-        renderable: Union[RenderableType, Control],
-        options: Optional[ConsoleOptions],
+        self, renderable: RenderableType, options: Optional[ConsoleOptions],
     ) -> Iterable[Segment]:
         """Render an object in to an iterable of `Segment` instances.
 
@@ -459,9 +449,6 @@ def _render(
             Iterable[Segment]: An iterable of segments that may be rendered.
         """
         render_iterable: RenderResult
-        if isinstance(renderable, Control):
-            self._control.append(renderable.codes)
-            return
         render_options = options or self.options
         if isinstance(renderable, ConsoleRenderable):
             render_iterable = renderable.__console__(self, render_options)
@@ -487,7 +474,7 @@ def _render(
                 yield from self.render(render_output, render_options)
 
     def render(
-        self, renderable: RenderableType, options: Optional[ConsoleOptions]
+        self, renderable: RenderableType, options: Optional[ConsoleOptions] = None
     ) -> Iterable[Segment]:
         """Render an object in to an iterable of `Segment` instances.
 
@@ -504,7 +491,7 @@ def render(
             Iterable[Segment]: An iterable of segments that may be rendered.
         """
 
-        yield from self._render(renderable, options)
+        yield from self._render(renderable, options or self.options)
 
     def render_lines(
         self,
@@ -685,6 +672,16 @@ def rule(
         rule = Rule(title=title, character=character, style=style)
         self.print(rule)
 
+    def control(self, control_codes: Union["Control", str]) -> None:
+        """Insert non-printing control codes.
+
+        Args:
+            control_codes (str): Control codes, such as those that may move the cursor.
+        """
+
+        self._buffer.append(Segment.control(str(control_codes)))
+        self._check_buffer()
+
     def print(
         self,
         *objects: Any,
@@ -802,10 +799,11 @@ def log(
 
     def _check_buffer(self) -> None:
         """Check if the buffer may be rendered."""
-        if self._buffer_index == 0:
-            text = self._render_buffer()
-            self.file.write(text)
-            self.file.flush()
+        with self._lock:
+            if self._buffer_index == 0:
+                text = self._render_buffer()
+                self.file.write(text)
+                self.file.flush()
 
     def _render_buffer(self) -> str:
         """Render buffered output, and clear buffer."""
@@ -818,14 +816,13 @@ def _render_buffer(self) -> str:
                 self._record_buffer.extend(buffer)
         del self._buffer[:]
         for line in Segment.split_and_crop_lines(buffer, self.width, pad=False):
-            for text, style in line:
-                if style:
+            for text, style, is_control in line:
+                if style and not is_control:
                     append(style.render(text, color_system=color_system))
                 else:
                     append(text)
 
-        rendered = "".join(self._control) + "".join(output)
-        del self._control[:]
+        rendered = "".join(output)
         return rendered
 
     def export_text(self, clear: bool = True, styles: bool = False) -> str:
@@ -848,10 +845,10 @@ def export_text(self, clear: bool = True, styles: bool = False) -> str:
             if styles:
                 text = "".join(
                     (style.render(text) if style else text)
-                    for text, style in self._record_buffer
+                    for text, style, _ in self._record_buffer
                 )
             else:
-                text = "".join(text for text, _ in self._record_buffer)
+                text = "".join(text for text, _, _ in self._record_buffer)
             if clear:
                 del self._record_buffer[:]
         return text
@@ -907,7 +904,9 @@ def escape(text: str) -> str:
 
         with self._record_buffer_lock:
             if inline_styles:
-                for text, style in Segment.simplify(self._record_buffer):
+                for text, style, _ in Segment.filter_control(
+                    Segment.simplify(self._record_buffer)
+                ):
                     text = escape(text)
                     if style:
                         rule = style.get_html_style(_theme)
@@ -916,7 +915,9 @@ def escape(text: str) -> str:
                         append(text)
             else:
                 styles: Dict[str, int] = {}
-                for text, style in Segment.simplify(self._record_buffer):
+                for text, style, _ in Segment.filter_control(
+                    Segment.simplify(self._record_buffer)
+                ):
                     text = escape(text)
                     if style:
                         rule = style.get_html_style(_theme)

rich/control.py

@@ -1,5 +1,9 @@
-from typing import NamedTuple
+from typing import NamedTuple, TYPE_CHECKING
 
+from .segment import Segment
+
+if TYPE_CHECKING:
+    from .console import Console, ConsoleOptions, RenderResult
 
 STRIP_CONTROL_CODES = [
     8,  # Backspace
@@ -10,11 +14,25 @@
 _CONTROL_TRANSLATE = {_codepoint: None for _codepoint in STRIP_CONTROL_CODES}
 
 
-class Control(NamedTuple):
-    """Control codes that are not printable."""
+class Control:
+    """A renderable that inserts a control code (non printable but may move cursor).
+
+    Args:
+        control_codes (str): A string containing control codes.
+    """
+
+    __slots__ = ["_control_codes"]
+
+    def __init__(self, control_codes: str) -> None:
+        self._control_codes = Segment.control(control_codes)
+
+    def __str__(self) -> str:
+        return self._control_codes.text
 
-    # May define pre and post control codes eventually
-    codes: str
+    def __console__(
+        self, console: "Console", options: "ConsoleOptions"
+    ) -> "RenderResult":
+        yield self._control_codes
 
 
 def strip_control_codes(text: str, _translate_table=_CONTROL_TRANSLATE) -> str:

rich/live_render.py

@@ -1,4 +1,4 @@
-from typing import Optional, Tuple
+from typing import Iterable, Optional, Tuple
 
 from .console import Console, ConsoleOptions, RenderableType, RenderResult
 from .control import Control
@@ -16,14 +16,21 @@ def __init__(self, renderable: RenderableType, style: StyleType = "") -> None:
     def set_renderable(self, renderable: RenderableType) -> None:
         self.renderable = renderable
 
-    def __console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+    def position_cursor(self) -> Control:
+        """Get control codes to move cursor to beggining of live render.
 
+        Returns:
+            str: String containing control codes.
+        """
         if self._shape is not None:
-            width, height = self._shape
+            _, height = self._shape
             if height > 1:
-                yield Control(f"\r\x1b[{height - 1}A")
+                return Control(f"\r\x1b[{height - 1}A\x1b[2K")
             else:
-                yield Control("\r")
+                return Control("\r")
+        return Control("")
+
+    def __console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
         style = console.get_style(self.style)
         lines = console.render_lines(self.renderable, options, style, pad=False)