columns docs and examples

docs/source/columns.rst

@@ -0,0 +1,23 @@
+Columns
+=======
+
+Rich can render text or other Rich renderables in neat columns with the :class:`~rich.columns.Columns` class. To use, construct a Columns instance with an iterable of renderables and print it to the Console.
+
+The following example is a very basic clone of the `ls` command in OSX / Linux to list directory contents::
+
+    import os
+    import sys
+
+    from rich import print
+    from rich.columns import Columns
+
+    if len(sys.argv) < 2:
+        print("Usage: python columns.py DIRECTORY")
+    else:
+        directory = os.listdir(sys.argv[1])
+        columns = Columns(directory, equal=True, expand=True)
+        print(columns)
+
+
+See `columns.py <https://github.com/willmcgugan/rich/blob/master/examples/columns.py>`_ for an example which outputs columns with more than just text. 
+

docs/source/index.rst

@@ -18,6 +18,7 @@ Welcome to Rich's documentation!
    markup.rst
    tables.rst
    panel.rst
+   columns.rst
    logging.rst
    progress.rst
    markdown.rst

docs/source/reference.rst

@@ -7,6 +7,7 @@ Reference
    reference/align.rst
    reference/bar.rst
    reference/color.rst
+   reference/columns.rst
    reference/console.rst
    reference/emoji.rst
    reference/highlighter.rst

docs/source/reference/columns.rst

@@ -0,0 +1,7 @@
+rich.columns
+============
+
+.. automodule:: rich.columns
+    :members:
+
+

examples/columns.py

@@ -0,0 +1,20 @@
+from rich import print
+from rich.columns import Columns
+from rich.panel import Panel
+
+import json
+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
+]
+
+print(Columns(user_renderables))

examples/listdir.py

@@ -0,0 +1,12 @@
+import os
+import sys
+
+from rich import print
+from rich.columns import Columns
+
+if len(sys.argv) < 2:
+    print("Usage: python columns.py DIRECTORY")
+else:
+    directory = os.listdir(sys.argv[1])
+    columns = Columns(directory, equal=True, expand=True)
+    print(columns)

rich/columns.py

@@ -17,6 +17,7 @@ class Columns(JupyterMixin):
         renderables (Iterable[RenderableType]): Any number of Rich renderables (including str),
         padding (PaddingDimensions, optional): Optional padding around cells. Defaults to (0, 1).
         expand (bool, optional): Expand columns to full width. Defaults to False.
+        equal (bool, optional): Arrange in to equal sized columns. Defaults to False.
         column_first (bool, optional): Align items from top to bottom (rather than left to right). Defaults to False.
         right_to_left (bool, optional): Start column from right hand side. Defaults to False.
     """

tests/test_columns.py

@@ -0,0 +1,57 @@
+import io
+
+from rich.columns import Columns
+from rich.console import Console
+
+COLUMN_DATA = [
+    "Ursus americanus",
+    "American buffalo",
+    "Bison bison",
+    "American crow",
+    "Corvus brachyrhynchos",
+    "American marten",
+    "Martes americana",
+    "American racer",
+    "Coluber constrictor",
+    "American woodcock",
+    "Scolopax minor",
+    "Anaconda (unidentified)",
+    "Eunectes sp.",
+    "Andean goose",
+    "Chloephaga melanoptera",
+    "Ant",
+    "Anteater, australian spiny",
+    "Tachyglossus aculeatus",
+    "Anteater, giant",
+    "Myrmecophaga tridactyla",
+]
+
+
+def render():
+    console = Console(file=io.StringIO(), width=100)
+    columns = Columns(COLUMN_DATA)
+    console.print(columns)
+    console.print()
+    columns.column_first = True
+    console.print(columns)
+    console.print()
+    columns.right_to_left = True
+    console.print(columns)
+    console.print()
+    columns.equal = True
+    columns.expand = True
+    console.print(columns)
+    console.print()
+    render_result = console.file.getvalue()
+    return render_result
+
+
+def test_render():
+    expected = "Ursus americanus           American buffalo       Bison bison            American crow          \nCorvus brachyrhynchos      American marten        Martes americana       American racer         \nColuber constrictor        American woodcock      Scolopax minor         Anaconda (unidentified)\nEunectes sp.               Andean goose           Chloephaga melanoptera Ant                    \nAnteater, australian spiny Tachyglossus aculeatus Anteater, giant        Myrmecophaga tridactyla\n\nUrsus americanus           Corvus brachyrhynchos   Coluber constrictor Eunectes sp.           \nAnteater, australian spiny American buffalo        American marten     American woodcock      \nAndean goose               Tachyglossus aculeatus  Bison bison         Martes americana       \nScolopax minor             Chloephaga melanoptera  Anteater, giant     American crow          \nAmerican racer             Anaconda (unidentified) Ant                 Myrmecophaga tridactyla\n\nEunectes sp.            Coluber constrictor Corvus brachyrhynchos   Ursus americanus          \nAmerican woodcock       American marten     American buffalo        Anteater, australian spiny\nMartes americana        Bison bison         Tachyglossus aculeatus  Andean goose              \nAmerican crow           Anteater, giant     Chloephaga melanoptera  Scolopax minor            \nMyrmecophaga tridactyla Ant                 Anaconda (unidentified) American racer            \n\nMartes americana                 American crow                     Ursus americanus                 \nAnt                              Eunectes sp.                      American woodcock                \nCorvus brachyrhynchos            American buffalo                  Anteater, giant                  \nAndean goose                     Scolopax minor                    American racer                   \nBison bison                      Myrmecophaga tridactyla           Anteater, australian spiny       \nAnaconda (unidentified)          Coluber constrictor               American marten                  \n                                 Tachyglossus aculeatus            Chloephaga melanoptera           \n\n"
+    assert render() == expected
+
+
+if __name__ == "__main__":
+    result = render()
+    print(result)
+    print(repr(result))