Loading worksheets on demand¶
This feature, new in version 0.7.1, is governed by the
open_workbook() function and allows saving memory and time by
loading only those sheets that the caller is interested in, and releasing sheets
when no longer required.
- No change.
open_workbook()loads global data and all sheets, releases resources no longer required (principally the
mmap.mmapobject containing the Workbook stream), and returns.
on_demand=Trueand BIFF version < 5.0:
- A warning message is emitted,
on_demandis recorded as
False, and the old process is followed.
on_demand=Trueand BIFF version >= 5.0:
open_workbook()loads global data and returns without releasing resources. At this stage, the only information available about sheets is
Book.sheets() will load all unloaded sheets.
The caller may save memory by calling
Book.unload_sheet() when finished with the sheet.
This applies irrespective of the state of
The caller may re-load an unloaded sheet by calling
Book.sheet_by_index(), except if the required resources have been
released (which will
have happened automatically when
on_demand is false). This is the only
case where an exception will be raised.
The caller may query the state of a sheet using
Book.release_resources() may used to save memory and close
any memory-mapped file before proceeding to examine already-loaded
sheets. Once resources are released, no further sheets can be loaded.
When using on-demand, it is advisable to ensure that
Book.release_resources() is always called, even if an exception
is raised in your own code; otherwise if the input file has been
mmap.mmap object will not be closed and you will
not be able to access the physical file until your Python process
terminates. This can be done by calling
explicitly in the finally part of a try/finally block.
The Book object is also a context manager, so you can wrap your code in a
with statement that will make sure underlying resources are closed.