Merge pull request #456 from python-cmd2/table_display0.9.2

table_display.py example now uses tableformatter instead of tabulate

6 files changed, 166 insertions, 36 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0acaf6df..556d02c3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,4 @@
-## 0.9.2 (TBD, 2018)
+## 0.9.2 (June 28, 2018)
 * Bug Fixes
     * Fixed issue where piping and redirecting did not work correctly with paths that had spaces
 * Enhancements
@@ -9,6 +9,8 @@
     * Added ``chop`` argument to ``cmd2.Cmd.ppaged()`` method for displaying output using a pager
         * If ``chop`` is ``False``, then ``self.pager`` is used as the pager
         * Otherwise ``self.pager_chop`` is used as the pager
+    * Greatly improved the [table_display.py](https://github.com/python-cmd2/cmd2/blob/master/examples/table_display.py) example
+        * Now uses the new [tableformatter](https://github.com/python-tableformatter/tableformatter) module which looks better than ``tabulate``
 * Deprecations
     * The ``CmdResult`` helper class is *deprecated* and replaced by the improved ``CommandResult`` class
         * ``CommandResult`` has the following attributes: **stdout**, **stderr**, and **data**
diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py
index 85439927..9c36a975 100644
--- a/cmd2/cmd2.py
+++ b/cmd2/cmd2.py
@@ -114,7 +114,7 @@ try:
 except ImportError:  # pragma: no cover
     ipython_available = False
 
-__version__ = '0.9.2a'
+__version__ = '0.9.2'
 
 
 # optional attribute, when tagged on a function, allows cmd2 to categorize commands
diff --git a/docs/conf.py b/docs/conf.py
index 25ba2a78..45639f58 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -62,7 +62,7 @@ author = 'Catherine Devlin and Todd Leonhardt'
 # The short X.Y version.
 version = '0.9'
 # The full version, including alpha/beta/rc tags.
-release = '0.9.2a'
+release = '0.9.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/examples/table_display.py b/examples/table_display.py
index 2e6ea804..75eada85 100755
--- a/examples/table_display.py
+++ b/examples/table_display.py
@@ -1,36 +1,145 @@
 #!/usr/bin/env python
 # coding=utf-8
 """A simple example demonstrating the following:
-    1) How to display tabular data within a cmd2 application
+    1) How to display tabular data
     2) How to display output using a pager
 
 NOTE: IF the table does not entirely fit within the screen of your terminal, then it will be displayed using a pager.
 You can use the arrow keys (left, right, up, and down) to scroll around the table as well as the PageUp/PageDown keys.
 You can quit out of the pager by typing "q".  You can also search for text within the pager using "/".
 
-WARNING: This example requires the tabulate module.
+WARNING: This example requires the tableformatter module: https://github.com/python-tableformatter/tableformatter
+- pip install tableformatter
 """
-import functools
+import argparse
+from typing import Tuple
 
 import cmd2
-import tabulate
+import tableformatter as tf
 
-# Format to use with tabulate module when displaying tables
-TABLE_FORMAT = 'grid'
+# Configure colors for when users chooses the "-c" flag to enable color in the table output
+try:
+    from colored import bg
+    BACK_PRI = bg(4)
+    BACK_ALT = bg(22)
+except ImportError:
+    try:
+        from colorama import Back
+        BACK_PRI = Back.LIGHTBLUE_EX
+        BACK_ALT = Back.LIGHTYELLOW_EX
+    except ImportError:
+        BACK_PRI = ''
+        BACK_ALT = ''
+
+
+# Formatter functions
+def no_dec(num: float) -> str:
+    """Format a floating point number with no decimal places."""
+    return "{}".format(round(num))
+
+
+def two_dec(num: float) -> str:
+    """Format a floating point number with 2 decimal places."""
+    return "{0:.2f}".format(num)
 
-# Create a function to format a fixed-width table for pretty-printing using the desired table format
-table = functools.partial(tabulate.tabulate, tablefmt=TABLE_FORMAT)
 
 # Population data from Wikipedia: https://en.wikipedia.org/wiki/List_of_cities_proper_by_population
-EXAMPLE_DATA = [['Shanghai', 'Shanghai', 'China', 'Asia', 24183300, 6340.5, 3814],
-                ['Beijing', 'Hebei', 'China', 'Asia', 20794000, 1749.57, 11885],
-                ['Karachi', 'Sindh', 'Pakistan', 'Asia', 14910352, 615.58, 224221],
-                ['Shenzen', 'Guangdong', 'China', 'Asia', 13723000, 1493.32, 9190],
-                ['Guangzho', 'Guangdong', 'China', 'Asia', 13081000, 1347.81, 9705],
-                ['Mumbai', ' Maharashtra', 'India', 'Asia', 12442373, 465.78, 27223],
-                ['Istanbul', 'Istanbul', 'Turkey', 'Eurasia', 12661000, 620.29, 20411],
-                ]
-EXAMPLE_HEADERS = ['City', 'Province', 'Country', 'Continent', 'Population', 'Area (km^2)', 'Pop. Density (/km^2)']
+
+# ############ Table data formatted as an iterable of iterable fields ############
+EXAMPLE_ITERABLE_DATA = [['Shanghai (上海)', 'Shanghai', 'China', 'Asia', 24183300, 6340.5],
+                         ['Beijing (北京市)', 'Hebei', 'China', 'Asia', 20794000, 1749.57],
+                         ['Karachi (کراچی)', 'Sindh', 'Pakistan', 'Asia', 14910352, 615.58],
+                         ['Shenzen (深圳市)', 'Guangdong', 'China', 'Asia', 13723000, 1493.32],
+                         ['Guangzho (广州市)', 'Guangdong', 'China', 'Asia', 13081000, 1347.81],
+                         ['Mumbai (मुंबई)', 'Maharashtra', 'India', 'Asia', 12442373, 465.78],
+                         ['Istanbul (İstanbuld)', 'Istanbul', 'Turkey', 'Eurasia', 12661000, 620.29],
+                        ]
+
+# Calculate population density
+for row in EXAMPLE_ITERABLE_DATA:
+    row.append(row[-2]/row[-1])
+
+
+# Column headers plus optional formatting info for each column
+COLUMNS = [tf.Column('City', width=11, header_halign=tf.ColumnAlignment.AlignCenter),
+           tf.Column('Province', header_halign=tf.ColumnAlignment.AlignCenter),
+           'Country',  # NOTE: If you don't need any special effects, you can just pass a string
+           tf.Column('Continent', cell_halign=tf.ColumnAlignment.AlignCenter),
+           tf.Column('Population', cell_halign=tf.ColumnAlignment.AlignRight, formatter=tf.FormatCommas()),
+           tf.Column('Area (km²)', width=7, header_halign=tf.ColumnAlignment.AlignCenter,
+                     cell_halign=tf.ColumnAlignment.AlignRight, formatter=two_dec),
+           tf.Column('Pop. Density (/km²)', width=12, header_halign=tf.ColumnAlignment.AlignCenter,
+                     cell_halign=tf.ColumnAlignment.AlignRight, formatter=no_dec),
+          ]
+
+
+# ######## Table data formatted as an iterable of python objects #########
+
+class CityInfo(object):
+    """City information container"""
+    def __init__(self, city: str, province: str, country: str, continent: str, population: int, area: float):
+        self.city = city
+        self.province = province
+        self.country = country
+        self.continent = continent
+        self._population = population
+        self._area = area
+
+    def get_population(self):
+        """Population of the city"""
+        return self._population
+
+    def get_area(self):
+        """Area of city in km²"""
+        return self._area
+
+
+def pop_density(data: CityInfo) -> str:
+    """Calculate the population density from the data entry"""
+    if not isinstance(data, CityInfo):
+        raise AttributeError("Argument to pop_density() must be an instance of CityInfo")
+    return no_dec(data.get_population() / data.get_area())
+
+
+# Convert the Iterable of Iterables data to an Iterable of non-iterable objects for demonstration purposes
+EXAMPLE_OBJECT_DATA = []
+for city_data in EXAMPLE_ITERABLE_DATA:
+    # Pass all city data other than population density to construct CityInfo
+    EXAMPLE_OBJECT_DATA.append(CityInfo(*city_data[:-1]))
+
+# If table entries are python objects, all columns must be defined with the object attribute to query for each field
+#   - attributes can be fields or functions. If a function is provided, the formatter will automatically call
+#     the function to retrieve the value
+OBJ_COLS = [tf.Column('City', attrib='city', header_halign=tf.ColumnAlignment.AlignCenter),
+            tf.Column('Province', attrib='province', header_halign=tf.ColumnAlignment.AlignCenter),
+            tf.Column('Country', attrib='country'),
+            tf.Column('Continent', attrib='continent', cell_halign=tf.ColumnAlignment.AlignCenter),
+            tf.Column('Population', attrib='get_population', cell_halign=tf.ColumnAlignment.AlignRight,
+                      formatter=tf.FormatCommas()),
+            tf.Column('Area (km²)', attrib='get_area', width=7, header_halign=tf.ColumnAlignment.AlignCenter,
+                      cell_halign=tf.ColumnAlignment.AlignRight, formatter=two_dec),
+            tf.Column('Pop. Density (/km²)', width=12, header_halign=tf.ColumnAlignment.AlignCenter,
+                      cell_halign=tf.ColumnAlignment.AlignRight, obj_formatter=pop_density),
+           ]
+
+
+EXTREMELY_HIGH_POULATION_DENSITY = 25000
+
+
+def high_density_tuples(row_tuple: Tuple) -> dict:
+    """Color rows with extremely high population density red."""
+    opts = dict()
+    if len(row_tuple) >= 7 and row_tuple[6] > EXTREMELY_HIGH_POULATION_DENSITY:
+        opts[tf.TableFormatter.ROW_OPT_TEXT_COLOR] = tf.TableColors.TEXT_COLOR_RED
+    return opts
+
+
+def high_density_objs(row_obj: CityInfo) -> dict:
+    """Color rows with extremely high population density red."""
+    opts = dict()
+    if float(pop_density(row_obj)) > EXTREMELY_HIGH_POULATION_DENSITY:
+        opts[tf.TableFormatter.ROW_OPT_TEXT_COLOR] = tf.TableColors.TEXT_COLOR_RED
+    return opts
 
 
 class TableDisplay(cmd2.Cmd):
@@ -39,26 +148,45 @@ class TableDisplay(cmd2.Cmd):
     def __init__(self):
         super().__init__()
 
-    def ptable(self, tabular_data, headers=()):
+    def ptable(self, rows, columns, grid_args, row_stylist):
         """Format tabular data for pretty-printing as a fixed-width table and then display it using a pager.
 
-        :param tabular_data: required argument - can be a list-of-lists (or another iterable of iterables), a list of
-                             named tuples, a dictionary of iterables, an iterable of dictionaries, a two-dimensional
-                             NumPy array, NumPy record array, or a Pandas dataframe.
-        :param headers: (optional) - to print nice column headers, supply this argument:
-                        - headers can be an explicit list of column headers
-                        - if `headers="firstrow"`, then the first row of data is used
-                        - if `headers="keys"`, then dictionary keys or column indices are used
-                        - Otherwise, a headerless table is produced
+        :param rows: required argument - can be a list-of-lists (or another iterable of iterables), a two-dimensional
+                             NumPy array, or an Iterable of non-iterable objects
+        :param columns: column headers and formatting options per column
+        :param grid_args: argparse arguments for formatting the grid
+        :param row_stylist: function to determine how each row gets styled
         """
-        formatted_table = table(tabular_data, headers=headers)
-        self.ppaged(formatted_table)
+        if grid_args.color:
+            grid = tf.AlternatingRowGrid(BACK_PRI, BACK_ALT)
+        elif grid_args.fancy:
+            grid = tf.FancyGrid()
+        elif grid_args.sparse:
+            grid = tf.SparseGrid()
+        else:
+            grid = None
+
+        formatted_table = tf.generate_table(rows=rows, columns=columns, grid_style=grid, row_tagger=row_stylist)
+        self.ppaged(formatted_table, chop=True)
+
+    table_parser = argparse.ArgumentParser()
+    table_item_group = table_parser.add_mutually_exclusive_group()
+    table_item_group.add_argument('-c', '--color', action='store_true', help='Enable color')
+    table_item_group.add_argument('-f', '--fancy', action='store_true', help='Fancy Grid')
+    table_item_group.add_argument('-s', '--sparse', action='store_true', help='Sparse Grid')
+
+    @cmd2.with_argparser(table_parser)
+    def do_table(self, args):
+        """Display data in iterable form on the Earth's most populated cities in a table."""
+        self.ptable(EXAMPLE_ITERABLE_DATA, COLUMNS, args, high_density_tuples)
 
-    def do_table(self, _):
-        """Display data on the Earth's most populated cities in a table."""
-        self.ptable(tabular_data=EXAMPLE_DATA, headers=EXAMPLE_HEADERS)
+    @cmd2.with_argparser(table_parser)
+    def do_object_table(self, args):
+        """Display data in object form on the Earth's most populated cities in a table."""
+        self.ptable(EXAMPLE_OBJECT_DATA, OBJ_COLS, args, high_density_objs)
 
 
 if __name__ == '__main__':
     app = TableDisplay()
+    app.debug = True
     app.cmdloop()
diff --git a/setup.py b/setup.py
index 59c53b68..a1ae363c 100755
--- a/setup.py
+++ b/setup.py
@@ -5,7 +5,7 @@ Setuptools setup file, used to install or test 'cmd2'
 """
 from setuptools import setup
 
-VERSION = '0.9.2a'
+VERSION = '0.9.2'
 DESCRIPTION = "cmd2 - a tool for building interactive command line applications in Python"
 LONG_DESCRIPTION = """cmd2 is a tool for building interactive command line applications in Python. Its goal is to make
 it quick and easy for developers to build feature-rich and user-friendly interactive command line applications.  It
diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py
index 94cd42f9..9ad61378 100644
--- a/tests/test_cmd2.py
+++ b/tests/test_cmd2.py
@@ -29,7 +29,7 @@ from .conftest import run_cmd, normalize, BASE_HELP, BASE_HELP_VERBOSE, \
 
 
 def test_ver():
-    assert cmd2.__version__ == '0.9.2a'
+    assert cmd2.__version__ == '0.9.2'
 
 
 def test_empty_statement(base_app):