248 lines
9.2 KiB
ReStructuredText
248 lines
9.2 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/chfw
|
|
|
|
.. image:: https://raw.githubusercontent.com/pyexcel/pyexcel-mobans/master/images/awesome-badge.svg
|
|
:target: https://awesome-python.com/#specific-formats-processing
|
|
|
|
.. image:: https://github.com/pyexcel/pyexcel-io/workflows/run_tests/badge.svg
|
|
:target: http://github.com/pyexcel/pyexcel-io/actions
|
|
|
|
.. image:: https://codecov.io/gh/pyexcel/pyexcel-io/branch/master/graph/badge.svg
|
|
:target: https://codecov.io/gh/pyexcel/pyexcel-io
|
|
|
|
.. image:: https://badge.fury.io/py/pyexcel-io.svg
|
|
:target: https://pypi.org/project/pyexcel-io
|
|
|
|
.. image:: https://anaconda.org/conda-forge/pyexcel-io/badges/version.svg
|
|
:target: https://anaconda.org/conda-forge/pyexcel-io
|
|
|
|
.. image:: https://pepy.tech/badge/pyexcel-io/month
|
|
:target: https://pepy.tech/project/pyexcel-io
|
|
|
|
.. image:: https://anaconda.org/conda-forge/pyexcel-io/badges/downloads.svg
|
|
:target: https://anaconda.org/conda-forge/pyexcel-io
|
|
|
|
.. image:: https://img.shields.io/gitter/room/gitterHQ/gitter.svg
|
|
:target: https://gitter.im/pyexcel/Lobby
|
|
|
|
.. image:: https://img.shields.io/static/v1?label=continuous%20templating&message=%E6%A8%A1%E7%89%88%E6%9B%B4%E6%96%B0&color=blue&style=flat-square
|
|
:target: https://moban.readthedocs.io/en/latest/#at-scale-continous-templating-for-open-source-projects
|
|
|
|
.. image:: https://img.shields.io/static/v1?label=coding%20style&message=black&color=black&style=flat-square
|
|
:target: https://github.com/psf/black
|
|
.. 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 github, `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.
|
|
|
|
Nor to read password protected xls, xlsx and ods files.
|
|
|
|
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
|
|
======================== ======================= =================
|
|
`pyexcel-io`_ csv, csvz [#f1]_, tsv,
|
|
tsvz [#f2]_
|
|
`pyexcel-xls`_ xls, xlsx(read only), `xlrd`_,
|
|
xlsm(read only) `xlwt`_
|
|
`pyexcel-xlsx`_ xlsx `openpyxl`_
|
|
`pyexcel-ods3`_ ods `pyexcel-ezodf`_,
|
|
lxml
|
|
`pyexcel-ods`_ ods `odfpy`_
|
|
======================== ======================= =================
|
|
|
|
.. table:: Dedicated file reader and writers
|
|
|
|
======================== ======================= =================
|
|
Package name Supported file formats Dependencies
|
|
======================== ======================= =================
|
|
`pyexcel-xlsxw`_ xlsx(write only) `XlsxWriter`_
|
|
`pyexcel-libxlsxw`_ xlsx(write only) `libxlsxwriter`_
|
|
`pyexcel-xlsxr`_ xlsx(read only) lxml
|
|
`pyexcel-xlsbr`_ xlsb(read only) pyxlsb
|
|
`pyexcel-odsr`_ read only for ods, fods lxml
|
|
`pyexcel-odsw`_ write only for ods loxun
|
|
`pyexcel-htmlr`_ html(read only) lxml,html5lib
|
|
`pyexcel-pdfr`_ pdf(read only) camelot
|
|
======================== ======================= =================
|
|
|
|
|
|
Plugin shopping guide
|
|
------------------------
|
|
|
|
Since 2020, all pyexcel-io plugins have dropped the support for python versions
|
|
which are lower than 3.6. If you want to use any of those Python versions, please use pyexcel-io
|
|
and its plugins versions that are lower than 0.6.0.
|
|
|
|
|
|
Except csv files, xls, xlsx and ods files are a zip of a folder containing a lot of
|
|
xml files
|
|
|
|
The dedicated readers for excel files can stream read
|
|
|
|
|
|
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').
|
|
|
|
|
|
|
|
.. _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-odsw: https://github.com/pyexcel/pyexcel-odsw
|
|
.. _pyexcel-pdfr: https://github.com/pyexcel/pyexcel-pdfr
|
|
|
|
.. _pyexcel-xlsxw: https://github.com/pyexcel/pyexcel-xlsxw
|
|
.. _pyexcel-libxlsxw: https://github.com/pyexcel/pyexcel-libxlsxw
|
|
.. _pyexcel-xlsxr: https://github.com/pyexcel/pyexcel-xlsxr
|
|
.. _pyexcel-xlsbr: https://github.com/pyexcel/pyexcel-xlsbr
|
|
.. _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
|
|
.. _libxlsxwriter: http://libxlsxwriter.github.io/getting_started.html
|
|
|
|
|
|
.. 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.yml
|
|
|
|
.. 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, please issue this command::
|
|
|
|
> test.bat
|
|
|
|
|
|
Before you commit
|
|
------------------------------
|
|
|
|
Please run::
|
|
|
|
$ make format
|
|
|
|
so as to beautify your code otherwise your build may fail your unit test.
|
|
|
|
|
|
|
|
|
|
License
|
|
================================================================================
|
|
|
|
New BSD License
|