Skip to main content

ASCII table with per column format specs, multi-line content, formatting directives, column width control.

Project description

License: Apache 2.0 Python versions supported Build Status Code Coverage

Introduction, Installation

Monotable is a Python library that generates an ASCII table from tabular cell data that looks pretty in a monospaced font.

Monotable offers formatting directives to reduce messy table pre-formatting code. You can set directives for each column. You can also write and plug in your own format function directives.

Here is a list of some of the things Monotable does:

  • Allows multi-line title, heading, and cell strings.

  • Supports column oriented cell data.

  • Generate a table with borders.

  • Directives to limit column width and text wrap.

  • Add horizontal and vertical rules.

  • Join ASCII tables horizontally.

  • Is thoroughly documented and tested.


pip install monotable


Per column format specifications

Specify format string for each column.

from monotable import mono
headings = ['comma', 'percent']
formats = [',', '.1%']
cells = [[123456789, 0.33], [2345678, 0.995]]
    headings, formats, cells, title="',' and '%' formats."))
',' and '%' formats.
      comma  percent
123,456,789    33.0%
  2,345,678    99.5%
  • List formats supplies the format strings containing the formatting instructions. They are assigned to columns from left to right.

  • Here the format strings are just format specifications.

  • For each cell in the column, it and the format specification is passed to the built-in function format(value, format_spec).

  • To write a format_spec, consult Python’s Format Specification Mini-Language.

  • The cells are organized as a list of rows where each row is a list of cells.

zero and none format directives

Improve the appearance of zero values. Show the meaning of cell type None.

from datetime import datetime
from monotable import mono

headings = [
    '24 hour\ntemp\nchange',

formats = [

h7 = datetime(2019, 2, 28, 7, 0, 0)
h8 = datetime(2019, 2, 28, 8, 0, 0)
h9 = datetime(2019, 2, 28, 9, 0, 0)

cells = [
    [h7, -2.3,   11, 3.4],
    [h8,  0.1,    0, 0.0],
    [h9,    5, None, 0.6734]

    headings, formats, cells, title='=Formatting directives.'))
     Formatting directives.
      24 hour
         temp     wind   precip.
hour   change    speed  (inches)
07         -2       11      3.40
08       same     calm
09         +5  offline      0.67
  • The '%H' format specification is passed by built-in function format() to datetime.__format__().

  • The '(zero=same)+.0f' format string is split into two parts.

    • (zero=same) selects the zero directive with the value same.

    • +.0f is passed to the format function as format_spec.

  • The zero format directive applies when the cell is a Number and the formatted text contains no non-zero digits. The characters after zero= are the formatted text for the cell.

  • Format directives are enclosed by ( and ).

  • Separate multiple format directives with ;.

  • The none format directive formats the cell value None as the characters after none=.

parentheses format directive

Enclose negative numbers with parentheses. The 1’s digit remains in the same column.

from monotable import mono

headings = ['Description', 'Amount']
formats = ['', '(zero=n/a;parentheses),']

cells = [
    ['receivables', 51],
    ['other assets', 9050],
    ['gifts', 0],
    ['pending payments',  -75],
    ['other liabilities', -623]

    headings, formats, cells, title='parentheses directive.'))
  parentheses directive.
Description        Amount
receivables           51
other assets       9,050
gifts                n/a
pending payments     (75)
other liabilities   (623)

Format function directives

Format function directives select the format function used for the column. These are useful for scaling numbers and showing truth values.

from monotable import mono

headings = [
    'units of\nthousands',
    'bool to\nyes/no'

formats = [

cells = [
    [35200, True],
    [1660, False]

    headings, formats, cells, title='Format function directives.'))
Format function directives.
 units of  bool to
thousands   yes/no
     35.2      yes
      1.7       no
  • Note the format function directives thousands and boolean.

  • ‘(thousands)’ divides the cell value by 1000.0 and then calls format().

  • ‘(boolean)yes,no’ formats the cells that test True as ‘yes’ and False as ‘no’.

  • You can substitute any text you want for ‘yes,no’ for example ‘on,off’.

  • You can also write and plug in an unlimited number of custom format function directives.

  • monotable’s format function directives are implemented in the file

Column oriented input with vertical rule column

from monotable import monocol, VR_COL

column0 = ('award', '', ['nominated', 'won'])
column1 = ('bool to\nyes/no', '(boolean)yes,no', [True, False])
columns = [column0, VR_COL, column1]

    title='Columns with\nvertical rule.'))
    Columns with
   vertical rule.
          | bool to
award     |  yes/no
nominated |     yes
won       |      no
  • VR_COL in the second column renders the vertical bars.

  • The title is center aligned.

Horizontal and vertical rules in a row oriented table

The cell row monotable.HR_ROW will be replaced with a heading guideline.

The text between columns can be changed with the format directive lsep. lsep specifies the separator between this column and the left side neighbor column.

