diff --git a/README.md b/README.md index e5df32d..cafc9dc 100644 --- a/README.md +++ b/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 diff --git a/docs/api.rst b/docs/api.rst index e69de29..90b80fb 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -0,0 +1,9 @@ +.. _api: + +=== +API +=== + +.. automodule:: tableprint + :members: + diff --git a/docs/conf.py b/docs/conf.py index c23cd0b..b276e2e 100644 --- a/docs/conf.py +++ b/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} diff --git a/docs/index.rst b/docs/index.rst index 107f8ef..04846bd 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/quickstart.rst b/docs/quickstart.rst index e69de29..5e455f3 100644 --- a/docs/quickstart.rst +++ b/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/ + diff --git a/tableprint.py b/tableprint.py index c5af916..98100ff 100644 --- a/tableprint.py +++ b/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: @@ -207,12 +178,12 @@ def hr(ncols, column_width=10, corner_char='+', line_char='-'): """ - hrstr = corner_char.join([('{:%s^%i}' % (line_char, column_width+2)).format('') for _ in range(ncols)]) + hrstr = corner_char.join([('{:%s^%i}' % (line_char, column_width + 2)).format('') for _ in range(ncols)]) 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)