Source code

Download source archive ↓

src/xlrd/__init__.py

1# Copyright (c) 2005-2012 Stephen John Machin, Lingfo Pty Ltd
2# This module is part of the xlrd package, which is released under a
3# BSD-style licence.
4import os
5import pprint
6import sys
7import zipfile
8
9from . import timemachine
10from .biffh import (
11    XL_CELL_BLANK, XL_CELL_BOOLEAN, XL_CELL_DATE, XL_CELL_EMPTY, XL_CELL_ERROR,
12    XL_CELL_NUMBER, XL_CELL_TEXT, XLRDError, biff_text_from_num,
13    error_text_from_code,
14)
15from .book import Book, colname, open_workbook_xls
16from .compdoc import SIGNATURE as XLS_SIGNATURE
17from .formula import *  # is constrained by __all__
18from .info import __VERSION__, __version__
19from .sheet import empty_cell
20from .xldate import XLDateError, xldate_as_datetime, xldate_as_tuple
21
22
23#: descriptions of the file types :mod:`xlrd` can :func:`inspect <inspect_format>`.
24FILE_FORMAT_DESCRIPTIONS = {
25    'xls': 'Excel xls',
26    'xlsb': 'Excel 2007 xlsb file',
27    'xlsx': 'Excel xlsx file',
28    'ods': 'Openoffice.org ODS file',
29    'zip': 'Unknown ZIP file',
30    None: 'Unknown file type',
31}
32
33ZIP_SIGNATURE = b"PK\x03\x04"
34
35PEEK_SIZE = max(len(XLS_SIGNATURE), len(ZIP_SIGNATURE))
36
37
38def inspect_format(path=None, content=None):
39    """
40    Inspect the content at the supplied path or the :class:`bytes` content provided
41    and return the file's type as a :class:`str`, or ``None`` if it cannot
42    be determined.
43
44    :param path:
45      A :class:`string <str>` path containing the content to inspect.
46      ``~`` will be expanded.
47
48    :param content:
49      The :class:`bytes` content to inspect.
50
51    :returns:
52       A :class:`str`, or ``None`` if the format cannot be determined.
53       The return value can always be looked up in :data:`FILE_FORMAT_DESCRIPTIONS`
54       to return a human-readable description of the format found.
55    """
56    if content:
57        peek = content[:PEEK_SIZE]
58    else:
59        path = os.path.expanduser(path)
60        with open(path, "rb") as f:
61            peek = f.read(PEEK_SIZE)
62
63    if peek.startswith(XLS_SIGNATURE):
64        return 'xls'
65
66    if peek.startswith(ZIP_SIGNATURE):
67        zf = zipfile.ZipFile(timemachine.BYTES_IO(content) if content else path)
68
69        # Workaround for some third party files that use forward slashes and
70        # lower case names. We map the expected name in lowercase to the
71        # actual filename in the zip container.
72        component_names = {name.replace('\\', '/').lower(): name
73                           for name in zf.namelist()}
74
75        if 'xl/workbook.xml' in component_names:
76            return 'xlsx'
77        if 'xl/workbook.bin' in component_names:
78            return 'xlsb'
79        if 'content.xml' in component_names:
80            return 'ods'
81        return 'zip'
82
83
84def open_workbook(filename=None,
85                  logfile=sys.stdout,
86                  verbosity=0,
87                  use_mmap=True,
88                  file_contents=None,
89                  encoding_override=None,
90                  formatting_info=False,
91                  on_demand=False,
92                  ragged_rows=False,
93                  ignore_workbook_corruption=False
94                  ):
95    """
96    Open a spreadsheet file for data extraction.
97
98    :param filename: The path to the spreadsheet file to be opened.
99
100    :param logfile: An open file to which messages and diagnostics are written.
101
102    :param verbosity: Increases the volume of trace material written to the
103                      logfile.
104
105    :param use_mmap:
106
107      Whether to use the mmap module is determined heuristically.
108      Use this arg to override the result.
109
110      Current heuristic: mmap is used if it exists.
111
112    :param file_contents:
113
114      A string or an :class:`mmap.mmap` object or some other behave-alike
115      object. If ``file_contents`` is supplied, ``filename`` will not be used,
116      except (possibly) in messages.
117
118    :param encoding_override:
119
120      Used to overcome missing or bad codepage information
121      in older-version files. See :doc:`unicode`.
122
123    :param formatting_info:
124
125      The default is ``False``, which saves memory.
126      In this case, "Blank" cells, which are those with their own formatting
127      information but no data, are treated as empty by ignoring the file's
128      ``BLANK`` and ``MULBLANK`` records.
129      This cuts off any bottom or right "margin" of rows of empty or blank
130      cells.
131      Only :meth:`~xlrd.sheet.Sheet.cell_value` and
132      :meth:`~xlrd.sheet.Sheet.cell_type` are available.
133
134      When ``True``, formatting information will be read from the spreadsheet
135      file. This provides all cells, including empty and blank cells.
136      Formatting information is available for each cell.
137
138      Note that this will raise a NotImplementedError when used with an
139      xlsx file.
140
141    :param on_demand:
142
143      Governs whether sheets are all loaded initially or when demanded
144      by the caller. See :doc:`on_demand`.
145
146    :param ragged_rows:
147
148      The default of ``False`` means all rows are padded out with empty cells so
149      that all rows have the same size as found in
150      :attr:`~xlrd.sheet.Sheet.ncols`.
151
152      ``True`` means that there are no empty cells at the ends of rows.
153      This can result in substantial memory savings if rows are of widely
154      varying sizes. See also the :meth:`~xlrd.sheet.Sheet.row_len` method.
155
156
157    :param ignore_workbook_corruption:
158
159      This option allows to read corrupted workbooks.
160      When ``False`` you may face CompDocError: Workbook corruption.
161      When ``True`` that exception will be ignored.
162
163    :returns: An instance of the :class:`~xlrd.book.Book` class.
164    """
165
166    file_format = inspect_format(filename, file_contents)
167    # We have to let unknown file formats pass through here, as some ancient
168    # files that xlrd can parse don't start with the expected signature.
169    if file_format and file_format != 'xls':
170        raise XLRDError(FILE_FORMAT_DESCRIPTIONS[file_format]+'; not supported')
171
172    bk = open_workbook_xls(
173        filename=filename,
174        logfile=logfile,
175        verbosity=verbosity,
176        use_mmap=use_mmap,
177        file_contents=file_contents,
178        encoding_override=encoding_override,
179        formatting_info=formatting_info,
180        on_demand=on_demand,
181        ragged_rows=ragged_rows,
182        ignore_workbook_corruption=ignore_workbook_corruption,
183    )
184
185    return bk
186
187
188def dump(filename, outfile=sys.stdout, unnumbered=False):
189    """
190    For debugging: dump an XLS file's BIFF records in char & hex.
191
192    :param filename: The path to the file to be dumped.
193    :param outfile: An open file, to which the dump is written.
194    :param unnumbered: If true, omit offsets (for meaningful diffs).
195    """
196    from .biffh import biff_dump
197    bk = Book()
198    bk.biff2_8_load(filename=filename, logfile=outfile, )
199    biff_dump(bk.mem, bk.base, bk.stream_len, 0, outfile, unnumbered)
200
201
202def count_records(filename, outfile=sys.stdout):
203    """
204    For debugging and analysis: summarise the file's BIFF records.
205    ie: produce a sorted file of ``(record_name, count)``.
206
207    :param filename: The path to the file to be summarised.
208    :param outfile: An open file, to which the summary is written.
209    """
210    from .biffh import biff_count_records
211    bk = Book()
212    bk.biff2_8_load(filename=filename, logfile=outfile, )
213    biff_count_records(bk.mem, bk.base, bk.stream_len, outfile)