224 lines
8.6 KiB
ReStructuredText
224 lines
8.6 KiB
ReStructuredText
================================================================================
|
|
pyexcel-io - Let you focus on data, instead of file formats
|
|
================================================================================
|
|
|
|
.. image:: https://raw.githubusercontent.com/pyexcel/pyexcel.github.io/master/images/patreon.png
|
|
:target: https://www.patreon.com/pyexcel
|
|
|
|
.. image:: https://api.bountysource.com/badge/team?team_id=288537
|
|
:target: https://salt.bountysource.com/teams/chfw-pyexcel
|
|
|
|
.. image:: https://travis-ci.org/pyexcel/pyexcel-io.svg?branch=master
|
|
:target: http://travis-ci.org/pyexcel/pyexcel-io
|
|
|
|
.. image:: https://codecov.io/gh/pyexcel/pyexcel-io/branch/master/graph/badge.svg
|
|
:target: https://codecov.io/gh/pyexcel/pyexcel-io
|
|
|
|
.. image:: https://img.shields.io/gitter/room/gitterHQ/gitter.svg
|
|
:target: https://gitter.im/pyexcel/Lobby
|
|
|
|
.. image:: https://readthedocs.org/projects/pyexcel-io/badge/?version=latest
|
|
:target: http://pyexcel-io.readthedocs.org/en/latest/
|
|
|
|
Support the project
|
|
================================================================================
|
|
|
|
If your company has embedded pyexcel and its components into a revenue generating
|
|
product, please support me on `patreon <https://www.patreon.com/bePatron?u=5537627>`_
|
|
or `bounty source <https://salt.bountysource.com/teams/chfw-pyexcel>`_ to maintain
|
|
the project and develop it further.
|
|
|
|
If you are an individual, you are welcome to support me too and for however long
|
|
you feel like. As my backer, you will receive
|
|
`early access to pyexcel related contents <https://www.patreon.com/pyexcel/posts>`_.
|
|
|
|
And your issues will get prioritized if you would like to become my patreon as `pyexcel pro user`.
|
|
|
|
With your financial support, I will be able to invest
|
|
a little bit more time in coding, documentation and writing interesting posts.
|
|
|
|
|
|
Known constraints
|
|
==================
|
|
|
|
Fonts, colors and charts are not supported.
|
|
|
|
Introduction
|
|
================================================================================
|
|
|
|
**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:
|
|
|
|
.. _file-format-list:
|
|
.. _a-map-of-plugins-and-file-formats:
|
|
|
|
.. table:: A list of file formats supported by external plugins
|
|
|
|
======================== ======================= ================= ==================
|
|
Package name Supported file formats Dependencies Python versions
|
|
======================== ======================= ================= ==================
|
|
`pyexcel-io`_ csv, csvz [#f1]_, tsv, 2.6, 2.7, 3.3,
|
|
tsvz [#f2]_ 3.4, 3.5, 3.6
|
|
pypy
|
|
`pyexcel-xls`_ xls, xlsx(read only), `xlrd`_, same as above
|
|
xlsm(read only) `xlwt`_
|
|
`pyexcel-xlsx`_ xlsx `openpyxl`_ same as above
|
|
`pyexcel-ods3`_ ods `pyexcel-ezodf`_, 2.6, 2.7, 3.3, 3.4
|
|
lxml 3.5, 3.6
|
|
`pyexcel-ods`_ ods `odfpy`_ same as above
|
|
======================== ======================= ================= ==================
|
|
|
|
.. table:: Dedicated file reader and writers
|
|
|
|
======================== ======================= ================= ==================
|
|
Package name Supported file formats Dependencies Python versions
|
|
======================== ======================= ================= ==================
|
|
`pyexcel-xlsxw`_ xlsx(write only) `XlsxWriter`_ Python 2 and 3
|
|
`pyexcel-xlsxr`_ xlsx(read only) lxml same as above
|
|
`pyexcel-odsr`_ read only for ods, fods lxml same as above
|
|
`pyexcel-htmlr`_ html(read only) lxml,html5lib same as above
|
|
======================== ======================= ================= ==================
|
|
|
|
|
|
.. _pyexcel-io: https://github.com/pyexcel/pyexcel-io
|
|
.. _pyexcel-xls: https://github.com/pyexcel/pyexcel-xls
|
|
.. _pyexcel-xlsx: https://github.com/pyexcel/pyexcel-xlsx
|
|
.. _pyexcel-ods: https://github.com/pyexcel/pyexcel-ods
|
|
.. _pyexcel-ods3: https://github.com/pyexcel/pyexcel-ods3
|
|
.. _pyexcel-odsr: https://github.com/pyexcel/pyexcel-odsr
|
|
.. _pyexcel-xlsxw: https://github.com/pyexcel/pyexcel-xlsxw
|
|
.. _pyexcel-xlsxr: https://github.com/pyexcel/pyexcel-xlsxr
|
|
.. _pyexcel-htmlr: https://github.com/pyexcel/pyexcel-htmlr
|
|
|
|
.. _xlrd: https://github.com/python-excel/xlrd
|
|
.. _xlwt: https://github.com/python-excel/xlwt
|
|
.. _openpyxl: https://bitbucket.org/openpyxl/openpyxl
|
|
.. _XlsxWriter: https://github.com/jmcnamara/XlsxWriter
|
|
.. _pyexcel-ezodf: https://github.com/pyexcel/pyexcel-ezodf
|
|
.. _odfpy: https://github.com/eea/odfpy
|
|
|
|
|
|
In order to manage the list of plugins installed, you need to use pip to add or remove
|
|
a plugin. When you use virtualenv, you can have different plugins per virtual
|
|
environment. In the situation where you have multiple plugins that does the same thing
|
|
in your environment, you need to tell pyexcel which plugin to use per function call.
|
|
For example, pyexcel-ods and pyexcel-odsr, and you want to get_array to use pyexcel-odsr.
|
|
You need to append get_array(..., library='pyexcel-odsr').
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [#f1] zipped csv file
|
|
.. [#f2] zipped tsv file
|
|
|
|
If you need to manipulate the data, you might do it yourself or use its brother
|
|
library `pyexcel <https://github.com/pyexcel/pyexcel>`__ .
|
|
|
|
If you would like to extend it, you may use it to write your own
|
|
extension to handle a specific file format.
|
|
|
|
|
|
|
|
|
|
Installation
|
|
================================================================================
|
|
|
|
You can install pyexcel-io via pip:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ pip install pyexcel-io
|
|
|
|
|
|
or clone it and install it:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ git clone https://github.com/pyexcel/pyexcel-io.git
|
|
$ cd pyexcel-io
|
|
$ python setup.py install
|
|
|
|
|
|
|
|
Development guide
|
|
================================================================================
|
|
|
|
Development steps for code changes
|
|
|
|
#. git clone https://github.com/pyexcel/pyexcel-io.git
|
|
#. cd pyexcel-io
|
|
|
|
Upgrade your setup tools and pip. They are needed for development and testing only:
|
|
|
|
#. pip install --upgrade setuptools pip
|
|
|
|
Then install relevant development requirements:
|
|
|
|
#. pip install -r rnd_requirements.txt # if such a file exists
|
|
#. pip install -r requirements.txt
|
|
#. pip install -r tests/requirements.txt
|
|
|
|
Once you have finished your changes, please provide test case(s), relevant documentation
|
|
and update CHANGELOG.rst.
|
|
|
|
.. note::
|
|
|
|
As to rnd_requirements.txt, usually, it is created when a dependent
|
|
library is not released. Once the dependecy is installed
|
|
(will be released), the future
|
|
version of the dependency in the requirements.txt will be valid.
|
|
|
|
|
|
How to test your contribution
|
|
------------------------------
|
|
|
|
Although `nose` and `doctest` are both used in code testing, it is adviable that unit tests are put in tests. `doctest` is incorporated only to make sure the code examples in documentation remain valid across different development releases.
|
|
|
|
On Linux/Unix systems, please launch your tests like this::
|
|
|
|
$ make
|
|
|
|
On Windows systems, please issue this command::
|
|
|
|
> test.bat
|
|
|
|
How to update test environment and update documentation
|
|
---------------------------------------------------------
|
|
|
|
Additional steps are required:
|
|
|
|
#. pip install moban
|
|
#. git clone https://github.com/moremoban/setupmobans.git # generic setup
|
|
#. git clone https://github.com/pyexcel/pyexcel-commons.git commons
|
|
#. make your changes in `.moban.d` directory, then issue command `moban`
|
|
|
|
What is pyexcel-commons
|
|
---------------------------------
|
|
|
|
Many information that are shared across pyexcel projects, such as: this developer guide, license info, etc. are stored in `pyexcel-commons` project.
|
|
|
|
What is .moban.d
|
|
---------------------------------
|
|
|
|
`.moban.d` stores the specific meta data for the library.
|
|
|
|
Acceptance criteria
|
|
-------------------
|
|
|
|
#. Has Test cases written
|
|
#. Has all code lines tested
|
|
#. Passes all Travis CI builds
|
|
#. Has fair amount of documentation if your change is complex
|
|
#. Please update CHANGELOG.rst
|
|
#. Please add yourself to CONTRIBUTORS.rst
|
|
#. Agree on NEW BSD License for your contribution
|
|
|
|
|
|
|
|
License
|
|
================================================================================
|
|
|
|
New BSD License
|