DOCSEARCHbyAlgolia
Submit Docs

tablib

repository·master·Indexed 26 days ago

https://github.com/jazzband/tablib

A format-agnostic tabular data library for Python that provides a unified interface to import, export, and manipulate datasets. It supports a wide range of formats including CSV, JSON, YAML, Excel (XLS/XLSX), SQL, ODS, DBF, HTML, and Pandas DataFrames. The library features Dataset and Databook objects for managing single or multiple tables, a format detection utility, and a class-based framework for registering custom formats.

Tokens
4.2K
Snippets
13
Records
39
Agent score
89%

What's inside tablib

  1. Overview of Tablib capabilities

    master

    Tablib is a format-agnostic tabular dataset library for Python. It provides a Pythonic interface to import, export, and manipulate tabular datasets. Key features include:

    • Seamless import and export across multiple formats.
    • Data segregation.
    • Dynamic columns.
    • Tags and filtering.

  2. Quickstart with Tablib Datasets

    master

    Tablib allows you to create, manipulate, and export tabular datasets using a format-agnostic approach. You can initialize a Dataset with headers, append rows of data, and export the result to various formats like JSON, YAML, XLSX, or Pandas DataFrames.

    >>> data = tablib.Dataset(headers=['First Name', 'Last Name', 'Age'])
>>> for i in [('Kenneth', 'Reitz', 22), ('Bessie', 'Monke', 21)]:
...     data.append(i)

>>> print(data.export('json'))
[{"Last Name": "Reitz", "First Name": "Kenneth", "Age": 22}, {"Last Name": "Monke", "First Name": "Bessie", "Age": 21}]

>>> print(data.export('yaml'))
- {Age: 22, First Name: Kenneth, Last Name: Reitz}
- {Age: 21, First Name: Bessie, Last Name: Monke}

>>> data.export('xlsx')
<redacted binary data>

>>> data.export('df')
  First Name Last Name  Age
0    Kenneth     Reitz   22
1     Bessie     Monke   21

  3. Create and populate a Dataset

    master

    A tablib.Dataset is a collection of data. You can create an empty instance and populate it by appending rows (lists or tuples) using the .append() method.

    import tablib

data = tablib.Dataset()

# Adding rows
names = ['Kenneth Reitz', 'Bessie Monke']
for name in names:
    fname, lname = name.split()
    data.append([fname, lname])

  4. Build Tablib documentation

    master

    Tablib documentation is written in reStructured Text and built using Sphinx. To build the documentation locally:

    1. Install Sphinx via pip.
    2. Navigate to the docs directory.
    3. Run make html to generate the HTML version.

    The output will be located in docs/_build/html.

    $ pip install sphinx
$ make html

  6. Import data from files

    master
    You can load data into a Dataset from a file-like object using the .load() method. Tablib automatically detects the format. If the source file (like CSV, TSV, or Excel) does not contain headers, pass headers=False to the .load() method.

  7. Import and export ODS (OpenDocument Spreadsheet)

    master

    The ods format supports import and export. Requires pip install "tablib[ods]".

    • skip_lines: Supported in import_set() to skip initial rows.
    • Binary Mode: You must write exported ODS data in binary mode ('wb').
    # Installation
pip install "tablib[ods]"

# Writing
with open('output.ods', 'wb') as f:
    f.write(data.ods)

  10. Add new formats to Tablib

    master

    Tablib uses a class-based micro-framework for adding format support. Since version 1.0, formats can be dynamically registered. To add a format, define a class with the required methods and register it with the registry.

    1. Define your custom format class

    Implement the following class methods depending on the level of support required:

    • export_set(cls, dset): Returns a string representation of a Dataset.
    • export_book(cls, dbook): Returns a string representation of a Databook.
    • import_set(cls, dset, in_stream): Populates a given Dataset with a given datastream.
    • import_book(cls, in_stream): Returns a Databook instance.
    • detect(cls, stream): Returns True if the given stream is parsable as this format.

    Note: If a format does not support a specific mechanism (e.g., a format that supports Dataset but not Databook), simply omit the corresponding method. Tablib will raise appropriate errors if that mechanism is called.

    2. Register the class

    Use tablib.formats.registry to make your format available for use.

    class MyXXXFormatClass:
    title = 'xxx'

    @classmethod
    def export_set(cls, dset):
        ....
        # returns string representation of given dataset

    @classmethod
    def export_book(cls, dbook):
        ....
        # returns string representation of given databook

    @classmethod
    def import_set(cls, dset, in_stream):
        ...
        # populates given Dataset with given datastream

    @classmethod
    def import_book(cls, in_stream):
        ...
        # returns Databook instance

   @classmethod
   def detect(cls, stream):
        ...
        # returns True if given stream is parsable as xxx

from tablib.formats import registry

registry.register('xxx', MyXXXFormatClass())