pretty docs

jizongFox · Jun 9, 2021 · 1af5eee · 1af5eee
1 parent 5d18450
commit 1af5eee
Show file tree

Hide file tree

Showing 14 changed files with 314 additions and 45 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added Console.size setter
 - Added Console.width setter
 - Added Console.height setter
+- Added angular style Rich reprs
 
 ## [10.2.2] - 2021-05-19
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -16,6 +16,7 @@ Welcome to Rich's documentation!
    markup.rst
    text.rst
    highlighting.rst
+   pretty.rst
    logging.rst
    traceback.rst
    prompt.rst

diff --git a/docs/source/pretty.rst b/docs/source/pretty.rst
@@ -0,0 +1,162 @@
+Pretty
+======
+
+In addition to syntax highlighting, Rich will automatically format any containers (lists, dicts, sets etc) you print to the console. The formatting method used by Rich follows well established conventions in the Python world to present data in a more readable way. 
+
+Run the following command to see an example of pretty printed output::
+
+    python -m rich.pretty
+
+Note how the output will change if you change the width of the terminal.
+
+pprint method
+-------------
+
+The :func:`~rich.pretty.pprint` method offers a few more argument you can use to tweak how objects are pretty printed. Here's how you would import it::
+
+    >>> from rich.pretty import pprint
+    >>> pprint(locals())
+
+Indent guides
+~~~~~~~~~~~~~
+
+Rich can draw *intent guides* which are vertical lines to highlight the indent level of a data structure. These can make it easier to read more deeply nested output. The pprint method enables indent guides by default, but you can set ``indent_guides=False`` to disable this feature. 
+
+Expand all
+~~~~~~~~~~
+
+Rich is quite conservative about expanding data structures and will try to fit as much in each line as it can. If you prefer, you can tell Rich to fully expand all data structures by setting ``expand_all=True``. Here's an example::
+
+    >>> pprint(["eggs", "ham"], expand_all=True)
+
+Truncating pretty output
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Very long data structures can be difficult to read and you may find yourself scrolling through multiple pages to find the output you are interested in. Rich can truncate containers and long strings if you just need a general overview a data structure.
+
+If you set the ``max_length`` argument to an integer then Rich will truncate containers with more than the given number of elements. If data is truncated, Rich will display an ellipsis ``...`` and the number of elements not shown.
+
+Here's an example::
+
+    >>> pprint(locals(), max_length=2)
+
+Truncating long strings
+~~~~~~~~~~~~~~~~~~~~~~~
+
+If you set the `max_string` argument to an integer, Rich will truncate strings over that length. Truncated string will be appended with the number of characters that have not been shown. Here's an example::
+
+    >>> pprint("Where there is a Will, there is a Way", max_string=21)
+
+Pretty renderable
+-----------------
+
+Rich offers a :class:`~rich.pretty.Pretty` class which you can user to insert pretty printed data in to another renderable.
+
+The following example, prints pretty printed output within a simple panel::
+
+    from rich import print
+    from rich.pretty import Pretty
+    from rich.panel import Panel
+
+    pretty = Pretty(locals())
+    panel = Panel(pretty)
+    print(panel)
+
+There are a large number of options to tweak the pretty formatting, See the :class:`~rich.pretty.Pretty` reference for details.
+
+Rich Repr
+---------
+
+Rich is able to syntax highlight any output, but the extra formatting done by the pretty printing is restricted to builtin containers, dataclasses, and other objects Rich knows about, such as objects generated by the `attrs <https://www.attrs.org/en/stable/>`_ library. Fortunately Rich offers a simple protocol you can use to add pretty printable output to any object.
+
+First, let's look at a class that might benefit from a Rich repr::
+
+    class Bird:
+        def __init__(self, name, eats=None, fly=True, extinct=False):
+            self.name = name
+            self.eats = list(eats) if eats else []
+            self.fly = fly
+            self.extinct = extinct
+
+        def __repr__(self):
+            return f"Bird({self.name!r}, eats={self.eats!r}, fly={self.fly!r}, extinct={self.extinct!r})"
+
+    BIRDS = {
+        "gull": Bird("gull", eats=["fish", "chips", "ice cream", "sausage rolls"]),
+        "penguin": Bird("penguin", eats=["fish"], fly=False),
+        "dodo": Bird("dodo", eats=["fruit"], fly=False, extinct=True)
+    }
+    print(BIRDS)
+
+The result of this script would be::
+
+    {'gull': Bird('gull', eats=['fish', 'chips', 'ice cream', 'sausage rolls'], fly=True, extinct=False), 'penguin': Bird('penguin', eats=['fish'], fly=False, extinct=False), 'dodo': Bird('dodo', eats=['fruit'], fly=False, extinct=True)}
+
+The output is long enough to wrap on to the next line, which can make it hard to read. The repr strings are informative but a little verbose since they include default arguments. If we print this with Rich, things are improved somewhat::
+
+    {
+        'gull': Bird('gull', eats=['fish', 'chips', 'ice cream', 'sausage rolls'],
+    fly=True, extinct=False),
+        'penguin': Bird('penguin', eats=['fish'], fly=False, extinct=False),
+        'dodo': Bird('dodo', eats=['fruit'], fly=False, extinct=True)
+    }
+
+Rich knows how to format the container dict, but the repr strings are still verbose, and there is some wrapping of the output (assuming an 80 character terminal).
+
+We can solve both these issues by adding the following ``__rich_repr__`` method::
+
+    def __rich_repr__(self):
+        yield self.name
+        yield "eats", self.eats
+        yield "fly", self.fly, True
+        yield "extinct", self.extinct, False
+
+Now if we print the same object with Rich we would get the following::
+
+    {
+        'gull': Bird(
+            'gull',
+            eats=['fish', 'chips', 'ice cream', 'sausage rolls']
+        ),
+        'penguin': Bird('penguin', eats=['fish'], fly=False),
+        'dodo': Bird('dodo', eats=['fruit'], fly=False, extinct=True)
+    }
+
+The default arguments have been omitted, and the output has been formatted nicely. Even if we have less room in the terminal, the result is still quite readable::
+
+    {
+        'gull': Bird(
+            'gull',
+            eats=[
+                'fish',
+                'chips',
+                'ice cream',
+                'sausage rolls'
+            ]
+        ),
+        'penguin': Bird(
+            'penguin',
+            eats=['fish'],
+            fly=False
+        ),
+        'dodo': Bird(
+            'dodo',
+            eats=['fruit'],
+            fly=False,
+            extinct=True
+        )
+    }
+
+You can add a ``__rich_repr__`` method to any class to enable Rich reprs. This method should return an iterable of tuples. You could return a list of tuples, but it's easier to express with the ``yield`` keywords, making it a *generator*.
+
+Each tuple specifies an element in the output.
+
+- ``yield value`` will generate a positional argument.
+- ``yield name, value`` will generate a keyword argument.
+- ``yield name, value, default`` will generate a keyword argument *if* ``value`` is not equal to ``default``. 
+
+You can also tell Rich to generate the *angular bracket* style of repr, which tend to be used where there is no easy way to recreate the object's constructor. To do this set the function attribute ``"angluar"`` to ``True`` immediately after your ``__rich_repr__`` methods. For example::
+
+    __rich_repr__.angular = True
+
+Note that you can add ``__rich_repr__`` methods to third-party libraries *without* including Rich as a dependency. If Rich is not installed, then nothing will break. Hopefully many more libraries will adopt Rich repr methods in the future, which will aid debugging!
diff --git a/examples/repr.py b/examples/repr.py
@@ -0,0 +1,25 @@
+class Bird:
+    def __init__(self, name, eats=None, fly=True, extinct=False):
+        self.name = name
+        self.eats = list(eats) if eats else []
+        self.fly = fly
+        self.extinct = extinct
+
+    def __repr__(self):
+        return f"Bird({self.name!r}, eats={self.eats!r}, fly={self.fly!r}, extinct={self.extinct!r})"
+
+    def __rich_repr__(self):
+        yield self.name
+        yield "eats", self.eats
+        yield "fly", self.fly, True
+        yield "extinct", self.extinct, False
+
+    __rich_repr__.angular = True
+
+from rich import print    
+BIRDS = {
+    "gull": Bird("gull", eats=["fish", "chips", "ice cream", "sausage rolls"]),
+    "penguin": Bird("penguin", eats=["fish"], fly=False),
+    "dodo": Bird("dodo", eats=["fruit"], fly=False, extinct=True)
+}
+print(BIRDS)
diff --git a/rich/highlighter.py b/rich/highlighter.py
@@ -81,7 +81,7 @@ class ReprHighlighter(RegexHighlighter):
 
     base_style = "repr."
     highlights = [
-        r"(?P<tag_start>\<)(?P<tag_name>[\w\-\.\:]*)(?P<tag_contents>.*?)(?P<tag_end>\>)",
+        r"(?P<tag_start>\<)(?P<tag_name>[\w\-\.\:]*)(?P<tag_contents>[\w\W]*?)(?P<tag_end>\>)",
         r"(?P<attrib_name>[\w_]{1,50})=(?P<attrib_value>\"?[\w_]+\"?)?",
         r"(?P<brace>[\{\[\(\)\]\}])",
         _combine_regex(

diff --git a/rich/layout.py b/rich/layout.py
@@ -181,8 +181,6 @@ def __rich_repr__(self) -> RichReprResult:
         yield "minimum_size", self.minimum_size, 1
         yield "ratio", self.ratio, 1
 
-    __rich_repr__.meta = {"angular": True}
-
     @property
     def renderable(self) -> RenderableType:
         """Layout renderable."""

diff --git a/rich/pretty.py b/rich/pretty.py
@@ -301,11 +301,7 @@ class Node:
     is_tuple: bool = False
     children: Optional[List["Node"]] = None
     key_separator = ": "
-
-    @property
-    def separator(self) -> str:
-        """Get separator between items."""
-        return "" if self.last else ","
+    separator: str = ", "
 
     def iter_tokens(self) -> Iterable[str]:
         """Generate tokens for this node."""
@@ -324,7 +320,7 @@ def iter_tokens(self) -> Iterable[str]:
                     for child in self.children:
                         yield from child.iter_tokens()
                         if not child.last:
-                            yield ", "
+                            yield self.separator
                 yield self.close_brace
             else:
                 yield self.empty
@@ -380,12 +376,14 @@ def render(
 class _Line:
     """A line in repr output."""
 
+    parent: Optional["_Line"] = None
     is_root: bool = False
     node: Optional[Node] = None
     text: str = ""
     suffix: str = ""
     whitespace: str = ""
     expanded: bool = False
+    last: bool = False
 
     @property
     def expandable(self) -> bool:
@@ -407,31 +405,39 @@ def expand(self, indent_size: int) -> Iterable["_Line"]:
         whitespace = self.whitespace
         assert node.children
         if node.key_repr:
-            yield _Line(
+            new_line = yield _Line(
                 text=f"{node.key_repr}{node.key_separator}{node.open_brace}",
                 whitespace=whitespace,
             )
         else:
-            yield _Line(text=node.open_brace, whitespace=whitespace)
+            new_line = yield _Line(text=node.open_brace, whitespace=whitespace)
         child_whitespace = self.whitespace + " " * indent_size
         tuple_of_one = node.is_tuple and len(node.children) == 1
-        for child in node.children:
-            separator = "," if tuple_of_one else child.separator
+        for last, child in loop_last(node.children):
+            separator = "," if tuple_of_one else node.separator
             line = _Line(
+                parent=new_line,
                 node=child,
                 whitespace=child_whitespace,
                 suffix=separator,
+                last=last and not tuple_of_one,
             )
             yield line
 
         yield _Line(
             text=node.close_brace,
             whitespace=whitespace,
-            suffix="," if (tuple_of_one and not self.is_root) else node.separator,
+            suffix=self.suffix,
+            last=self.last,
         )
 
     def __str__(self) -> str:
-        return f"{self.whitespace}{self.text}{self.node or ''}{self.suffix}"
+        if self.last:
+            return f"{self.whitespace}{self.text}{self.node or ''}"
+        else:
+            return (
+                f"{self.whitespace}{self.text}{self.node or ''}{self.suffix.rstrip()}"
+            )
 
 
 def traverse(
@@ -493,17 +499,28 @@ def iter_rich_args(rich_args: Any) -> Iterable[Union[Any, Tuple[str, Any]]]:
                     yield arg
 
         if hasattr(obj, "__rich_repr__"):
+            angular = getattr(obj.__rich_repr__, "angular", False)
             args = list(iter_rich_args(obj.__rich_repr__()))
+            class_name = obj.__class__.__name__
 
             if args:
                 children = []
                 append = children.append
-                node = Node(
-                    open_brace=f"{obj.__class__.__name__}(",
-                    close_brace=")",
-                    children=children,
-                    last=root,
-                )
+                if angular:
+                    node = Node(
+                        open_brace=f"<{class_name} ",
+                        close_brace=">",
+                        children=children,
+                        last=root,
+                        separator=" ",
+                    )
+                else:
+                    node = Node(
+                        open_brace=f"{class_name}(",
+                        close_brace=")",
+                        children=children,
+                        last=root,
+                    )
                 for last, arg in loop_last(args):
                     if isinstance(arg, tuple):
                         key, child = arg
@@ -518,7 +535,9 @@ def iter_rich_args(rich_args: Any) -> Iterable[Union[Any, Tuple[str, Any]]]:
                         append(child_node)
             else:
                 node = Node(
-                    value_repr=f"{obj.__class__.__name__}()", children=[], last=root
+                    value_repr=f"<{class_name}>" if angular else f"{class_name}()",
+                    children=[],
+                    last=root,
                 )
         elif _is_attr_object(obj):
             children = []

diff --git a/rich/region.py b/rich/region.py
@@ -7,18 +7,4 @@ class Region(NamedTuple):
     x: int
     y: int
     width: int
-    height: int
-
-    def contains(self, x: int, y: int) -> bool:
-        """Check if a point is in the region.
-
-        Args:
-            x (int): X coordinate (column)
-            y (int): Y coordinate (row)
-
-        Returns:
-            bool: True if the point is within the region.
-        """
-        return ((self.x + self.width) > x >= self.x) and (
-            ((self.y + self.height) > y >= self.y)
-        )
+    height: int