Merge pull request #25 from python-tableformatter/data_types

Improved handling of common data types and documented supported data types

Author: tleonhardt

README.md

@@ -69,6 +69,23 @@ print(tf.generate_table(rows))
 
 *NOTE: Rendering of tables looks much better in Python than it appears in this Markdown file.*
 
+See the [simple_text.py](https://github.com/python-tableformatter/tableformatter/blob/master/examples/simple_text.py) and
+[simple_object.py](https://github.com/python-tableformatter/tableformatter/blob/master/examples/simple_object.py) examples
+for more basic usage.
+
+## Supported Data Types
+The following tabular data types are supported:
+* list of lists or another iterable of iterables
+* two-dimensional NumPy arrays
+* NumPy record arrays (names as columns)
+* pandas.DataFrame
+* list or another iterable of arbitrary non-iterable objects (column specifier required) 
+* list or another iterable of dicts (dict keys iterated through as rows where each key must be a hashable iterable)
+* dict of iterables (keys as columns)
+
+See the [data_types.py](https://github.com/python-tableformatter/tableformatter/blob/master/examples/data_types.py) 
+example for more info.
+
 
 ## Column Headers
 The second argument to ``generate_table`` named ``columns`` is optional and defines a list of column headers to be used.
@@ -88,7 +105,6 @@ print(tf.generate_table(rows, cols))
 ╚══════╧══════╧══════╧══════╝
 ```
 
-
 ## Grid Style
 The third argument to ``generated`` table named ``grid_style`` is optional and specifies how the table lines are drawn.
 

examples/data_types.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python
+# coding=utf-8
+"""
+tableformatter supports and has been tested with the following tabular data types:
+* list of lists or another iterable of iterables
+* two-dimensional NumPy arrays
+* NumPy record arrays (names as columns)
+* pandas.DataFrame
+* list or another iterable of arbitrary non-iterable objects (column specifier required)
+* list or another iterable of dicts (dict keys iterated through as rows where each key must be a hashable iterable)
+* dict of iterables (keys as columns)
+
+This example demonstrates tableformatter working with these data types in the simplest possible manner.
+"""
+from collections import OrderedDict
+import numpy as np
+import pandas as pd
+import tableformatter as tf
+
+iteralbe_of_iterables = [[1, 2, 3, 4],
+                         [5, 6, 7, 8]]
+print("Data type: iterable of iterables")
+print(iteralbe_of_iterables)
+print(tf.generate_table(iteralbe_of_iterables))
+
+np_2d_array = np.array([[1, 2, 3, 4],
+                        [5, 6, 7, 8]])
+print("Data type: NumPy 2D array")
+print(np_2d_array)
+print(tf.generate_table(np_2d_array))
+
+np_rec_array = np.rec.array([(1, 2., 'Hello'),
+                             (2, 3., "World")],
+                            dtype=[('foo', 'i4'), ('bar', 'f4'), ('baz', 'U10')])
+print("Data type: Numpy record array")
+print(np_rec_array)
+print(tf.generate_table(np_rec_array))
+
+d = {'col1': [1, 5], 'col2': [2, 6], 'col3': [3, 7], 'col4': [4, 8]}
+od = OrderedDict(sorted(d.items(), key=lambda t: t[0]))
+pandas_dataframe = pd.DataFrame(data=od)
+print("Data type: Pandas DataFrame")
+print(pandas_dataframe)
+print(tf.generate_table(pandas_dataframe))
+
+d1 = {1: 'a', 2: 'b', 3: 'c', 4: 'd'}
+d2 = {5: 'e', 6: 'f', 7: 'g', 8: 'h'}
+iterable_of_dicts = [ OrderedDict(sorted(d1.items(), key=lambda t: t[0])),
+                      OrderedDict(sorted(d2.items(), key=lambda t: t[0]))]
+print("Data type: iterable of dicts (dict keys iterated through as column values)")
+print(iterable_of_dicts)
+print(tf.generate_table(iterable_of_dicts))
+
+dict_of_iterables = od
+print("Data type: dict of iterables (dict keys iterated through as rows where each key must be a hashable iterable)")
+print(dict_of_iterables)
+print(tf.generate_table(dict_of_iterables))
+
+
+class MyRowObject(object):
+    """Simple object to demonstrate using a list of non-iterable objects with TableFormatter"""
+    def __init__(self, field1: int, field2: int, field3: int, field4: int):
+        self.field1 = field1
+        self.field2 = field2
+        self._field3 = field3
+        self.field4 = field4
+
+    def get_field3(self):
+        """Demonstrates accessing object functions"""
+        return self._field3
+
+
+rows = [MyRowObject(1, 2, 3, 4),
+        MyRowObject(5, 6, 7, 8)]
+columns = (tf.Column('Col1', attrib='field1'),
+           tf.Column('Col2', attrib='field2'),
+           tf.Column('Col3', attrib='get_field3'),
+           tf.Column('Col4', attrib='field4'))
+print("Data type: iterable of arbitrary non-iterable objects")
+print(rows)
+print(tf.generate_table(rows, columns))

tableformatter.py

@@ -4,6 +4,7 @@
 """
 import abc
 import enum
+import itertools
 import re
 import textwrap as textw
 from typing import List, Iterable, Optional, Tuple, Union, Callable
@@ -615,6 +616,33 @@ def generate_table(rows: Iterable[Union[Iterable, object]],
     :param row_tagger: decorator function to apply per-row options
     :return: formatted string containing the table
     """
+    # If a dictionary is passed in, then treat keys as column headers and values as column values
+    if isinstance(rows, dict):
+        if not columns:
+            columns = rows.keys()
+        rows = list(itertools.zip_longest(*rows.values()))  # columns have to be transposed
+
+    # Extract column headers if this is a NumPy record array and columns weren't specified
+    if not columns:
+        try:
+            import numpy as np
+        except ImportError:
+            pass
+        else:
+            if isinstance(rows, np.recarray):
+                columns = rows.dtype.names
+
+    # Deal with Pandas DataFrames not being iterable in a sane way
+    try:
+        import pandas as pd
+    except ImportError:
+        pass
+    else:
+        if isinstance(rows, pd.DataFrame):
+            if not columns:
+                columns = rows.columns
+            rows = rows.values
+
     show_headers = True
     use_attrib = False
     if isinstance(columns, Collection) and len(columns) > 0:

tests/test_data_types.py

@@ -0,0 +1,109 @@
+# coding=utf-8
+"""
+Unit testing the variety of data types supported by tableformatter.
+"""
+from collections import OrderedDict
+import tableformatter as tf
+
+
+EXPECTED_BASIC = '''
+╔═══╤═══╤═══╤═══╗
+║ 1 │ 2 │ 3 │ 4 ║
+║ 5 │ 6 │ 7 │ 8 ║
+╚═══╧═══╧═══╧═══╝
+'''.lstrip('\n')
+
+EXPECTED_WITH_HEADERS = '''
+╔══════╤══════╤══════╤══════╗
+║ col1 │ col2 │ col3 │ col4 ║
+╠══════╪══════╪══════╪══════╣
+║ 1    │ 2    │ 3    │ 4    ║
+║ 5    │ 6    │ 7    │ 8    ║
+╚══════╧══════╧══════╧══════╝
+'''.lstrip('\n')
+
+iteralbe_of_iterables = [[1, 2, 3, 4],
+                         [5, 6, 7, 8]]
+d = {'col1': [1, 5], 'col2': [2, 6], 'col3': [3, 7], 'col4': [4, 8]}
+od = OrderedDict(sorted(d.items(), key=lambda t: t[0]))
+
+
+def test_iterable_of_iterables():
+    table = tf.generate_table(iteralbe_of_iterables)
+    assert table == EXPECTED_BASIC
+
+
+def test_iterable_of_dicts():
+    d1 = {1: 'a', 2: 'b', 3: 'c', 4: 'd'}
+    d2 = {5: 'e', 6: 'f', 7: 'g', 8: 'h'}
+    iterable_of_dicts = [OrderedDict(sorted(d1.items(), key=lambda t: t[0])),
+                         OrderedDict(sorted(d2.items(), key=lambda t: t[0]))]
+    table = tf.generate_table(iterable_of_dicts)
+    assert table == EXPECTED_BASIC
+
+
+def test_dict_of_iterables():
+    table = tf.generate_table(od)
+    assert table == EXPECTED_WITH_HEADERS
+
+
+class MyRowObject(object):
+    """Simple object to demonstrate using a list of non-iterable objects with TableFormatter"""
+    def __init__(self, field1: int, field2: int, field3: int, field4: int):
+        self.field1 = field1
+        self.field2 = field2
+        self._field3 = field3
+        self.field4 = field4
+
+    def get_field3(self):
+        """Demonstrates accessing object functions"""
+        return self._field3
+
+
+def test_iterable_of_non_iterable_objects():
+    rows = [MyRowObject(1, 2, 3, 4),
+            MyRowObject(5, 6, 7, 8)]
+    columns = (tf.Column('col1', attrib='field1'),
+               tf.Column('col2', attrib='field2'),
+               tf.Column('col3', attrib='get_field3'),
+               tf.Column('col4', attrib='field4'))
+    table = tf.generate_table(rows, columns)
+    assert table == EXPECTED_WITH_HEADERS
+
+
+try:
+    import numpy as np
+except ImportError:
+    pass
+else:
+    np_2d_array = np.array(iteralbe_of_iterables)
+
+    def test_numpy_2d_array():
+        table = tf.generate_table(np_2d_array)
+        assert table == EXPECTED_BASIC
+
+    def test_numpy_record_array():
+        np_rec_array = np.rec.array([(1, 2., 'Hello'),
+                                     (2, 3., "World")],
+                                    dtype=[('foo', 'i4'), ('bar', 'f4'), ('baz', 'U10')])
+        table = tf.generate_table(np_rec_array)
+        expected = '''
+╔═════╤═════╤═══════╗
+║ foo │ bar │ baz   ║
+╠═════╪═════╪═══════╣
+║ 1   │ 2.0 │ Hello ║
+║ 2   │ 3.0 │ World ║
+╚═════╧═════╧═══════╝
+'''.lstrip('\n')
+        assert table == expected
+
+try:
+    import pandas as pd
+except ImportError:
+    pass
+else:
+    df = pd.DataFrame(data=od)
+
+    def test_pandas_dataframe():
+        table = tf.generate_table(df)
+        assert table == EXPECTED_WITH_HEADERS

tox.ini

@@ -21,6 +21,8 @@ commands =
 [testenv:py35]
 deps =
   codecov
+  numpy
+  pandas
   pytest
   pytest-cov
 commands =
@@ -29,12 +31,16 @@ commands =
 
 [testenv:py35-win]
 deps =
+  numpy
+  pandas
   pytest
 commands = py.test -v
 
 [testenv:py36]
 deps =
   codecov
+  numpy
+  pandas
   pytest
   pytest-cov
 commands =
@@ -44,6 +50,8 @@ commands =
 [testenv:py36-win]
 deps =
   codecov
+  numpy
+  pandas
   pytest
   pytest-cov
 commands =
@@ -52,6 +60,8 @@ commands =
 
 [testenv:py37]
 deps =
+  numpy
+  pandas
   pytest
 commands = py.test -v