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