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)[source]¶
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)[source]¶
Adds a formatter to the
Dataset
.- Parameters:
col – column to. Accepts index int, header str, or None to apply the formatter to all columns.
handler – reference to callback function to execute against each cell value.
- append(row, tags=())[source]¶
Adds a row to the
Dataset
. See :method:`Dataset.insert` for additional documentation.
- append_col(col, header=None)[source]¶
Adds a column to the
Dataset
. See :method:`Dataset.insert_col` for additional documentation.
- 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)[source]¶
Export
Dataset
object to format.- Parameters:
**kwargs – (optional) custom configuration to the format export_set.
- extend(rows, tags=())[source]¶
Adds a list of rows to the
Dataset
using :method:`Dataset.append`
- filter(tag)[source]¶
Returns a new instance of the
Dataset
, excluding any rows that do not contain the given tags.
- 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
.
- insert(index, row, tags=())[source]¶
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.You can add tags to the row you are inserting. This gives you the ability to :method:`filter <Dataset.filter>` your
Dataset
later.
- insert_col(index, col=None, header=None)[source]¶
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.
- load(in_stream, format=None, **kwargs)[source]¶
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.
- lpush(row, tags=())[source]¶
Adds a row to the top of the
Dataset
. See :method:`Dataset.insert` for additional documentation.
- lpush_col(col, header=None)[source]¶
Adds a column to the top of the
Dataset
. See :method:`Dataset.insert` for additional documentation.
- remove_duplicates()[source]¶
Removes all duplicate rows from the
Dataset
object while maintaining the original order.
- rpush(row, tags=())[source]¶
Adds a row to the end of the
Dataset
. See :method:`Dataset.insert` for additional documentation.
- rpush_col(col, header=None)[source]¶
Adds a column to the end of the
Dataset
. See :method:`Dataset.insert` for additional documentation.
- sort(col, reverse=False)[source]¶
Sort a
Dataset
by a specific column, given string (for header) or integer (for column index). The order can be reversed by settingreverse
toTrue
.Returns a new
Dataset
instance where columns have been sorted.
- stack(other)[source]¶
Stack two
Dataset
instances together by joining at the row level, and return new combinedDataset
instance.
- stack_cols(other)[source]¶
Stack two
Dataset
instances together by joining at the column level, and return a new combinedDataset
instance. If eitherDataset
has headers set, than the other must as well.
- subset(rows=None, cols=None)[source]¶
Returns a new instance of the
Dataset
, including only specified rows and columns.
Databook Object¶
- class tablib.Databook(sets=None)[source]¶
A book of
Dataset
objects.- export(format, **kwargs)[source]¶
Export
Databook
object to format.- Parameters:
**kwargs – (optional) custom configuration to the format export_book.
Functions¶
Exceptions¶
- exception tablib.exceptions.HeadersNeeded[source]¶
Header parameter must be given when appending a column to this Dataset.
- exception tablib.exceptions.InvalidDimensions[source]¶
The size of the column or row doesn’t fit the table dimensions.
Now, go start some Tablib Development.