Package: eg.spreader
SpreaderA fast spreadsheet logic library.Spreader is a zero dependency library that implements spreadsheet logic - reading and writing data and formulas into cells, automatic recalculation, copying and moving cells, adding and deleting rows and columns and so on. It does not implement any spreadsheet UI.
It is currently in alpha stage.InstallSpreader is a C++ library. Binary wheels are provided for common configurations on macOS and Windows.
If you are on another platform or have an uncommon configurationpipwill build the module from
source.
In order for a build from source to succeed you will needWorking C++ compiler supporting C++20 standardLinux: GCC 11.3 or abovemacOS: Xcode 14 or aboveWindows: Visual Studio 2022 or aboveOn Linux you will also need Python development support (the python-dev or python3-dev package in most Linux distributions).
No further external dependencies are required.To install the modulepipinstalleg.spreaderQuick startfromeg.spreaderimportSheet...#Create a new sheetsheet=Sheet()#Set a cell to contain plain value. Instead of "A2"#you can also say Point(x=0, y=1) or just (0, 1) or [0, 1].#Columns are x and rows y, zero-basedsheet.setValueCell("A2","Hello ")sheet.setValueCell("B3","World!")#Set a cell to contain formulasheet.setFormulaCell("A1","A2 & B3")#Read calculated formula resultval=s.getValue("A1")#val is "Hello Wolrd!" hereLimitsMaximum possible size of a sheet is currently 65536 x 2147483648 (e.g. 216x 231) cells.
You can query this value viaSheet.maxSizeproperty.
Note that currently, sheets are held entirely in memory (there is no 'offloading' of unused data to some kind of storage).
Thus, depending on how much memory you have available the actual limit on how big a sheet you will be able to create might
be lower than maximum.There is no hard limit on things like:Maximum length of cell's string valueMaximum number of function arguments (for functions that support variable number of arguments likeSUM)Maximum level of nesting in formulas
or anything else in the library. Instead, those are limited by available memory. In practice such limit is quite a bit larger than
traditional255of Excel.Cell and Area coordinatesCell coordinates in the API can be given in the usual "A1", "B2" format. Alternatively, and slightly faster, you can usePoint(x=..., y=...)objects or(x, y)tuples or[x, y]lists. In the later casexandyare zero based soPoint(x=0, y=0)and(0, 0)correspond to "A1".Similarly area coordinates can be given either as "A1:B2" or asRect(Point(x=..., y=...), Size(width=..., height=...))or as(x, y, width, height)or[x, y, width, height], whichever suits your needs more. As with individual cells, using "A1:B2" format is slightly slower.Cell valuesSpreader supports the following cell value types:None(e.g. blank cell),bool,float,strand instances of its ownErrorValueclass. All known errors are available as constants fromErrorsclass (e.g.Errors.InvalidReference) and represent the usual spreadsheet #-errors (e.g.#REF!).Numbers contained in a cell are never NaNs and never infinite. Setting a NaN or infinite value cell will result in anErrorValueinstead.Strings you set into a cell viasheet.setValueCell()call do not need to be escaped - they are always taken to be literal.
For examplesheet.setValueCell("A1", "=3")will result in a cell holding literal "=3" value as if you typed'=3in Excel
or other spreadsheets.Supported formulasSpreader supports all the operators (e.g.=,+,>,*etc.) supported by Excel.Dynamic array formulasare fully supported. Therefor there is no need forARRAYFORMULAand it isn't recognized.The following functions are currently implemented:ExpandAADDRESS, AVERAGE, AVERAGEA, AVERAGEIFCCEIL, CHOOSE, COLUMN, CONCAT, CONCATENATE, COUNT, COUNTADDATE, DATEDIF, DAY, DAYSEEDATE, EOMONTH, ERROR.TYPEFFIND, FLOORHHLOOKUP, HOURIIF, INDEX, INDIRECT, INT, ISBLANK, ISERR, ISERROR, ISEVEN, ISLOGICAL, ISNA, ISNONTEXT, ISNUMBER, ISODD, ISOWEEKNUM, ISTEXTLLEFT, LEN, LOWERMMATCH, MAX, MAXA, MID, MIN, MINA, MINUTE, MOD, MONTH, MROUNDNNOT, NOWOORRREPLACE, RIGHT, ROUND, ROUNDDOWN, ROUNDUP, ROWSSECOND, SIGN, STDEV, STDEV.P, STDEV.S, STDEVA, STDEVP, STDEVPA, SUBSTITUTE, SUM, SUMIF, SWITCHTTIME, TODAY, TRANSPOSE, TRIMUUPPERVVLOOKUPWWEEKDAY, WEEKNUMXXORYYEARRecalculationBy default sheet recalculation is automatic. You can suspend it usingsheet.suspendRecalc()and resume it again usingsheet.resumeRecalc(). Suspend calls can nest and each is "undone" by a corresponding resume. While suspended you can
manually recalculate a sheet usingsheet.recalculate().Manipulating sheet sizeSimilar to how visual spreadsheets behave sheet size (as returned bysheet.size()) is dynamic and you don't manipulate
it directly. When you set any cell to a non-null value sheet automatically expands to encompass it if it is outside
the current size. It doesn't automatically contract, however. To reduce size you can usesheet.deleteColumns()andsheet.deleteRows()calls. Those, as well assheet.insertColumns()andsheet.insertRows()can be used to
delete/insert rows and columns anywhere in the sheet. Just like in visual spreadsheets all the references in formulas
will be automatically adjusted to account for insertion or deletion.Copying and moving cellsNormal copying and moving semantics of spreadsheets are also fully supported. You can use:sheet.copyCell()to copy a single cell to a single cell or area.sheet.copyCells()(note the plural) to copy an area to another location given by its top left cornersheet.moveCell()to move a single cell to a new location (also a single cell)sheet.moveCells()to move a cell area to a new location given by its top left cornerFor all these calls the formula references are adjusted in normal spreadsheet fashion.Roadmap and missing featuresSpreader is currently in alpha - implemented features work and work well but many desirable things are missing.
The following features are currently on the roadmap:Change notifications to enable clients to react to cells changed during recalculationAbility to associate abstract formatting information with cells rows and columns. Spreader itself doesn't care
about formatting - it just needs to keep track of it for clients to act upon.Support conditional formatting formulas. Similar to above associate opaque format with boolean formulas and tell
the client which one to use.Support optional undo. It needs to be optional because it will slow things down and not all clients need it.Support more functions in formulasSupport localized formula input. Currently formula syntax must use US English syntax:.as decimal separator,,to separate
arguments. Excel allows using,and;for languages that use comma as decimal separator.Serialization/deserialization. Likely inxlsxandjson.Maybe: support manipulating very large spreadsheets by offloading parts of them to persistent
storage and not keeping everything in memory.Maybe: support doing spreadsheet math using decimals rather than doubles.