API

This part of the documentation covers all the interfaces of Tablib. For parts where Tablib depends on external libraries, we document the most important right here and provide links to the canonical documentation.

Dataset Object

class tablib.Dataset(*args, **kwargs)

The Dataset object is the heart of Tablib. It provides all core functionality.

Usually you create a Dataset instance in your main module, and append rows as you collect data.

data = tablib.Dataset()
data.headers = ('name', 'age')

for (name, age) in some_collector():
    data.append((name, age))

Setting columns is similar. The column data length must equal the current height of the data and headers must be set.

data = tablib.Dataset()
data.headers = ('first_name', 'last_name')

data.append(('John', 'Adams'))
data.append(('George', 'Washington'))

data.append_col((90, 67), header='age')

You can also set rows and headers upon instantiation. This is useful if dealing with dozens or hundreds of Dataset objects.

headers = ('first_name', 'last_name')
data = [('John', 'Adams'), ('George', 'Washington')]

data = tablib.Dataset(*data, headers=headers)

Parameters:

• *args – (optional) list of rows to populate Dataset

• headers – (optional) list strings for Dataset header row

• title – (optional) string to use as title of the Dataset

If you look at the code, the various output/import formats are not defined within the Dataset object. To add support for a new format, see Adding New Formats.

add_formatter(col, handler)

Adds a formatter to the Dataset.

New in version 0.9.5.

Parameters:

• col – column to. Accepts index int or header str.

• handler – reference to callback function to execute against each cell value.

append(row, tags=())

Adds a row to the Dataset. See :method:`Dataset.insert` for additional documentation.

append_col(col, header=None)

Adds a column to the Dataset. See :method:`Dataset.insert_col` for additional documentation.

append_separator(text='-')

Adds a separator to the Dataset.

property dict

A native Python representation of the Dataset object. If headers have been set, a list of Python dictionaries will be returned. If no headers have been set, a list of tuples (rows) will be returned instead.

A dataset object can also be imported by setting the Dataset.dict attribute:

data = tablib.Dataset()
data.dict = [{'age': 90, 'first_name': 'Kenneth', 'last_name': 'Reitz'}]

export(format, **kwargs)

Export Dataset object to format.

Parameters:

**kwargs – (optional) custom configuration to the format export_set.

extend(rows, tags=())

Adds a list of rows to the Dataset using :method:`Dataset.append`

filter(tag)

Returns a new instance of the Dataset, excluding any rows that do not contain the given tags.

get_col(index)

Returns the column from the Dataset at the given index.

property headers

An optional list of strings to be used for header rows and attribute names.

This must be set manually. The given list length must equal Dataset.width.

property height

The number of rows currently in the Dataset. Cannot be directly modified.

insert(index, row, tags=())

Inserts a row to the Dataset at the given index.

Rows inserted must be the correct size (height or width).

The default behaviour is to insert the given row to the Dataset object at the given index.

insert_col(index, col=None, header=None)

Inserts a column to the Dataset at the given index.

Columns inserted must be the correct height.

You can also insert a column of a single callable object, which will add a new column with the return values of the callable each as an item in the column.

data.append_col(col=random.randint)

If inserting a column, and Dataset.headers is set, the header attribute must be set, and will be considered the header for that row.

See Dynamic Columns for an in-depth example.

Changed in version 0.9.0: If inserting a column, and Dataset.headers is set, the header attribute must be set, and will be considered the header for that row.

New in version 0.9.0: If inserting a row, you can add tags to the row you are inserting. This gives you the ability to :method:`filter <Dataset.filter>` your Dataset later.

insert_separator(index, text='-')

Adds a separator to Dataset at given index.

load(in_stream, format=None, **kwargs)

Import in_stream to the Dataset object using the format. in_stream can be a file-like object, a string, or a bytestring.

Parameters:

**kwargs – (optional) custom configuration to the format import_set.

lpop()

Removes and returns the first row of the Dataset.

lpush(row, tags=())

Adds a row to the top of the Dataset. See :method:`Dataset.insert` for additional documentation.

lpush_col(col, header=None)

Adds a column to the top of the Dataset. See :method:`Dataset.insert` for additional documentation.

pop()

Removes and returns the last row of the Dataset.

remove_duplicates()

Removes all duplicate rows from the Dataset object while maintaining the original order.

rpop()

Removes and returns the last row of the Dataset.

rpush(row, tags=())

Adds a row to the end of the Dataset. See :method:`Dataset.insert` for additional documentation.

rpush_col(col, header=None)

Adds a column to the end of the Dataset. See :method:`Dataset.insert` for additional documentation.

sort(col, reverse=False)

Sort a Dataset by a specific column, given string (for header) or integer (for column index). The order can be reversed by setting reverse to True.

Returns a new Dataset instance where columns have been sorted.

stack(other)

Stack two Dataset instances together by joining at the row level, and return new combined Dataset instance.

stack_cols(other)

Stack two Dataset instances together by joining at the column level, and return a new combined Dataset instance. If either Dataset has headers set, than the other must as well.

subset(rows=None, cols=None)

Returns a new instance of the Dataset, including only specified rows and columns.

transpose()

Transpose a Dataset, turning rows into columns and vice versa, returning a new Dataset instance. The first row of the original instance becomes the new header row.

property width

The number of columns currently in the Dataset. Cannot be directly modified.

wipe()

Removes all content and headers from the Dataset object.

Databook Object

class tablib.Databook(sets=None)

A book of Dataset objects.

add_sheet(dataset)

Adds given Dataset to the Databook.

export(format, **kwargs)

Export Databook object to format.

Parameters:

**kwargs – (optional) custom configuration to the format export_book.

load(in_stream, format, **kwargs)

Import in_stream to the Databook object using the format. in_stream can be a file-like object, a string, or a bytestring.

Parameters:

**kwargs – (optional) custom configuration to the format import_book.

property size

The number of the Dataset objects within Databook.

wipe()

Removes all Dataset objects from the Databook.

Functions

tablib.detect_format(stream)

Return format name of given stream (file-like object, string, or bytestring).

tablib.import_set(stream, format=None, **kwargs)

Return dataset of given stream (file-like object, string, or bytestring).

Exceptions

exception tablib.exceptions.HeadersNeeded

Header parameter must be given when appending a column to this Dataset.

exception tablib.exceptions.InvalidDatasetIndex

Outside of Dataset size.

exception tablib.exceptions.InvalidDatasetType

Only Datasets can be added to a Databook.

exception tablib.exceptions.InvalidDimensions

The size of the column or row doesn’t fit the table dimensions.

exception tablib.exceptions.TablibException

Tablib common exception.

exception tablib.exceptions.UnsupportedFormat

Format not supported.

Now, go start some Tablib Development.