pyexcel-xls is a tiny wrapper library to read, manipulate and write data in xls format and it can read xlsx and xlsm fromat. You are likely to use it with pyexcel.
1. v0.7.0 removed the pin on xlrd < 2. If you have xlrd >= 2, this library will NOT read 'xlsx' format and you need to install pyexcel-xlsx. Othwise, this library can use xlrd < 2 to read xlsx format for you. So 'xlsx' support in this library will vary depending on the installed version of xlrd.
2. v0.7.0 can write datetime.timedelta. but when the value is read out, you will get datetime.datetime. so you as the developer decides what to do with it.
detect_merged_cells allows you to spread the same value among all merged cells. But be aware that this may slow down its reading performance.
skip_hidden_row_and_column allows you to skip hidden rows and columns and is defaulted to True. It may slow down its reading performance. And it is only valid for 'xls' files. For 'xlsx' files, please use pyexcel-xlsx.
xls file cannot contain more than 65,000 rows. You are risking the reputation of yourself/your company/ your country if you keep using xls and are not aware of its row limit.
If your company uses pyexcel and its components in a revenue-generating product, please consider supporting the project on GitHub or Patreon. Your financial support will enable me to dedicate more time to coding, improving documentation, and creating engaging content.
Fonts, colors and charts are not supported.
Nor to read password protected xls, xlsx and ods files.
You can install pyexcel-xls via pip:
$ pip install pyexcel-xls
or clone it and install it:
$ git clone https://github.com/pyexcel/pyexcel-xls.git
$ cd pyexcel-xls
$ python setup.py install.. testcode::
:hide:
>>> import os
>>> import sys
>>> from io import BytesIO
>>> from collections import OrderedDict
Here's the sample code to write a dictionary to an xls file:
>>> from pyexcel_xls 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.xls", data)
Here's the sample code:
>>> from pyexcel_xls import get_data >>> data = get_data("your_file.xls") >>> import json >>> print(json.dumps(data)) {"Sheet 1": [[1, 2, 3], [4, 5, 6]], "Sheet 2": [["row 1", "row 2", "row 3"]]}
Here's the sample code to write a dictionary to an xls file:
>>> from pyexcel_xls 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 = BytesIO() >>> save_data(io, data) >>> # do something with the io >>> # In reality, you might give it to your http response >>> # object for downloading
Continue from previous example:
>>> # This is just an illustration >>> # In reality, you might deal with xls file upload >>> # where you will read from requests.FILES['YOUR_XLS_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]]}
Let's assume the following file is a huge xls file:
>>> 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.xls", sheetx)
And let's pretend to read partial data:
>>> partial_data = get_data("huge_file.xls", 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:
>>> partial_data = get_data("huge_file.xls", 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:
>>> partial_data = get_data("huge_file.xls", ... start_row=2, row_limit=3, ... start_column=1, column_limit=2) >>> print(json.dumps(partial_data)) {"huge": [[23, 33], [24, 34], [25, 35]]}
.. testcode::
:hide:
>>> os.unlink("huge_file.xls")
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 xls format, installing it is enough.
Here is the sample code:
>>> import pyexcel as pe >>> sheet = pe.get_book(file_name="your_file.xls") >>> sheet Sheet 1: +---+---+---+ | 1 | 2 | 3 | +---+---+---+ | 4 | 5 | 6 | +---+---+---+ Sheet 2: +-------+-------+-------+ | row 1 | row 2 | row 3 | +-------+-------+-------+
Here is the sample code:
>>> sheet.save_as("another_file.xls")
You got to wrap the binary content with stream to get xls working:
>>> # This is just an illustration >>> # In reality, you might deal with xls file upload >>> # where you will read from requests.FILES['YOUR_XLS_FILE'] >>> xlsfile = "another_file.xls" >>> with open(xlsfile, "rb") as f: ... content = f.read() ... r = pe.get_book(file_type="xls", file_content=content) ... print(r) ... Sheet 1: +---+---+---+ | 1 | 2 | 3 | +---+---+---+ | 4 | 5 | 6 | +---+---+---+ Sheet 2: +-------+-------+-------+ | row 1 | row 2 | row 3 | +-------+-------+-------+
You need to pass a BytesIO instance to Writer:
>>> data = [ ... [1, 2, 3], ... [4, 5, 6] ... ] >>> io = BytesIO() >>> sheet = pe.Sheet(data) >>> io = sheet.save_to_memory("xls", io) >>> # then do something with io >>> # In reality, you might give it to your http response >>> # object for downloading
New BSD License
Development steps for code changes
- git clone https://github.com/pyexcel/pyexcel-xls.git
- cd pyexcel-xls
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.
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
Please run:
$ make format
so as to beautify your code otherwise your build may fail your unit test.
- If a zero was typed in a DATE formatted field in xls, you will get "01/01/1900".
- If a zero was typed in a TIME formatted field in xls, you will get "00:00:00".
.. testcode::
:hide:
>>> import os
>>> os.unlink("your_file.xls")
>>> os.unlink("another_file.xls")