Metadata-Version: 1.1
Name: pyexcel-ods
Version: 0.2.2
Summary: A wrapper library to read, manipulate and write data in ods format
Home-page: UNKNOWN
Author: C.W.
Author-email: wangc_2011 (at) hotmail.com
License: New BSD
Description: ================================================================================
        pyexcel-ods - Let you focus on data, instead of ods format
        ================================================================================
        
        .. image:: https://api.travis-ci.org/pyexcel/pyexcel-ods.png
            :target: http://travis-ci.org/pyexcel/pyexcel-ods
        
        .. image:: https://codecov.io/github/pyexcel/pyexcel-ods/coverage.png
            :target: https://codecov.io/github/pyexcel/pyexcel-ods
        
        **pyexcel-ods** is a tiny wrapper library to read, manipulate and write data in
        ods format using python 2.6 and python 2.7. You are likely to use it with
        `pyexcel <https://github.com/pyexcel/pyexcel>`_.
        `pyexcel-ods3 <https://github.com/pyexcel/pyexcel-ods3>`_ is a sister library that
        does the same thing but supports Python 3.3 and 3.4 and depends on lxml.
        
        Known constraints
        ==================
        
        Fonts, colors and charts are not supported.
        
        Installation
        ================================================================================
        
        You can install it via pip:
        
        .. code-block:: bash
        
            $ pip install pyexcel-ods
        
        
        or clone it and install it:
        
        .. code-block:: bash
        
            $ git clone http://github.com/pyexcel/pyexcel-ods.git
            $ cd pyexcel-ods
            $ python setup.py install
        
        Usage
        ================================================================================
        
        As a standalone library
        --------------------------------------------------------------------------------
        
        Write to an ods file
        ********************************************************************************
        
        Here's the sample code to write a dictionary to an ods file:
        
        .. code-block:: python
        
            >>> from pyexcel_ods import save_data
            >>> data = OrderedDict() # from collections import OrderedDict
            >>> data.update({"Sheet 1": [[1, 2, 3], [4, 5, 6]]})
            >>> data.update({"Sheet 2": [["row 1", "row 2", "row 3"]]})
            >>> save_data("your_file.ods", data)
        
        Read from an ods file
        ********************************************************************************
        
        Here's the sample code:
        
        .. code-block:: python
        
            >>> from pyexcel_ods 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"]]}
        
        
        Write an ods to memory
        ********************************************************************************
        
        Here's the sample code to write a dictionary to an ods file:
        
        .. code-block:: python
        
            >>> from pyexcel_ods import save_data
            >>> data = OrderedDict()
            >>> data.update({"Sheet 1": [[1, 2, 3], [4, 5, 6]]})
            >>> data.update({"Sheet 2": [[7, 8, 9], [10, 11, 12]]})
            >>> io = StringIO()
            >>> save_data(io, data)
            >>> # do something with the io
            >>> # In reality, you might give it to your http response
            >>> # object for downloading
        
        
        
        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.
        
        Any version under pyexcel 0.2.2, you have to keep doing the following:
        
        Import it in your file to enable this plugin:
        
        .. code-block:: python
        
            from pyexcel.ext import ods
        
        Please note only pyexcel version 0.0.4+ support this.
        
        
        Reading from an ods file
        ********************************************************************************
        
        Here is the sample code:
        
        .. code-block:: python
        
            >>> import pyexcel as pe
            >>> # from pyexcel.ext import ods
            >>> 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 |
            +-------+-------+-------+
        
        
        Writing to an ods file
        ********************************************************************************
        
        Here is the sample code:
        
        .. code-block:: python
        
            >>> sheet.save_as("another_file.ods")
        
        
        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 |
            +-------+-------+-------+
        
        
        Writing to a StringIO instance
        ********************************************************************************
        
        You need to pass a StringIO instance to Writer:
        
        .. code-block:: python
        
            >>> data = [
            ...     [1, 2, 3],
            ...     [4, 5, 6]
            ... ]
            >>> io = StringIO()
            >>> sheet = pe.Sheet(data)
            >>> io = sheet.save_to_memory("ods", io)
            >>> # then do something with io
            >>> # In reality, you might give it to your http response
            >>> # object for downloading
        
        License
        ================================================================================
        
        New BSD License
        
        Developer guide
        ==================
        
        Development steps for code changes
        
        #. git clone https://github.com/pyexcel/pyexcel-ods.git
        #. cd pyexcel-ods
        
        Upgrade your setup tools and pip. They are needed for development and testing only:
        
        #. pip install --upgrade setuptools "pip==7.1"
        
        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
        
        
        In order to update test environment, and documentation, additional setps are
        required:
        
        #. pip install moban
        #. git clone https://github.com/pyexcel/pyexcel-commons.git
        #. make your changes in `.moban.d` directory, then issue command `moban`
        
        What is 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.
        
        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.
        
        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 test
        
        On Windows systems, please issue this command::
        
            > test.bat
        
        Credits
        ================================================================================
        
        ODSReader is originally written by `Marco Conti <https://github.com/marcoconti83/read-ods-with-odfpy>`_
        
        
        Change log
        ================================================================================
        
        0.2.2 - unreleased
        --------------------------------------------------------------------------------
        
        Updated
        ********************************************************************************
        
        #. issue `#14 <https://github.com/pyexcel/pyexcel-ods/issues/14>`_, index error
           when reading a ods file that has non-uniform columns repeated property.
        
        
        0.2.1 - 31.08.2016
        --------------------------------------------------------------------------------
        
        Added
        ********************************************************************************
        
        #. support pagination. two pairs: start_row, row_limit and start_column,
           column_limit help you deal with large files.
        #. use odfpy 1.3.3 as compulsory package. offically support python 3
        
        0.2.0 - 01.06.2016
        --------------------------------------------------------------------------------
        
        Added
        ********************************************************************************
        
        #. By default, `float` will be converted to `int` where fits. `auto_detect_int`,
           a flag to switch off the autoatic conversion from `float` to `int`.
        #. 'library=pyexcel-ods' was added so as to inform pyexcel to use it instead of
           other libraries, in the situation where multiple plugins were installed.
        
        
        Updated
        ********************************************************************************
        
        #. support the auto-import feature of pyexcel-io 0.2.0
        
        
        0.1.1 - 30.01.2016
        --------------------------------------------------------------------------------
        
        Added
        ********************************************************************************
        
        #. 'streaming' is an extra option given to get_data. Only when 'streaming'
           is explicitly set to True, the data will be consisted of generators,
           hence will break your existing code.
        #. uses yield in to_array and returns a generator
        #. support multi-line text cell #5
        #. feature migration from pyexcel-ods3 pyexcel/pyexcel-ods3#5
        
        Updated
        ********************************************************************************
        #. compatibility with pyexcel-io 0.1.1
        
        
        0.0.12 - 10.10.2015
        --------------------------------------------------------------------------------
        
        Updated
        ********************************************************************************
        #. Bug fix: excessive trailing columns with empty values
        
        
        0.0.11 - 26.09.2015
        --------------------------------------------------------------------------------
        
        Updated
        ********************************************************************************
        #. Complete fix for libreoffice datetime field
        
        
        0.0.10 - 15.09.2015
        --------------------------------------------------------------------------------
        
        Updated
        ********************************************************************************
        #. Bug fix: date field could have datetime from libreoffice
        
        
        0.0.9 - 21.08.2015
        --------------------------------------------------------------------------------
        
        Updated
        ********************************************************************************
        #. Bug fix: utf-8 string throw unicode exceptions
        
        
        0.0.8 - 28.06.2015
        --------------------------------------------------------------------------------
        
        Updated
        ********************************************************************************
        #. Pin dependency odfpy 0.9.6 to avoid buggy odfpy 1.3.0
        
        
        0.0.7 - 28.05.2015
        --------------------------------------------------------------------------------
        
        Updated
        ********************************************************************************
        #. Bug fix: "number-columns-repeated" is now respected
        
        
        0.0.6 - 21.05.2015
        --------------------------------------------------------------------------------
        
        Updated
        ********************************************************************************
        #. get_data and save_data are seen across pyexcel-* extensions. remember them
           once and use them across all extensions.
        
        
        0.0.5 - 22.02.2015
        --------------------------------------------------------------------------------
        
        Added
        ********************************************************************************
        
        #. Loads only one sheet from a multiple sheet book
        #. Use New BSD License
        
        
        0.0.4 - 14.12.2014
        --------------------------------------------------------------------------------
        
        Updated
        ********************************************************************************
        #. IO interface update as pyexcel-io introduced keywords.
        
        
        0.0.3 - 08.12.2014
        --------------------------------------------------------------------------------
        
        #. initial release
        
        
Keywords: excel,python,pyexcel
Platform: UNKNOWN
Classifier: Topic :: Office/Business
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: BSD License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
