pyexcel-xlsx 0.6.1
A wrapper library to read, manipulate and write data in xlsx and xlsmformat
License: New BSD
Requires Python: >=3.6
Keywords: python, xlsx

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

.. 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://codecov.io/gh/pyexcel/pyexcel-xlsx/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/pyexcel/pyexcel-xlsx

.. image:: https://badge.fury.io/py/pyexcel-xlsx.svg
   :target: https://pypi.org/project/pyexcel-xlsx

.. image:: https://anaconda.org/conda-forge/pyexcel-xlsx/badges/version.svg
   :target: https://anaconda.org/conda-forge/pyexcel-xlsx


.. image:: https://pepy.tech/badge/pyexcel-xlsx/month
   :target: https://pepy.tech/project/pyexcel-xlsx

.. image:: https://anaconda.org/conda-forge/pyexcel-xlsx/badges/downloads.svg
   :target: https://anaconda.org/conda-forge/pyexcel-xlsx

.. 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

**pyexcel-xlsx** is a tiny wrapper library to read, manipulate and write data in xlsx and xlsm format using  `read_only` mode reader, `write_only` mode writer from openpyxl. You are likely to use it with `pyexcel <https://github.com/pyexcel/pyexcel>`__.

Please note:

1. `auto_detect_int` flag will not take effect because openpyxl detect integer in python 3 by default.
2. `skip_hidden_row_and_column` will get a penalty where `read_only` mode cannot be used.



Support the project
================================================================================

If your company has embedded pyexcel and its components into a revenue generating
product, please support me on github, or `patreon <https://www.patreon.com/bePatron?u=5537627>`_
maintain the project and develop it further.

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.

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


You can install pyexcel-xlsx via pip:

.. code-block:: bash

    $ pip install pyexcel-xlsx


or clone it and install it:

.. code-block:: bash

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

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

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

Write to an xlsx file
********************************************************************************



Here's the sample code to write a dictionary to an xlsx file:

.. code-block:: python

    >>> from pyexcel_xlsx 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.xlsx", data)


Read from an xlsx file
********************************************************************************

Here's the sample code:

.. code-block:: python

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


Write an xlsx to memory
********************************************************************************

Here's the sample code to write a dictionary to an xlsx file:

.. code-block:: python

    >>> from pyexcel_xlsx 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 xlsx from memory
********************************************************************************

Continue from previous example:

.. code-block:: python

    >>> # This is just an illustration
    >>> # In reality, you might deal with xlsx file upload
    >>> # where you will read from requests.FILES['YOUR_XLSX_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 xlsx 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.xlsx", sheetx)

And let's pretend to read partial data:

