pyexcel-odsr 0.5.1

================================================================================
pyexcel-odsr - Let you focus on data, instead of ods format
================================================================================

.. image:: https://raw.githubusercontent.com/pyexcel/pyexcel.github.io/master/images/patreon.png
:target: https://www.patreon.com/pyexcel

.. image:: https://api.travis-ci.org/pyexcel/pyexcel-odsr.svg?branch=master
:target: http://travis-ci.org/pyexcel/pyexcel-odsr

.. image:: https://codecov.io/gh/pyexcel/pyexcel-odsr/branch/master/graph/badge.svg
:target: https://codecov.io/gh/pyexcel/pyexcel-odsr

.. image:: https://img.shields.io/gitter/room/gitterHQ/gitter.svg
:target: https://gitter.im/pyexcel/Lobby


**pyexcel-odsr** is a specialized ods reader based on tailored ods reader from
`messytables <https://github.com/okfn/messytables>`_.
You are likely to use it with `pyexcel <https://github.com/pyexcel/pyexcel>`_.
Differring from `pyexcel-ods <https://github.com/pyexcel/pyexcel-ods>`_ and
`pyexcel-ods3 <https://github.com/pyexcel/pyexcel-ods3>`_ in handling ods file, this
library could read partial content from a huge ods file.


Known constraints
==================

Fonts, colors and charts are not supported.

Installation
================================================================================

You can install it via pip:

.. code-block:: bash

$ pip install pyexcel-odsr


or clone it and install it:

.. code-block:: bash

$ git clone https://github.com/pyexcel/pyexcel-odsr.git
$ cd pyexcel-odsr
$ python setup.py install

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>`_ to
maintain the project and develop it further.

If you are an individual, you are welcome to support me too on patreon and for however long
you feel like to. As a patreon, you will receive
`early access to pyexcel related contents <https://www.patreon.com/pyexcel/posts>`_.

With your financial support, I will be able to invest
a little bit more time in coding, documentation and writing interesting posts.


Usage
================================================================================

As a standalone library
--------------------------------------------------------------------------------

Read from an ods file
********************************************************************************

Here's the sample code:

.. code-block:: python

>>> from pyexcel_odsr import get_data
>>> data = get_data("your_file.ods")
>>> import json
>>> print(json.dumps(data))
{"Sheet 1": [[1, 2, 3], [4, 5, 6]], "Sheet 2": [["row 1", "row 2", "row 3"]]}



Read from an ods from memory
********************************************************************************

Continue from previous example:

.. code-block:: python

>>> # This is just an illustration
>>> # In reality, you might deal with ods file upload
>>> # where you will read from requests.FILES['YOUR_ODS_FILE']
>>> data = get_data(io)
>>> print(json.dumps(data))
{"Sheet 1": [[1, 2, 3], [4, 5, 6]], "Sheet 2": [[7, 8, 9], [10, 11, 12]]}


Pagination feature
********************************************************************************



Let's assume the following file is a huge ods file:

.. code-block:: python

>>> huge_data = [
... [1, 21, 31],
... [2, 22, 32],
... [3, 23, 33],
... [4, 24, 34],
... [5, 25, 35],
... [6, 26, 36]
... ]
>>> sheetx = {
... "huge": huge_data
... }
>>> save_data("huge_file.ods", sheetx)

And let's pretend to read partial data:

.. code-block:: python

>>> partial_data = get_data("huge_file.ods", start_row=2, row_limit=3)
>>> print(json.dumps(partial_data))
{"huge": [[3, 23, 33], [4, 24, 34], [5, 25, 35]]}

And you could as well do the same for columns:

.. code-block:: python

>>> partial_data = get_data("huge_file.ods", start_column=1, column_limit=2)
>>> print(json.dumps(partial_data))
{"huge": [[21, 31], [22, 32], [23, 33], [24, 34], [25, 35], [26, 36]]}

Obvious, you could do both at the same time:

.. code-block:: python

>>> partial_data = get_data("huge_file.ods",
... start_row=2, row_limit=3,
... start_column=1, column_limit=2)
>>> print(json.dumps(partial_data))
{"huge": [[23, 33], [24, 34], [25, 35]]}

