auto repr

docs/source/pretty.rst

@@ -67,24 +67,28 @@ Rich Repr Protocol
 
 Rich is able to syntax highlight any output, but the formatting 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. To add Rich formatting capabilities to custom objects, you can implement the *rich repr protocol*.
 
+Run the following command to see an example of what the Rich repr protocol can generate::
+
+    python -m rich.repr
+
 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
+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 __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)
+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::
 
@@ -168,6 +172,45 @@ This will change the output of the Rich repr example to the following::
 
 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 more third-party libraries will adopt Rich repr methods in the future.
 
+Automatic Rich Repr
+~~~~~~~~~~~~~~~~~~~
+
+Rich can generate a rich repr automatically if the parameters are named the same as your attributes. 
+
+To automatically build a rich repr, use the :meth:`~rich.repr.auto` class decorator. The Bird example above follows the above rule, so we wouldn't even need to implement our own `__rich_repr__`::
+
+    import rich.repr
+
+    @rich.repr.auto
+    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
+
+
+    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)
+    }
+    from rich import print
+    print(BIRDS)
+
+Note that the decorator will also create a `__repr__`, so you you will get an auto-generated repr even if you don't print with Rich.
+
+If you want to auto-generate the angular type of repr, then set ``angular=True`` on the decorator::
+
+    @rich.repr.auto(angular=True)
+    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
+
+
 Example
 -------