1Signature functions 2================================================================================ 3 4Import data into Python 5-------------------------------------------------------------------------------- 6 7This library provides one application programming interface to read data from 8one of the following data sources: 9 10 * physical file 11 * memory file 12 * SQLAlchemy table 13 * Django Model 14 * Python data structures: dictionary, records and array 15 16and to transform them into one of the following data structures: 17 18 * two dimensional array 19 * a dictionary of one dimensional arrays 20 * a list of dictionaries 21 * a dictionary of two dimensional arrays 22 * a :class:`~pyexcel.Sheet` 23 * a :class:`~pyexcel.Book` 24 25 26Four data access functions 27++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 28 29Python data can be handled well using lists, 30dictionaries and various mixture of both. This library provides four module level 31functions to help you obtain excel data in these data structures. Please refer to 32"A list of module level functions", the first three functions operates on any 33one sheet from an excel book and the fourth one returns all data in all sheets 34in an excel book. 35 36.. table:: A list of module level functions 37 38 =============================== ======================================= ================================ 39 Functions Name Python name 40 =============================== ======================================= ================================ 41 :meth:`~pyexcel.get_array` two dimensional array a list of lists 42 :meth:`~pyexcel.get_dict` a dictionary of one dimensional arrays an ordered dictionary of lists 43 :meth:`~pyexcel.get_records` a list of dictionaries a list of dictionaries 44 :meth:`~pyexcel.get_book_dict` a dictionary of two dimensional arrays a dictionary of lists of lists 45 =============================== ======================================= ================================ 46 47See also: 48 49* :ref:`get_an_array_from_an_excel_sheet` 50* :ref:`get_a_dict_from_an_excel_sheet` 51* :ref:`get_records_from_an_excel_sheet` 52* :ref:`get_an_book_dict_from_an_excel_book` 53 54The following two variants of the data access function use generator and should work well with big data files 55 56.. table:: A list of variant functions 57 58 =============================== ======================================= ================================ 59 Functions Name Python name 60 =============================== ======================================= ================================ 61 :meth:`~pyexcel.iget_array` a memory efficient two dimensional a generator of a list of lists 62 array 63 :meth:`~pyexcel.iget_records` a memory efficient list a generator of 64 list of dictionaries a list of dictionaries 65 =============================== ======================================= ================================ 66 67However, you will need to call :meth:`~pyexcel.free_resource` to make sure file 68handles are closed. 69 70Two pyexcel functions 71++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 72 73In cases where the excel data needs custom manipulations, a pyexcel user got a 74few choices: one is to use :class:`~pyexcel.Sheet` and :class:`~pyexcel.Book`, 75the other is to look for more sophisticated ones: 76 77* Pandas, for numerical analysis 78* Do-it-yourself 79 80=============================== ================================ 81Functions Returns 82=============================== ================================ 83:meth:`~pyexcel.get_sheet` :class:`~pyexcel.Sheet` 84:meth:`~pyexcel.get_book` :class:`~pyexcel.Book` 85=============================== ================================ 86 87For all six functions, you can pass on the same command parameters while the 88return value is what the function says. 89 90 91Export data from Python 92-------------------------------------------------------------------------------- 93 94This library provides one application programming interface to transform them 95into one of the data structures: 96 97 * two dimensional array 98 * a (ordered) dictionary of one dimensional arrays 99 * a list of dictionaries 100 * a dictionary of two dimensional arrays 101 * a :class:`~pyexcel.Sheet` 102 * a :class:`~pyexcel.Book` 103 104and write to one of the following data sources: 105 106 * physical file 107 * memory file 108 * SQLAlchemy table 109 * Django Model 110 * Python data structures: dictionary, records and array 111 112 113Here are the two functions: 114 115=============================== ================================= 116Functions Description 117=============================== ================================= 118:meth:`~pyexcel.save_as` Works well with single sheet file 119:meth:`~pyexcel.isave_as` Works well with big data files 120:meth:`~pyexcel.save_book_as` Works with multiple sheet file 121 and big data files 122:meth:`~pyexcel.isave_book_as` Works with multiple sheet file 123 and big data files 124=============================== ================================= 125 126If you would only use these two functions to do format transcoding, you may enjoy a 127speed boost using :meth:`~pyexcel.isave_as` and :meth:`~pyexcel.isave_book_as`, 128because they use `yield` keyword and minimize memory footprint. However, you will 129need to call :meth:`~pyexcel.free_resource` to make sure file handles are closed. 130And :meth:`~pyexcel.save_as` and :meth:`~pyexcel.save_book_as` reads all data into 131memory and **will make all rows the same width**. 132 133See also: 134 135* :ref:`save_an_array_to_an_excel_sheet` 136* :ref:`save_an_book_dict_to_an_excel_book` 137* :ref:`save_an_array_to_a_csv_with_custom_delimiter` 138 139Data transportation/transcoding 140-------------------------------------------------------------------------------- 141 142This library is capable of transporting your data between any of the following data sources: 143 144 * physical file 145 * memory file 146 * SQLAlchemy table 147 * Django Model 148 * Python data structures: dictionary, records and array 149 150See also: 151 152* :ref:`import_excel_sheet_into_a_database_table` 153* :ref:`save_a_xls_as_a_xlsx` 154* :ref:`save_a_xls_as_a_csv` 155