By default the column separator is two spaces. In this example lsep in the second column is changed to ' | '. This creates an effect approximating a vertical rule.

The last row only has one element. monotable extends short heading, formats, and cell rows with the empty string value. Extra format directive strings are silently ignored.

from monotable import mono, HR_ROW

headings = ['col-0', 'col-1']
formats = ['', '(lsep= | )']

cells = [['time', '12:45'],
         ['place', 'home'],
         HR_ROW,              # put a heading guideline here
         ['sound', 'bell'],
         ['volume']]          # short row is extended with empty string

print(mono(headings, formats, cells))
col-0  | col-1
time   | 12:45
place  | home
sound  | bell
volume |

Documentation on Read the Docs

More Examples

List of format directives

Read about all the format directive syntax in the full Documentation. Follow the Format directives link in the Quick Links section.


render cell type None as characters ccc.


render numeric cell that formats to zero to characters ccc.


remove minus sign and enclose negative cell value in parentheses.


Characters ccc separate this column and the column to the left.


Characters ccc separate this column and the column to the right.


sets maximum width of column to N characters, content is truncated


sets maximum width of column to N characters, content is text wrapped


Pads or truncates content to N characters.


Pads or text wraps content to N characters.

List of format function directives


test cell truth value and substitute caller’s strings for True, False. The format_spec is ttt,fff where characters ttt are rendered for True and the characters fff are rendered for False.


selects user defined function function-name. User can plug in an unlimited number of format functions.

thousands millions billions trillions

divide cell value by 1000.0 (1.0e6, 1.0e9, 1,0e12).

milli micro nano pico

multiply cell value by 1000.0 (1.0e6, 1.0e9, 1,0e12).

kibi mebi gibi tebi

divide cell value by 1024. (1024**2, 1024**3, 1024**4).


format cells that are mappings by selecting keys with the format_spec.


cell is formatted by python printf-style percent operator ‘%’.


format cell with str.format().


format cell using string.Template.substitute().

Auto-alignment and how to override it

Monotable auto-aligns the title, headings, and each column.

Auto-alignment is overridden by using one of '<', '^', '>' prefixes on a heading string, format directive string, or title.

Read more about auto-alignment in “Quick Links” section in the full Documentation. Follow the link Auto-alignment.

What monotable does not do

  • Produce terminal graphics characters. Try PYPI terminaltables.

  • Handle CJK wide characters.

  • Handle ANSI escape terminal color sequences. Try PYPI terminaltables.

  • Produce arbitrary markup source text. Try PYPI tabulate instead. However calling mono() or monocol() with keyword argument bordered=True produces valid reStructuredText grid table and simple table markup is possible.

Monotable does make the output of its formatting and alignment engine available in list form. Please look for the function MonoTable.row_strings() in the API documentation.

Recent Changes

3.1.0 - 2020-05-15

  • Add py.typed designation. Add to setup() zip_safe=False.

3.0.1 - 2020-05-10

  • Remove Python 2.7 compatibility.

  • Move typing comments into function annotations. Rework typing.

  • Add monotable.join_strings().

2.1.0 - 2019-02-25

  • Add module level convenience functions mono(), monocol() and constants HR_ROW, VR_COL.

  • Add formatting directives none, zero, parentheses, lsep, and rsep.

  • Reorder/rework docs examples and other sections.

  • Change what (boolean) prints when malformed format spec.

  • Drop Python 3.3 and 3.4 classifiers. Drop Python 3.4 tests from Travis CI.

2.0.1 - 2018-05-12

  • Bugfix- MonoTableCellError on str below float in a column.

  • Bugfix- Incorrect format spec reported in MonoTableCellError.

2.0.0 - 2017-06-16

  • Changed the API: headings and formats parameters are now passed to table(), bordered_table().

  • Added to class MonoTable 2 member functions that take table data organized as columns.

  • Added convenience functions to module monotable.table. They call class MonoTable public member functions.

  • Added 13 new plugin format functions and the corresponding format options: boolean, thousands, millions, billions, trillions, milli, micro, nano, pico, kibi, mebi, gibi, tebi.

  • Removed ‘from MonoTable import’ statements from

1.0.2 - 2017-04-06

  • Bug fix, incorrect cell auto-alignment when mixed types in a column.

  • Bug fix, format_none_as cell ignoring column format string’s align_spec.

  • Remove and re-add files to git index so stored with LFs.

  • Add complexity inspections to CI.

  • Refactor 2 functions to reduce McCabe complexity.

  • Code inspection fixes. Docs and comments fixed.

1.0.1 - 2017-03-26

  • and doc fixes.

Contributing and Developing

Please see Contributing.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

monotable-3.1.0.tar.gz (87.2 kB view hashes)

Uploaded source

Built Distribution

monotable-3.1.0-py3-none-any.whl (41.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page