capability.rst

Signature functions

Import data into Python

This library provides one application programming interface to read data from one of the following data sources:

• physical file
• memory file
• SQLAlchemy table
• Django Model
• Python data structures: dictionary, records and array

and to transform them into one of the following data structures:

• two dimensional array
• a dictionary of one dimensional arrays
• a list of dictionaries
• a dictionary of two dimensional arrays
• a ~pyexcel.Sheet
• a ~pyexcel.Book

Four data access functions

Python data can be handled well using lists, dictionaries and various mixture of both. This library provides four module level functions to help you obtain excel data in these data structures. Please refer to "A list of module level functions", the first three functions operates on any one sheet from an excel book and the fourth one returns all data in all sheets in an excel book.

A list of module level functions

Functions	Name	Python name
~pyexcel.get_array	two dimensional array	a list of lists
~pyexcel.get_dict	a dictionary of one dimensional arrays	an ordered dictionary of lists
~pyexcel.get_records	a list of dictionaries	a list of dictionaries
~pyexcel.get_book_dict	a dictionary of two dimensional arrays	a dictionary of lists of lists

See also:

• get_an_array_from_an_excel_sheet
• get_a_dict_from_an_excel_sheet
• get_records_from_an_excel_sheet
• get_an_book_dict_from_an_excel_book

The following two variants of the data access function use generator and should work well with big data files

A list of variant functions

Functions	Name	Python name
~pyexcel.iget_array	a memory efficient two dimensional array	a generator of a list of lists
~pyexcel.iget_records	a memory efficient list list of dictionaries	a generator of a list of dictionaries

However, you will need to call ~pyexcel.free_resource to make sure file handles are closed.

Two pyexcel functions

In cases where the excel data needs custom manipulations, a pyexcel user got a few choices: one is to use ~pyexcel.Sheet and ~pyexcel.Book, the other is to look for more sophisticated ones:

• Pandas, for numerical analysis
• Do-it-yourself

Functions	Returns
~pyexcel.get_sheet	~pyexcel.Sheet
~pyexcel.get_book	~pyexcel.Book

For all six functions, you can pass on the same command parameters while the return value is what the function says.

Export data from Python

This library provides one application programming interface to transform them into one of the data structures:

• two dimensional array
• a (ordered) dictionary of one dimensional arrays
• a list of dictionaries
• a dictionary of two dimensional arrays
• a ~pyexcel.Sheet
• a ~pyexcel.Book

and write to one of the following data sources:

• physical file
• memory file
• SQLAlchemy table
• Django Model
• Python data structures: dictionary, records and array

Here are the two functions:

Functions	Description
~pyexcel.save_as	Works well with single sheet file
~pyexcel.isave_as	Works well with big data files
~pyexcel.save_book_as	Works with multiple sheet file and big data files
~pyexcel.isave_book_as	Works with multiple sheet file and big data files

If you would only use these two functions to do format transcoding, you may enjoy a speed boost using ~pyexcel.isave_as and ~pyexcel.isave_book_as, because they use yield keyword and minimize memory footprint. However, you will need to call ~pyexcel.free_resource to make sure file handles are closed. And ~pyexcel.save_as and ~pyexcel.save_book_as reads all data into memory and will make all rows the same width.

See also:

• save_an_array_to_an_excel_sheet
• save_an_book_dict_to_an_excel_book
• save_an_array_to_a_csv_with_custom_delimiter

Data transportation/transcoding

This library is capable of transporting your data between any of the following data sources:

• physical file
• memory file
• SQLAlchemy table
• Django Model
• Python data structures: dictionary, records and array

See also:

• import_excel_sheet_into_a_database_table
• save_a_xls_as_a_xlsx
• save_a_xls_as_a_csv