updates docs

README.md

@@ -8,7 +8,6 @@
 ## About
 `tableprint` lets you easily print pretty ASCII formatted tables of data.
 Unlike other modules, you can print single rows of data at a time (useful for printing ongoing computation results).
-Also, `tableprint` is fast (minimal processing required) and is therefore relevant for printing updates during speed-intensive computations.
 
 ## Installation
 ```bash

docs/api.rst

@@ -0,0 +1,9 @@
+.. _api:
+
+===
+API
+===
+
+.. automodule:: tableprint
+    :members:
+

docs/conf.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# TablePrint documentation build configuration file, created by
+# Tableprint documentation build configuration file, created by
 # sphinx-quickstart on Wed Sep 30 13:40:02 2015.
 #
 # This file is execfile()d with the current directory set to its
@@ -53,7 +53,7 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'TablePrint'
+project = u'Tableprint'
 copyright = u'2015, Niru Maheswaranathan'
 author = u'Niru Maheswaranathan'
 
@@ -207,7 +207,7 @@ html_static_path = ['_static']
 #html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'TablePrintdoc'
+htmlhelp_basename = 'Tableprintdoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -229,7 +229,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  (master_doc, 'TablePrint.tex', u'TablePrint Documentation',
+  (master_doc, 'Tableprint.tex', u'Tableprint Documentation',
    u'Niru Maheswaranathan', 'manual'),
 ]
 
@@ -259,7 +259,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'tableprint', u'TablePrint Documentation',
+    (master_doc, 'tableprint', u'Tableprint Documentation',
      [author], 1)
 ]
 
@@ -273,8 +273,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  (master_doc, 'TablePrint', u'TablePrint Documentation',
-   author, 'TablePrint', 'One line description of project.',
+  (master_doc, 'Tableprint', u'Tableprint Documentation',
+   author, 'Tableprint', 'One line description of project.',
    'Miscellaneous'),
 ]
 
@@ -292,4 +292,4 @@ texinfo_documents = [
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'https://docs.python.org/3': None}

docs/index.rst

@@ -1,23 +1,58 @@
-.. TablePrint documentation master file, created by
-   sphinx-quickstart on Wed Sep 30 13:40:02 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+==========
+Tableprint
+==========
 
-Welcome to TablePrint's documentation!
-======================================
+Tableprint is a library for printing out numerical data in Ascii formatted tables. Check it out on `Github`_!
 
-Contents:
+.. _Github: https://github.com/nirum/tableprint/
 
-.. toctree::
-   :maxdepth: 2
-   quickstart
-   examples
-   api
+Installation
+------------
 
-Indices and tables
-==================
+First, we need to install the module. We can do that using pip: 
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. code-block:: bash
 
+    $ pip install tableprint
+
+Quickstart
+----------
+
+Now let's see what we can do. Tableprint offers two functions that print a table directly,
+``tableprint.table`` and ``tableprint.frame``. The first takes a numpy array and a list of
+headers, whereas the second takes a pandas DataFrame as input. For example, you can do the following:
+
+.. code-block:: python
+
+    >>> tableprint.table(np.random.randn(10,3), ['A', 'B', 'C'])
+
+If you want to append to a table on the fly, you can use the functions ``tableprint.header``,
+``tableprint.row``, and ``tableprint.hr``. These functions return an ASCII formatted string
+given a list of headers, an array of data, and a number of columns, respectively. For example
+
+.. code-block:: python
+
+    >>> print(tableprint.hr(3))
+    >>> print(tableprint.header(['A', 'B', 'C']))
+    >>> print(tableprint.hr(3))
+    >>> for ix in range(10):
+
+            # insert time-intensive data collection here
+            data = np.random.randn(3)
+
+            # print data to stdout
+            print(tableprint.row(data), flush=True)
+
+    >>> print(tableprint.hr(3))
+
+API
+---
+
+Tableprint comes with a number of options, these are fully described below:
+
+.. autofunction:: tableprint.table
+.. autofunction:: tableprint.frame
+.. autofunction:: tableprint.header
+.. autofunction:: tableprint.row
+.. autofunction:: tableprint.hr
+.. autofunction:: tableprint.humantime

docs/quickstart.rst

@@ -0,0 +1,8 @@
+==========
+TablePrint
+==========
+
+`tableprint`_ is a library for printing out numerical data in Ascii formatted tables.
+
+.. _tableprint: https://github.com/nirum/tableprint/
+

tableprint.py

@@ -1,5 +1,7 @@
 """
-Module to nicely format ASCII table rows for display
+Tableprint
+
+A module to print and display ASCII formatted tables of data
 
 """
 
@@ -7,31 +9,7 @@ from __future__ import print_function
 import numpy as np
 
 # exports
-__all__ = ['table', 'row', 'header', 'frame']
-
-
-def frame(dataframe, options=None):
-    """
-    Print an ASCII table using the given pandas DataFrame
-
-    Parameters
-    ----------
-    dataframe : DataFrame
-        A pandas DataFrame with consisting of the table to print
-
-    options : dict
-        A dictionary of options. Defaults:
-        {
-            'column_width'  : 10,       # the width of each column in the table
-            'outer_char'    : '|',      # the character defining the outer border of the table
-            'corner_char'   : '+',      # printed at the junctions of the table lines
-            'line_char'     : '-',      # character as part of each horizontal rule
-            'format_spec'   : '5g'      # format_spec string for formatting numbers
-        }
-
-    """
-
-    table(np.array(dataframe), list(dataframe.columns), options)
+__all__ = ['table', 'row', 'header', 'hr', 'humantime', 'frame']
 
 
 def table(data, headers, format_spec='5g', column_width=10, outer_char='|', corner_char='+', line_char='-'):
@@ -46,41 +24,34 @@ def table(data, headers, format_spec='5g', column_width=10, outer_char='|', corn
     headers : list
         A list of n strings consisting of the header of each of the n columns
 
-    options : dict
-        A dictionary of options. Defaults:
-        {
-            'column_width'  : 10,       # the width of each column in the table
-            'outer_char'    : '|',      # the character defining the outer border of the table
-            'corner_char'   : '+',      # printed at the junctions of the table lines
-            'line_char'     : '-',      # character as part of each horizontal rule
-            'format_spec'   : '5g'      # format_spec string for formatting numbers
-        }
+    column_width : int, optional
+        The width of each column in the table (Default: 10)
+
+    outer_char : string, optional
+        The character defining the outer border of the table (Default: '|')
+
+    corner_char : string, optional
+        Printed at the junctions of the table lines (Default: '+')
+
+    line_char : string, optional
+        Character as part of each horizontal rule (Default: '-')
+
+    format_spec : string, optional
+        Format specification for formatting numbers (Default: '5g')
+
 
     """
 
-    # default options
-    opts = {
-        'column_width': 10,
-        'outer_char': '|',
-        'corner_char': '+',
-        'line_char': '-',
-        'format_spec': '5g'
-    }
-
-    # user-specified options
-    if options:
-        opts.update(options)
-
     # the hr line
-    hrule = hr(len(headers), column_width=opts['column_width'],
-               corner_char=opts['corner_char'], line_char=opts['line_char'])
+    hrule = hr(len(headers), column_width=column_width,
+               corner_char=corner_char, line_char=line_char)
 
     # get the header string
-    headerstr = [hrule, header(headers, column_width=opts['column_width'], outer_char=opts['outer_char']), hrule]
+    headerstr = [hrule, header(headers, column_width=column_width, outer_char=outer_char), hrule]
 
     # parse each row
-    tablestr = headerstr + [row(d, column_width=opts['column_width'], format_spec=opts['format_spec'],
-                           outer_char=opts['outer_char']) for d in data]\
+    tablestr = headerstr + [row(d, column_width=column_width, format_spec=format_spec,
+                           outer_char=outer_char) for d in data]\
 
     # only add the final border if there was data in the table
     if len(data) > 0:
@@ -212,7 +183,7 @@ def hr(ncols, column_width=10, corner_char='+', line_char='-'):
     return corner_char + hrstr[1:-1] + corner_char
 
 
-def hrtime(t):
+def humantime(t):
     """
     Converts a time in seconds to a reasonable human readable time
 
@@ -236,22 +207,22 @@ def hrtime(t):
     # weeks
     if t >= 7*60*60*24:
         weeks = np.floor(t / (7.*60.*60.*24.))
-        timestr = "{:0.0f} weeks, ".format(weeks) + hrtime(t % (7*60*60*24))
+        timestr = "{:g} weeks, ".format(weeks) + hrtime(t % (7*60*60*24))
 
     # days
     elif t >= 60*60*24:
         days = np.floor(t / (60.*60.*24.))
-        timestr = "{:0.0f} days, ".format(days) + hrtime(t % (60*60*24))
+        timestr = "{:g} days, ".format(days) + hrtime(t % (60*60*24))
 
     # hours
     elif t >= 60*60:
         hours = np.floor(t / (60.*60.))
-        timestr = "{:0.0f} hours, ".format(hours) + hrtime(t % (60*60))
+        timestr = "{:g} hours, ".format(hours) + hrtime(t % (60*60))
 
     # minutes
     elif t >= 60:
         minutes = np.floor(t / 60.)
-        timestr = "{:0.0f} min., ".format(minutes) + hrtime(t % 60)
+        timestr = "{:g} min., ".format(minutes) + hrtime(t % 60)
 
     # seconds
     elif (t >= 1) | (t == 0):
@@ -270,3 +241,32 @@ def hrtime(t):
         timestr = "{:g} ns".format(t*1e9)
 
     return timestr
+
+
+def frame(dataframe, **kwargs):
+    """
+    Print an ASCII table using the given pandas DataFrame
+
+    Parameters
+    ----------
+    dataframe : DataFrame
+        A pandas DataFrame with consisting of the table to print
+
+    column_width : int, optional
+        The width of each column in the table (Default: 10)
+
+    outer_char : string, optional
+        The character defining the outer border of the table (Default: '|')
+
+    corner_char : string, optional
+        Printed at the junctions of the table lines (Default: '+')
+
+    line_char : string, optional
+        Character as part of each horizontal rule (Default: '-')
+
+    format_spec : string, optional
+        Format specification for formatting numbers (Default: '5g')
+
+    """
+
+    table(np.array(dataframe), list(dataframe.columns), **kwargs)