mirror of https://github.com/Textualize/rich.git
38 lines
1.9 KiB
ReStructuredText
38 lines
1.9 KiB
ReStructuredText
|
Console Protocol
|
||
|
|
================
|
||
|
|
|
||
|
|
Rich supports a simple protocol to add rich formatting capabilities to custom objects, so you can :meth:`~rich.console.Console.print` your object with color, styles and formatting.
|
||
|
|
|
||
|
|
You can use this for presentation or to display additional debugging information that might be hard to parse from a ``__repr__`` output.
|
||
|
|
|
||
|
|
|
||
|
|
Console Str
|
||
|
|
-----------
|
||
|
|
|
||
|
|
The easiest way to add console output to your custom object is to implement a ``__console_str__`` method. This method accepts no arguments, and should return a :class:`~rich.text.Text` instance. Here's an example::
|
||
|
|
|
||
|
|
class MyObject:
|
||
|
|
def __console_str__(self) -> Text:
|
||
|
|
return Text.from_markup("[bold]MyObject()[/bold]")
|
||
|
|
|
||
|
|
If you were to print or log an instance of ``MyObject`` it would render as ``MyObject()`` in bold. Naturally, you would want to put this to better use, perhaps by adding specialized syntax highlighting.
|
||
|
|
|
||
|
|
|
||
|
|
Console Render
|
||
|
|
--------------
|
||
|
|
|
||
|
|
The ``__console_str__`` method is limited to styled text. For more advanced rendering, Rich supports a ``__console__`` method which you can use to render custom output with other renderable objects. For instance, a complex data type might be best represented as a :class:`~rich.table.Table`.
|
||
|
|
|
||
|
|
The ``__console__`` method should accept a :class:`~rich.console.Console` and a :class:`~rich.console.ConsoleOptions` instance. It should return an iterable of other renderable objects. Although that means it *could* return a container such as a list, it is customary to ``yield`` output (making the method a generator)
|
||
|
|
|
||
|
|
Here's an example of a ``__console__`` method::
|
||
|
|
|
||
|
|
class MyObject:
|
||
|
|
def __console__(self, console: Console, options: ConsoleOptions) -> Iterable[Table]:
|
||
|
|
my_table = Table("Key, "Value")
|
||
|
|
my_table.add_row("foo", "bar")
|
||
|
|
my_table.add_row("egg", "baz")
|
||
|
|
yield my_table
|
||
|
|
|
||
|
|
If you were to print a ``MyObject`` instance, it would render a simple table to the terminal.
|