Skip to content

Commit

Permalink
describe pyexcel-io
Browse files Browse the repository at this point in the history
  • Loading branch information
@chfw
chfw committed May 18, 2015
1 parent 010b109 commit 3f759db
Show file tree
Hide file tree
Showing 3 changed files with 78 additions and 28 deletions.
35 changes: 26 additions & 9 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,31 @@ pyexcel-io - Let you focus on data, instead of file formats
.. image:: http://img.shields.io/gittip/chfw.svg
:target: https://gratipay.com/chfw/

**pyexcel-io** is a tiny wrapper library to read and write the data in csv format,
import the data into and export the data from database. If you need to manipulate
the data, you might use its brother library
`pyexcel <https://github.com/chfw/pyexcel>`__ .

Meanwhile, if you would like to extend it, you may use it to write your own
extension to handle a specific file format: reading content from and writing
content to.

**pyexcel-io** provides **one** application programming interface(API) to read
and write the data in excel format, import the data into and export the data
from database. It provides support for csv(z) format, django database and
sqlalchemy supported databases. Its supported file formats are extended to cover
"xls", "xlsx", "ods" by the following extensions:

================ ==================================
Plugins Supported file formats
================ ==================================
`pyexcel-xls`_ xls, xlsx(r), xlsm(r)
`pyexcel-xlsx`_ xlsx
`pyexcel-ods`_ ods (python 2.6, 2.7 only)
`pyexcel-ods3`_ ods
================ ==================================

.. _pyexcel-xls: https://github.com/chfw/pyexcel-xls
.. _pyexcel-xlsx: https://github.com/chfw/pyexcel-xlsx
.. _pyexcel-ods: https://github.com/chfw/pyexcel-ods
.. _pyexcel-ods3: https://github.com/chfw/pyexcel-ods3

If you need to manipulate the data, you might do it yourself or use its brother
library `pyexcel <https://github.com/chfw/pyexcel>`__ .

If you would like to extend it, you may use it to write your own
extension to handle a specific file format.

Known constraints
================================================================================
Expand All @@ -45,6 +61,7 @@ or clone it and install it::
$ cd pyexcel-io
$ python setup.py install


License
===========

Expand Down
38 changes: 19 additions & 19 deletions doc/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,11 @@
Introduction
--------------------------------------------------------------------------------

**pyexcel-io** is a wrapper library that provides **one** application
programming interface to read and write data in different excel formats.
This library makes information processing involving excel files a
simple task. The data in excel files can be turned into an ordered dictionary
with least code, vice versa. This library focuses on data processing using
excel files as storage media hence fonts, colors and charts were not and
**pyexcel-io** provides **one** application programming interface(API) to read
and write data in different excel formats. It makes information processing
involving excel files a simple task. The data in excel files can be turned into
an ordered dictionary with least code. This library focuses on data processing
using excel files as storage media hence fonts, colors and charts were not and
will not be considered.

It was created due to the lack of uniform programming interface to access data
Expand All @@ -35,9 +34,9 @@ application supports, the library takes up the challenge and promises to support
all known excel formats.

All great work have done by individual library developers. This library unites
only the data access code. With that said, pyexcel also bring something new on
the table: :ref:`"csvz" and "tsvz"<csvz>` format, new format names as of 2014.
They are invented and supported by `pyexcel-io`_.
only the data access API. With that said, **pyexcel-io** also bring something
new on the table: :ref:`"csvz" and "tsvz"<csvz>` format, new format names
as of 2014. They are invented and supported by `pyexcel-io`_.

Getting the source
--------------------------------------------------------------------------------
Expand All @@ -58,20 +57,22 @@ For individual excel file formats, please install them as you wish:
.. _a-map-of-plugins-and-file-formats:
.. table:: a map of plugins and supported excel file formats

