# 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`.

    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=())

    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(index)

    Returns the row from the `Dataset` at the given index.

  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.

    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)

    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.

  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. If the instance has headers, 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.