.. code-block:: python

   >>> partial_data = get_data("huge_file.xlsx", 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.xlsx", 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.xlsx",
   ...     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 xlsx format,
installing it is enough.


Reading from an xlsx file
********************************************************************************

Here is the sample code:

.. code-block:: python

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


Writing to an xlsx file
********************************************************************************

Here is the sample code:

.. code-block:: python

    >>> sheet.save_as("another_file.xlsx")


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

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

.. code-block:: python

    >>> # This is just an illustration
    >>> # In reality, you might deal with xlsx file upload
    >>> # where you will read from requests.FILES['YOUR_XLSX_FILE']
    >>> xlsxfile = "another_file.xlsx"
    >>> with open(xlsxfile, "rb") as f:
    ...     content = f.read()
    ...     r = pe.get_book(file_type="xlsx", 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("xlsx", 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-xlsx.git
#. cd pyexcel-xlsx

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 dependency 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 advisable
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.




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

0.6.1 - 10.11.2024
--------------------------------------------------------------------------------

**Updated**

#. Compatability with openpyxl 3.1.0 and later

0.6.0 - 10.10.2020
--------------------------------------------------------------------------------

**Updated**

#. New style xlsx plugins, promoted by pyexcel-io v0.6.2.

0.5.8 - 28.12.2019
--------------------------------------------------------------------------------

**Updated**

#. `#34 <https://github.com/pyexcel/pyexcel-xlsx/issues/34>`_: pin
   openpyxl>=2.6.1

0.5.7 - 15.02.2019
--------------------------------------------------------------------------------

**Added**

#. `pyexcel-io#66 <https://github.com/pyexcel/pyexcel-io/issues/66>`_ pin
   openpyxl < 2.6.0

0.5.6 - 26.03.2018
--------------------------------------------------------------------------------

**Added**

#. `#24 <https://github.com/pyexcel/pyexcel-xlsx/issues/24>`_, remove deprecated
   warning from merged_cell_ranges and get_sheet_by_name

0.5.5 - 18.12.2017
--------------------------------------------------------------------------------

**Added**

#. `#22 <https://github.com/pyexcel/pyexcel-xlsx/issues/22>`_, to detect merged
   cell in xlsx - fast tracked patreon request.

0.5.4 - 2.11.2017
--------------------------------------------------------------------------------

**Updated**

#. Align the behavior of skip_hidden_row_and_column. Default it to True.

0.5.3 - 2.11.2017
--------------------------------------------------------------------------------

**Added**

#. `#20 <https://github.com/pyexcel/pyexcel-xlsx/issues/20>`_, skip hidden rows
   and columns under 'skip_hidden_row_and_column' flag.

0.5.2 - 23.10.2017
--------------------------------------------------------------------------------

**updated**

#. pyexcel `pyexcel#105 <https://github.com/pyexcel/pyexcel/issues/105>`_,
   remove gease from setup_requires, introduced by 0.5.1.
#. remove python2.6 test support
#. update its dependecy on pyexcel-io to 0.5.3

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

**added**

#. `pyexcel#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.

**Removed**

#. `#18 <https://github.com/pyexcel/pyexcel-xlsx/issues/18>`_, is handled in
   pyexcel-io

0.4.2 - 25.08.2017
--------------------------------------------------------------------------------

**Updated**

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

0.4.1 - 16.07.2017
--------------------------------------------------------------------------------

**Removed**

#. Removed useless code

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

**Updated**

#. `#14 <https://github.com/pyexcel/pyexcel-xlsx/issues/14>`_, close file handle
#. pyexcel-io plugin interface now updated to use `lml
   <https://github.com/chfw/lml>`_.

0.3.0 - 22.12.2016
--------------------------------------------------------------------------------

**Updated**

#. Code refactoring with pyexcel-io v 0.3.0
#. `#13 <https://github.com/pyexcel/pyexcel-xlsx/issues/13>`_, turn read_only
   flag on openpyxl.

0.2.3 - 05.11.2016
--------------------------------------------------------------------------------

**Updated**

#. `#12 <https://github.com/pyexcel/pyexcel-xlsx/issues/12>`_, remove
   UserWarning: Using a coordinate with ws.cell is deprecated. Use
   ws[coordinate]

0.2.2 - 31.08.2016
--------------------------------------------------------------------------------

**Added**

#. support pagination. two pairs: start_row, row_limit and start_column,
   column_limit help you deal with large files.

0.2.1 - 12.07.2016
--------------------------------------------------------------------------------

**Added**

#. `#8 <https://github.com/pyexcel/pyexcel-xlsx/issues/8>`__,
   `skip_hidden_sheets` is added. By default, hidden sheets are skipped when
   reading all sheets. Reading sheet by name or by index are not affected.

0.2.0 - 01.06.2016
--------------------------------------------------------------------------------

**Added**

#. 'library=pyexcel-xlsx' was added to inform pyexcel to use it instead of other
   libraries, in the situation where there are more than one plugin for a file
   type, e.g. xlsm

**Updated**

#. support the auto-import feature of pyexcel-io 0.2.0

0.1.0 - 17.01.2016
--------------------------------------------------------------------------------

**Added**

#. Passing "streaming=True" to get_data, you will get the two dimensional array
   as a generator
#. Passing "data=your_generator" to save_data is acceptable too.

**Updated**

#. compatibility with pyexcel-io 0.1.0