Merge pull request #21 from python-tableformatter/README_TODOs

anselor · web-flow · commit 2b2c9d8d299d · 2018-08-02T11:38:04.000-04:00
Completed basic documentation in README.md
diff --git a/README.md b/README.md
@@ -1,5 +1,4 @@
-tableformatter: tabular data formatter
-======================================
+# tableformatter: tabular data formatter
 [![Latest Version](https://img.shields.io/pypi/v/tableformatter.svg?style=flat-square&label=latest%20stable%20version)](https://pypi.org/project/tableformatter/)
 [![Build status](https://api.travis-ci.com/python-tableformatter/tableformatter.svg?branch=master)](https://travis-ci.com/python-tableformatter/tableformatter)
 [![Appveyor build status](https://img.shields.io/appveyor/ci/anselor/tableformatter.svg?style=flat-square&label=windows%20build)](https://ci.appveyor.com/project/anselor/tableformatter)
@@ -16,8 +15,8 @@ receive arbitrary Python objects.
 
 [![Screenshot](tf.png)](https://github.com/python-tableformatter/tableformatter/blob/master/tf.png)
 
-Main Features
--------------
+
+## Main Features
 - Easy to display simple tables with just one function call when you don't need the fine-grained control
 - Fine-grained control of almost every aspect of how data is formatted when you want it
 - Tables with column headers
@@ -28,14 +27,13 @@ Main Features
 - Support for Python 3.4+ on Windows, macOS, and Linux
 
 
-Installation
-============
+## Installation
 ```Bash
 pip install tableformatter
 ```
 
-Dependencies
-------------
+
+## Dependencies
 ``tableformatter`` depends on the [wcwidth](https://github.com/jquast/wcwidth) module for measuring the width of
 unicode strings rendered to a terminal.
 
@@ -46,20 +44,19 @@ If you wish to use the optional support for color, then at least one of the foll
 If both ``colorama`` and ``colored`` are installed, then ``colored`` will take precedence.
 
 
-Usage
-=====
+## Usage
 For simple cases, you only need to use a single function from this module: ``generate_table``.  The only required argument
 to this function is ``rows`` which is an Iterable of Iterables such as a list of lists or another tabular data type like
 a 2D [numpy](http://www.numpy.org) array.  ``generate_table`` outputs a nicely formatted table:
 
 ```Python
-from tableformatter import generate_table
+import tableformatter as tf
 
 rows = [('A1', 'A2', 'A3', 'A4'),
         ('B1', 'B2\nB2\nB2', 'B3', 'B4'),
         ('C1', 'C2', 'C3', 'C4'),
         ('D1', 'D2', 'D3', 'D4')]
-print(generate_table(rows))
+print(tf.generate_table(rows))
 ╔════╤════╤════╤════╗
 ║ A1 │ A2 │ A3 │ A4 ║
 ║ B1 │ B2 │ B3 │ B4 ║
@@ -72,13 +69,13 @@ print(generate_table(rows))
 
 *NOTE: Rendering of tables looks much better in Python than it appears in this Markdown file.*
 
-Column Headers
---------------
+
+## Column Headers
 The second argument to ``generate_table`` named ``columns`` is optional and defines a list of column headers to be used.
 
 ```Python
 cols = ['Col1', 'Col2', 'Col3', 'Col4']
-print(generate_table(rows, cols))
+print(tf.generate_table(rows, cols))
 ╔══════╤══════╤══════╤══════╗
 ║ Col1 │ Col2 │ Col3 │ Col4 ║
 ╠══════╪══════╪══════╪══════╣
@@ -91,8 +88,8 @@ print(generate_table(rows, cols))
 ╚══════╧══════╧══════╧══════╝
 ```
 
-Grid Style
-----------
+
+## Grid Style
 The third argument to ``generated`` table named ``grid_style`` is optional and specifies how the table lines are drawn.
 
 Supported grid sytles are:
@@ -102,9 +99,7 @@ Supported grid sytles are:
 * **SparseGrid** - sparse grid with no lines at all to conserve both vertical and horizontal space
 
 ```Python
-from tableformatter import FancyGrid
-
-print(generate_table(rows, grid_style=FancyGrid()))
+print(tf.generate_table(rows, grid_style=tf.FancyGrid()))
 ╔════╤════╤════╤════╗
 ║ A1 │ A2 │ A3 │ A4 ║
 ╟────┼────┼────┼────╢
@@ -118,14 +113,14 @@ print(generate_table(rows, grid_style=FancyGrid()))
 ╚════╧════╧════╧════╝
 ```
 
-Transposed Tables
------------------
+
+## Transposed Tables
 Normally the "rows" are displayed left-to-right and "columns" are displayed up-to-down.  However, if you want to transpose
 this and print "rows" up-to-down and "columns" left-to-right then that is easily done using the fourth (optional) argument
 to ``generate_table``:
 
 ```Python
-print(generate_table(rows, cols, transpose=True))
+print(tf.generate_table(rows, cols, transpose=True))
 ╔══════╦════╤════╤════╤════╗
 ║ Col1 ║ A1 │ B1 │ C1 │ D1 ║
 ║ Col2 ║ A2 │ B2 │ C2 │ D2 ║
@@ -136,14 +131,118 @@ print(generate_table(rows, cols, transpose=True))
 ╚══════╩════╧════╧════╧════╝
 ```
 
-Column Alignment
-----------------
-TODO
 
-Number Formatting
------------------
-TODO
+## Column Formatting
+For rich column formatting, instead of passing a simple iterable to the 2nd argument of ``generate_table``, an iterable
+of ``tableformatter.Column`` objects can be passed.  The ``Column`` class has the following attributes, all of which are
+optional other than the first:
+
+| Attribute name | Description |
+| -------------- | ----------- |
+| col_name       | Column name to display
+| width          | Number of displayed terminal characters. Unicode wide characters count as 2 displayed characters.
+| attrib         | The name of the object attribute to look up for cell contents on this column
+| wrap_mode      | Defines how to handle long cells that must be wrapped or truncated
+| wrap_prefix    | String to display at the beginning of each wrapped line in a cell
+| cell_padding   | Number of padding spaces to the left and right of each cell
+| header_halign  | Horizontal alignment of the column header
+| header_valign  | Vertical alignment of the column header
+| cell_halign    | Horizontal alignment of the cells in this column
+| cell_valign    | Vertical alignment of the cells in this column
+| formatter      | Callable that can process the value in this column for display
+| obj_formatter  | Callable that processes the row object to generate content for this column
+
+See the [columns.py](https://github.com/python-tableformatter/tableformatter/blob/master/examples/columns.py) example
+for a demonstration for how all of these options can be used.
+
+### Column Alignment
+You can override both the horizontal and vertical alignment.  This can be done separately for the column header versus
+the cell contents.
+
+Possible alignments are all elements within the ``ColumnAlignment`` enum class: 
+* Horizontal alignments:
+    * AlignLeft (*default*)
+    * AlignCenter
+    * AlignRight
+* Vertical alignments:
+    * AlignTop (*default*)
+    * AlignBottom
+    
+```Python
+columns = (tf.Column('Col1', cell_halign=tf.ColumnAlignment.AlignLeft),
+           tf.Column('Col2', cell_halign=tf.ColumnAlignment.AlignRight),
+           tf.Column('Col3', cell_halign=tf.ColumnAlignment.AlignCenter),
+           tf.Column('Col4', cell_valign=tf.ColumnAlignment.AlignBottom))
+print(tf.generate_table(rows, columns))
+╔══════╤══════╤══════╤══════╗
+║ Col1 │ Col2 │ Col3 │ col4 ║
+╠══════╪══════╪══════╪══════╣
+║ A1   │   A2 │  A3  │ A4   ║
+║ B1   │   B2 │  B3  │      ║
+║      │   B2 │      │      ║
+║      │   B2 │      │ B4   ║
+║ C1   │   C2 │  C3  │ C4   ║
+║ D1   │   D2 │  D3  │ D4   ║
+╚══════╧══════╧══════╧══════╝
+```    
+   
+### Number Formatting
+The ``formatter`` attribute of the ``Column`` class accepts an arbitrary callable which accepts a single argument containing
+the cell contents for that column and returns a string with the contents formatted in the
+desired format.  There are a couple callable classes built into ``tableformatter`` to help
+formatting numbers:
+* FormatBytes - formats a value in bytes into a human readable string
+* FormatCommas - Formats a number with comma separators
+
+```Python
+rows = [(None, None),
+        ('123', '123'),
+        (123, 123),
+        (12345, 12345),
+        (12345678, 12345678),
+        (1234567890, 1234567890),
+        (1234567890123, 1234567890123)]
+cols = (tf.Column('First', width=20, formatter=tf.FormatBytes(), cell_halign=tf.ColumnAlignment.AlignRight),
+        tf.Column('Second', formatter=tf.FormatCommas(), cell_halign=tf.ColumnAlignment.AlignRight))
+print(tf.generate_table(rows, cols))
+╔═══════════╤═══════════════════╗
+║ First     │ Second            ║
+╠═══════════╪═══════════════════╣
+║           │                   ║
+║ 123.00  B │               123 ║
+║ 123.00  B │               123 ║
+║  12.06 KB │            12,345 ║
+║  11.77 MB │        12,345,678 ║
+║   1.15 GB │     1,234,567,890 ║
+║   1.12 TB │ 1,234,567,890,123 ║
+╚═══════════╧═══════════════════╝
+```
+
+See the [cmd2_tables.py](https://github.com/python-tableformatter/tableformatter/blob/master/examples/formatters.py) example
+for examples of how custom formatter functions can be used.
+
+
+## Color
+If either ``colorama`` or ``colored`` is installed, then ``tableformatter`` has support for altering both the foreground
+and background color of cell contents.
+
+### Alternating background row color
+It is trivial to alternate the background color of each row as follows:
+```Python
+from colorama import Back
+print(generate_table(rows, cols, grid_style=tf.AlternatingRowGrid(Back.GREEN, Back.BLUE)))
+```
+See the [cmd2_tables.py](https://github.com/python-tableformatter/tableformatter/blob/master/examples/cmd2_tables.py) or 
+[color.py](https://github.com/python-tableformatter/tableformatter/blob/master/examples/color.py) examples for more 
+complete examples.
+
+### Dynamically setting cell color based on cell contents
+The 5th argument to ``generate_table`` is **row_tagger** and it expects a callable which accepts a single argument for
+the row contents and returns a dictionary of row options for that row which can
+be used to set the foreground and/or background color of all cells in that row.
+
+See the ``high_density_tuples`` function in the [cmd2_tables.py](https://github.com/python-tableformatter/tableformatter/blob/master/examples/cmd2_tables.py)
+example for a demonstration of how to use this feature.
+
+
 
-Color
------
-TODO
diff --git a/examples/cmd2_tables.py b/examples/cmd2_tables.py
@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 # coding=utf-8
 """A simple example demonstrating the following:
     1) How to integrate tableformatter into an interactive command-line application using the cmd2 module
@@ -31,11 +31,13 @@
 # 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:
@@ -64,12 +66,11 @@ def two_dec(num: float) -> str:
                          ['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])
-
+    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),
@@ -81,13 +82,14 @@ def two_dec(num: float) -> str:
                      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
@@ -131,8 +133,7 @@ def pop_density(data: CityInfo) -> str:
                       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
 
@@ -177,14 +178,20 @@ def ptable(self, rows, columns, grid_args, row_stylist):
         else:
             grid = None
 
-        formatted_table = tf.generate_table(rows=rows, columns=columns, grid_style=grid, row_tagger=row_stylist)
+        transpose = False
+        if grid_args.transpose:
+            transpose = True
+
+        formatted_table = tf.generate_table(rows=rows, columns=columns, grid_style=grid, row_tagger=row_stylist,
+                                            transpose=transpose)
         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')
+    table_parser.add_argument('-t', '--transpose', action='store_true', help='Transpose rows and columns')
 
     @cmd2.with_argparser(table_parser)
     def do_table(self, args):
diff --git a/tableformatter.py b/tableformatter.py
@@ -668,14 +668,14 @@ def Column(col_name: str,
     :param col_name: Column name to display
     :param width: Number of displayed terminal characters. Unicode wide characters count as 2 displayed characters.
     :param attrib: The name of the object attribute to look up for cell contents on this column
-    :param wrap_mode: Defines how to handle long cells that must be wropped or truncated
+    :param wrap_mode: Defines how to handle long cells that must be wrapped or truncated
     :param wrap_prefix: String to display at the beginning of each wrapped line in a cell
     :param cell_padding: Number of padding spaces to the left and right of each cell
     :param header_halign: Horizontal alignment of the column header
     :param header_valign: Vertical alignment of the column header
     :param cell_halign: Horizontal alignment of the cells in this column
     :param cell_valign: Vertical alignment of the cells in this column
-    :param formatter: Callable that can process the value in this column for display.
+    :param formatter: Callable that can process the value in this column for display
     :param obj_formatter: Callable that processes the row object to generate content for this column
     :return: A column tuple the TableFormatter expects
     """
