diff --git a/README.md b/README.md index 4a7b0eec..e425485d 100644 --- a/README.md +++ b/README.md @@ -126,6 +126,50 @@ To insert an emoji in to console output place the name between two colons. Here' Please use this feature wisely. +## Tables + +Rich can render flexible tables with unicode box characters. There is a large variety of formatting options for borders, styles, cell alignment etc. Here's a simple example: + +```python +from rich.console import Console +from rich.table import Column, Table + +console = Console() + +table = Table(show_header=True, header_style="bold magenta") +table.add_column("Date", style="dim", width=12) +table.add_column("Title") +table.add_column("Production Budget", justify="right") +table.add_column("Box Office", justify="right") +table.add_row( + "Dev 20, 2019", "Star Wars: The Rise of Skywalker", "$275,000,000", "$375,126,118" +) +table.add_row( + "May 25, 2018", + "[red]Solo[/red]: A Star Wars Story", + "$275,000,000", + "$393,151,347", +) +table.add_row( + "Dec 15, 2017", + "Star Wars Ep. VIII: The Last Jedi", + "$262,000,000", + "[bold]$1,332,539,889[/bold]", +) + +console.print(table) +``` + +This produces the following output: + +![table](https://github.com/willmcgugan/rich/raw/master/imgs/table.png) + +Note that console markup is rendered in the same was as `print()` and `log()`. In fact, anything that is renderable by Rich may be included in the headers / rows (even other tables). + +The `Table` class is smart enough to resize columns to fit the available width of the terminal, wrapping text as required. Here's the same example, with the terminal made smaller than the table above: + +![table2](https://github.com/willmcgugan/rich/raw/master/imgs/table2.png) + ## Progress Bars Rich can render multiple flicker-free [progress](https://rich.readthedocs.io/en/latest/progress.html) bars to track long-running tasks. @@ -149,6 +193,26 @@ The columns may be configured to show any details you want. Built-in columns inc To try this out yourself, see [examples/downloader.py](https://github.com/willmcgugan/rich/blob/master/examples/downloader.py) which can download multiple URLs simultaneously while displaying progress. +## Columns + +Rich can render content in neat [columns](https://rich.readthedocs.io/en/latest/columns.html) with equal or optimal width. Here's a very basic clone of the `ls` command with Rich: + +```python +import os + +from rich import print +from rich.columns import Columns + +directory = os.listdir(sys.argv[1]) +print(Columns(directory)) +``` + +This will displays the file names in the current directory arranged in to _optimal_ columns. + +Here's the output from the [columns example] which displays data pulled from an API in columns: + +![columns](https://github.com/willmcgugan/rich/raw/master/imgs/columns.png) + ## Markdown Rich can render [markdown](https://rich.readthedocs.io/en/latest/markdown.html) and does a reasonable job of translating the formatting to the terminal. @@ -201,50 +265,6 @@ This will produce the following output: ![syntax](https://github.com/willmcgugan/rich/raw/master/imgs/syntax.png) -## Tables - -Rich can render flexible tables with unicode box characters. There is a large variety of formatting options for borders, styles, cell alignment etc. Here's a simple example: - -```python -from rich.console import Console -from rich.table import Column, Table - -console = Console() - -table = Table(show_header=True, header_style="bold magenta") -table.add_column("Date", style="dim", width=12) -table.add_column("Title") -table.add_column("Production Budget", justify="right") -table.add_column("Box Office", justify="right") -table.add_row( - "Dev 20, 2019", "Star Wars: The Rise of Skywalker", "$275,000,000", "$375,126,118" -) -table.add_row( - "May 25, 2018", - "[red]Solo[/red]: A Star Wars Story", - "$275,000,000", - "$393,151,347", -) -table.add_row( - "Dec 15, 2017", - "Star Wars Ep. VIII: The Last Jedi", - "$262,000,000", - "[bold]$1,332,539,889[/bold]", -) - -console.print(table) -``` - -This produces the following output: - -![table](https://github.com/willmcgugan/rich/raw/master/imgs/table.png) - -Note that console markup is rendered in the same was as `print()` and `log()`. In fact, anything that is renderable by Rich may be included in the headers / rows (even other tables). - -The `Table` class is smart enough to resize columns to fit the available width of the terminal, wrapping text as required. Here's the same example, with the terminal made smaller than the table above: - -![table2](https://github.com/willmcgugan/rich/raw/master/imgs/table2.png) - ## Tracebacks Rich can render beautiful tracebacks which are easier to read and show more code than standard Python tracebacks. You can set Rich as the default traceback handler so all uncaught exceptions will be rendered by Rich. diff --git a/docs/source/columns.rst b/docs/source/columns.rst index 64a0b867..aeeda4d7 100644 --- a/docs/source/columns.rst +++ b/docs/source/columns.rst @@ -19,5 +19,5 @@ The following example is a very basic clone of the `ls` command in OSX / Linux t print(columns) -See `columns.py `_ for an example which outputs columns with more than just text. +See `columns.py `_ for an example which outputs columns containing more than just text. diff --git a/examples/columns.py b/examples/columns.py index 90a4a741..7a068f23 100644 --- a/examples/columns.py +++ b/examples/columns.py @@ -9,12 +9,14 @@ from urllib.request import urlopen users = json.loads(urlopen("https://randomuser.me/api/?results=30").read())["results"] print(users) -user_renderables = [ - Panel( - f"[b]{user['name']['first']} {user['name']['last']}[/b]\n[yellow]{user['location']['country']}", - expand=False, - ) - for user in users -] + +def get_content(user): + country = user["location"]["country"] + name = f"{user['name']['first']} {user['name']['last']}" + + return f"[b]{name}[/b]\n[yellow]{country}" + + +user_renderables = [Panel(get_content(user), expand=False,) for user in users] print(Columns(user_renderables)) diff --git a/imgs/columns.png b/imgs/columns.png new file mode 100644 index 00000000..328bbd96 Binary files /dev/null and b/imgs/columns.png differ