As a pyexcel plugin
--------------------------------------------------------------------------------

No longer, explicit import is needed since pyexcel version 0.2.2. Instead,
this library is auto-loaded. So if you want to read data in ods format,
installing it is enough.


Reading from an ods file
********************************************************************************

Here is the sample code:

.. code-block:: python

>>> import pyexcel as pe
>>> sheet = pe.get_book(file_name="your_file.ods")
>>> sheet
Sheet 1:
+---+---+---+
| 1 | 2 | 3 |
+---+---+---+
| 4 | 5 | 6 |
+---+---+---+
Sheet 2:
+-------+-------+-------+
| row 1 | row 2 | row 3 |
+-------+-------+-------+



Reading from a IO instance
********************************************************************************

You got to wrap the binary content with stream to get ods working:

.. code-block:: python

>>> # This is just an illustration
>>> # In reality, you might deal with ods file upload
>>> # where you will read from requests.FILES['YOUR_ODS_FILE']
>>> odsfile = "another_file.ods"
>>> with open(odsfile, "rb") as f:
... content = f.read()
... r = pe.get_book(file_type="ods", file_content=content)
... print(r)
...
Sheet 1:
+---+---+---+
| 1 | 2 | 3 |
+---+---+---+
| 4 | 5 | 6 |
+---+---+---+
Sheet 2:
+-------+-------+-------+
| row 1 | row 2 | row 3 |
+-------+-------+-------+




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

New BSD License

Developer guide
==================

Development steps for code changes

#. git clone https://github.com/pyexcel/pyexcel-odsr.git
#. cd pyexcel-odsr

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

Credits
================================================================================

This library is based on the ods of messytables, Open Knowledge Foundation Ltd.



Contributors
================

Author is in setup.py file and module __author__. Hence please find the
contributors here.

In alphabetic order:

*. `Jona <https://github.com/jonadem>`_



Change log
================================================================================

0.5.1 - 20.10.2017
--------------------------------------------------------------------------------

added
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

#. `#103 <https://github.com/pyexcel/pyexcel/issues/103>`_, include LICENSE file
in MANIFEST.in, meaning LICENSE file will appear in the released tar ball.

0.5.0 - 30.08.2017
--------------------------------------------------------------------------------

Updated
********************************************************************************

#. put dependency on pyexcel-io 0.5.0, which uses cStringIO instead of StringIO.
Hence, there will be performance boost in handling files in memory.

Relocated
--------------------------------------------------------------------------------

#. All ods type conversion code lives in pyexcel_io.service module

0.4.3 - 25.08.2017
--------------------------------------------------------------------------------

#. `#4 <https://github.com/pyexcel/pyexcel-odsr/issues/4>`_, handle unseekable
stream given by http response.

0.4.2 - 20.08.2017
--------------------------------------------------------------------------------

Fix package installation error

0.4.1 - 26.07.2017
--------------------------------------------------------------------------------

Updated
********************************************************************************

#. PR `#3 <https://github.com/pyexcel/pyexcel-odsr/pull/3>`_, support fods, flat
ods file

0.4.0 - 19.06.2017
--------------------------------------------------------------------------------

Updated
********************************************************************************

#. Updated to use lml interface


0.3.2 - 07.05.2017
--------------------------------------------------------------------------------

Updated
********************************************************************************

#. issue `#2 <https://github.com/pyexcel/pyexcel-odsr/issues/2>`_, not all texts
in a multi-node cell were extracted.

0.3.1 - 13.04.2017
--------------------------------------------------------------------------------

Updated
********************************************************************************

#. issue `#1 <https://github.com/pyexcel/pyexcel-odsr/issues/1>`_, PT288H00M00S
is valid duration


0.3.0 - 02.02.2017
--------------------------------------------------------------------------------

#. initial release. It has all functionalities of pyexcel-ods and pyexcel-ods3.
Specially, it supports partial reading of the ods file. When dealing with
big data file, this capability enables pagination feature to indeed read
partial files.