Quickstart¶
This page gives a good introduction to the basics of Tableview. This assumes that you have tableview installed and up to date.
Create a TableView¶
The heart of the Tableview library is the TableView object. It represents a shallow view of any tabular data. To create one, pass some tabular data to its constructor:
d = [['Name', 'Age', 'Drink', 'Color'], \
['Ryan', 30, 'Tea', 'Purple'], \
['Michael', 31, 'Coffee', 'Blue'], \
['Keith', 40, 'Tea', 'Maroon'], \
['Brent', 26, 'Coffee', 'Blue'], \
['Craig', '??', 'Bourbon', 'Turquoise']]
table = tableview.TableView(d)
Example Context
From here on, if you see table, assume that it is a fresh TableView object that represents the data above.
Pretty Printing¶
The pretty() method returns a pretty string for a TableView:
>>> print table.pretty()
Name Age Drink Color
Ryan 30 Tea Purple
Michael 31 Coffee Blue
Keith 40 Tea Maroon
Brent 26 Coffee Blue
Craig ?? Bourbon Turquoise
Rows and Columns¶
Views are indexed by by row, just like a 2D list
>>> print table[0].pretty()
Name Age Drink Color
But to make operations symmetrical between rows and columns, the rows and cols properties are provided. They work just like you think:
>>> print table.rows[0].pretty()
Name Age Drink Color
>>> print table.cols[0].pretty()
Name
Ryan
Michael
Keith
Brent
Craig
Row Notation
From here on, the table.rows[] notation will be used, but any such operation can be done using the table[] notation. They are equivalent.
Removing Data from a View¶
You can delete a row or column from a view using the standard del operator:
del table.rows[0]
The same operation works on columns:
del table.cols[1]
Looking at the data now, we see there are no column headers, and the Age column has been removed:
>>> print table.pretty()
Ryan Tea Purple
Michael Coffee Blue
Keith Tea Maroon
Brent Coffee Blue
Craig Bourbon Turquoise
It is important to remember that we haven’t modified the source data. Row and column operations only affect the view itself. We can create a new view from the data, and take a look at it:
>>> table2 = tableview.TableView(d)
>>> print table2.pretty()
Name Age Drink Color
Ryan 30 Tea Purple
Michael 31 Coffee Blue
Keith 40 Tea Maroon
Brent 26 Coffee Blue
Craig ?? Bourbon Turquoise
Selecting Rows and Columns¶
Frequently, we want to select data based on some criteria, rather than by index. select_rows and select_cols do just that. Let’s say we are only interested in the coffee drinkers:
selection = table.select_rows(lambda row : row[2] == 'Coffee')
The select methods take a single callable that takes a single argument (a row or column). They return True if the row or column is to be returned in the selection. Let’s inspect our selected data:
>>> print selection.pretty()
Michael 31 Coffee Blue
Brent 26 Coffee Blue
Like all operations, the same can be done with columns. Using a fresh table:
>>> print table.select_cols(lambda col : col[0] in ('Name', 'Drink')).pretty()
Name Drink
Ryan Tea
Michael Coffee
Keith Tea
Brent Coffee
Craig Bourbon
Selection operations return new tableview objects. Our original TableView is untouched by calls to select_rows and select_cols
Stripping Rows and Columns¶
Stripping works just like selecting, except that the matching rows/columns are removed from the output, rather than included. Back to our coffee drinkers:
>>> print table.strip_rows(lambda row : row[2] == 'Coffee').pretty()
Name Age Drink Color
Ryan 30 Tea Purple
Keith 40 Tea Maroon
Craig ?? Bourbon Turquoise
Tea is better for you, anyway.
Splitting Tables¶
TableViews can be split into smaller views by rows or by columns. This is handy when you have a table that is composed of multiple subtables, separated by empty rows or a divider:
separated_data = [[1,2,3], \
[], \
[4,5,6], \
[7,8,9], \
['','','']
[10,11,12], \
[13,14,15], \
[16,17,18]]
table = tableview.TableView(separated_data)
one,two,three = table.split_rows()
>>> print one.pretty()
1 2 3
>>> print two.pretty()
4 5 6
7 8 9
>>> print three.pretty()
10 11 12
13 14 15
16 17 18
The default behavior of split_rows and split_cols is to split on empty rows/columns. The example above splits the table view into 3 parts, using the empty rows as delimiters. An ‘empty’ row is one whose elements all evaluate to False This is why the row of empty strings worked as a delimiter in the example above. This also means that a row of zeroes is a valid delimiter, so care must be taken when working with tables of numeric data.
The default delimiter behavior can be modified with an optional criteria argument to split_rows and split_cols It is a function that accepts a row or column as an argument, and should return True if that row or column is a delimiter:
mixed_data = [['Letters:'], \
['a','b','c'], \
['d','e','f'], \
['Numbers:'], \
[1,2,3], \
[4,5,6], \
[7,8,9]], \
['Symbols:'], \
['*','%','!'], \
['$','#','@']]
table = tableview.TableView(mixed_data)
letters,numbers,symbols = table.split_rows(lambda row : row[0].endswith(':'))
>>> print letters.pretty()
a b c
d e f
>>> print numbers.pretty()
1 2 3
4 5 6
>>> print symbols.pretty()
* % !
$ # @
The example above performs a similar split, but instead of looking for empty rows, it uses rows whose first cells end with a colon (:), assuming these rows to be section headings.
Manipulating Data¶
While row and column operations don’t affect a TableView's source data, assignments to its members do. Once you have the view configured to show the data you want, it can be modified. This is the real power of Tableview:
selection = table.select_rows(lambda row : row[2] == 'Coffee')
for row in selection:
row[-1] = 'Yellow'
We’ve singled out all the coffee drinkers, and changed their favorite color to yellow. Remember that when we select rows, we’re getting a new view of the table. Our original table object is still a view of all the source data. Let’s inspect:
>>> print table.pretty()
Name Age Drink Color
Ryan 30 Tea Purple
Michael 31 Coffee Yellow
Keith 40 Tea Maroon
Brent 26 Coffee Yellow
Craig ?? Bourbon Turquoise
Raw Data¶
A copy of the contents of a view can be retrieved using its raw property. This returns a copy of the view’s data as a list of lists:
>>> table.raw
[['Ryan', 30, 'Tea', 'Purple'], ['Michael', 31, 'Coffee', 'Blue'], ['Keith', 40, 'Diet Coke', 'Maroon'], ['Brent', 26, 'Coffee', 'Blue'], ['Craig', '??', 'Turquoise', 'Red']]
Loading Data from Disk¶
If you are working with CSV or text files, data can be easily loaded from disk:
table = tableview.load('data.csv')
In this case, the TableView object wasn’t invoked directly. Like any TableView, we can access its source data using the data property:
>>> print table.data
[['Name', 'Age', 'Drink', 'Color'], ['Ryan', 30, 'Tea', 'Purple'], ['Michael', 31, 'Coffee', 'Blue'], ['Keith', 40, 'Tea', 'Maroon'], ['Brent', 26, 'Coffee', 'Blue'], ['Craig', ??, 'Bourbon', 'Turquoise']]
The tableview.load function uses the file extension to determine how to parse the file. A .csv extension indicates comma-separated-values, and any other extension is assumed to be tab-separated text.