================ ============================================================ ============= ======================== =============================
Plugin Supported file formats Dependencies Python versions Comments
================ ============================================================ ============= ======================== =============================
`pyexcel-io`_ csv, csvz [#f1]_, tsv, tsvz [#f2]_ 2.6, 2.7, 3.3, 3.4, pypy
`xls`_ xls, xlsx(read only), xlsm(read only) xlrd, xlwt 2.6, 2.7, 3.3, 3.4, pypy supports reading xlsx as well
`xlsx`_ xlsx openpyxl 2.6, 2.7, 3.3, 3.4, pypy
`ods3`_ ods ezodf, lxml 2.6, 2.7, 3.3, 3.4
`ods`_ ods (python 2.6, 2.7) odfpy 2.6, 2.7
================ ============================================================ ============= ======================== =============================
============== ======================================= ============= ======================== =============================
Package name Supported file formats Dependencies Python versions Comments
============== ======================================= ============= ======================== =============================
`pyexcel-io`_ csv, csvz [#f1]_, tsv, tsvz [#f2]_ 2.6, 2.7, 3.3, 3.4, pypy
`xls`_ xls, xlsx(read only), xlsm(read only) xlrd, xlwt 2.6, 2.7, 3.3, 3.4, pypy supports reading xlsx as well
`xlsx`_ xlsx openpyxl 2.6, 2.7, 3.3, 3.4, pypy
`ods3`_ ods ezodf, lxml 2.6, 2.7, 3.3, 3.4
`ods`_ ods (python 2.6, 2.7) odfpy 2.6, 2.7
============== ======================================= ============= ======================== =============================

Please import them before you start to access the desired file formats::

import pyexcel_plugin

After that, you can start get and save data in the loaded format.

.. table:: Plugin compatibility table

============= =========== ============ ============ ============
Expand All @@ -92,7 +93,6 @@ Please import them before you start to access the desired file formats::
.. _ods: https://github.com/chfw/pyexcel-ods
.. _ods3: https://github.com/chfw/pyexcel-ods3


Contents:

.. toctree::
Expand Down
33 changes: 33 additions & 0 deletions pyexcel_io/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,12 +91,19 @@ def resolve_missing_extensions(extension, available_list):
message = MESSAGE_LOADING_FORMATTER % (extension, merged)
raise NotImplementedError(message)


def load_data(filename,
file_type=None,
sheet_name=None,
sheet_index=None,
**keywords):
"""Load data from any supported excel formats
:param filename: actual file name, a file stream or actual content
:param file_type: used only when filename is not a physial file name
:param sheet_name: the name of the sheet to be loaded
:param sheet_index: the index of the sheet to be loaded
:param keywords: any other parameters
"""
extension = None
book = None
Expand Down Expand Up @@ -143,6 +150,10 @@ def load_data(filename,

def get_writer(filename, file_type=None, **keywords):
"""Create a writer from any supported excel formats
:param filename: actual file name or a file stream
:param file_type: used only when filename is not a physial file name
:param keywords: any other parameters
"""
extension = None
writer = None
Expand Down Expand Up @@ -183,6 +194,13 @@ def get_io(file_type):


def store_data(afile, data, file_type=None, **keywords):
"""Non public function to store data to afile
:param filename: actual file name, a file stream or actual content
:param data: the data to be written
:param file_type: used only when filename is not a physial file name
:param keywords: any other parameters
"""
writer = get_writer(
afile,
file_type=file_type,
Expand All @@ -192,6 +210,13 @@ def store_data(afile, data, file_type=None, **keywords):


def save_data(afile, data, file_type=None, **keywords):
"""Public function to store data to afile
:param filename: actual file name, a file stream or actual content
:param data: the data to be saved
:param file_type: used only when filename is not a physial file name
:param keywords: any other parameters
"""
to_store = data
if isinstance(data, list):
single_sheet_in_book = True
Expand All @@ -209,6 +234,14 @@ def save_data(afile, data, file_type=None, **keywords):


def get_data(afile, file_type=None, **keywords):
"""get data from file
:param filename: actual file name, a file stream or actual content
:param sheet_name: the name of the sheet to be loaded
:param sheet_index: the index of the sheet to be loaded
:param file_type: used only when filename is not a physial file name
:param keywords: any other parameters
"""
if isstream(afile) and file_type is None:
file_type='csv'
data = load_data(afile, file_type=file_type, **keywords)
Expand Down

0 comments on commit 3f759db

Please sign in to comment.