formulas: An Excel formulas interpreter in Python.¶
- release:
1.3.4
- date:
2026-03-11 18:35:00
- repository:
- pypi-repo:
- docs:
- wiki:
- download:
- donate:
- keywords:
excel, formulas, interpreter, compiler, dispatch
- developers:
Vincenzo Arcidiacono <vinci1it2000@gmail.com>
- license:
What is formulas?¶
formulas implements an interpreter for Excel formulas, which parses and compile Excel formulas expressions.
Moreover, it compiles Excel workbooks to python and executes without using the Excel COM server. Hence, Excel is not needed.
Installation¶
To install it use (with root privileges):
$ pip install formulas
Or download the last git version and use (with root privileges):
$ python setup.py install
Install extras¶
Some additional functionality is enabled installing the following extras:
excel: enables to compile Excel workbooks to python and execute using:
ExcelModel.plot: enables to plot the formula ast and the Excel model.
To install formulas and all extras, do:
$ pip install formulas[all]
Development version¶
To help with the testing and the development of formulas, you can install the development version:
$ pip install https://github.com/vinci1it2000/formulas/archive/dev.zip
CLI Quickstart¶
The formulas command-line interface works with spreadsheet models and accepts .xlsx, .ods, and .json inputs.
A typical workflow starts by calculating a workbook. You can override input values directly from the command line and request specific cells to be rendered in the output.
$ formulas calc test/test_files/excel.xlsx \
--overwrite "'[excel.xlsx]'!INPUT_A=3" \
--overwrite "'[excel.xlsx]DATA'!B3=1" \
--render "'[excel.xlsx]DATA'!C2=result" \
--output-format json
Spreadsheet models can also be converted into a portable JSON representation. This is useful when the model needs to be versioned, inspected, or executed without the original workbook.
$ formulas build test/test_files/excel.xlsx \
--output-file model.json
For validation purposes, a workbook can be tested directly from the CLI. The following command runs the tests and prints a short summary.
$ formulas test test/test_files/excel.xlsx --summary
Finally, a model can be exposed as a lightweight HTTP API, allowing other applications to execute it remotely. The serve command requires the optional web dependencies (pip install formulas[web]).
$ formulas serve test/test_files/excel.xlsx \
--host 127.0.0.1 \
--port 5000
Each command provides additional options and examples through the built-in help system:
$ formulas COMMAND --help
Table of Contents
- 1. What is formulas?
- 2. Installation
- 3. CLI Quickstart
- 4. Basic Examples
- 5. Advanced Examples
- 6. Excel Function Coverage
- 7. Next moves
- 8. Contributing to formulas
- 9. Donate
- 10. Supported by
- 11. API Reference
- 11.1. parser
- 11.2. builder
- 11.3. errors
- 11.4. tokens
- 11.4.1. function
- 11.4.2. operand
- 11.4.2.1. fast_range2parts
- 11.4.2.2. fast_range2parts_v1
- 11.4.2.3. fast_range2parts_v2
- 11.4.2.4. fast_range2parts_v3
- 11.4.2.5. fast_range2parts_v4
- 11.4.2.6. fast_range2parts_v5
- 11.4.2.7. range2parts
- 11.4.2.8. Empty
- 11.4.2.9. Error
- 11.4.2.10. Number
- 11.4.2.11. Operand
- 11.4.2.12. Range
- 11.4.2.13. String
- 11.4.2.14. XlError
- 11.4.3. operator
- 11.4.4. parenthesis
- 11.4.5. Token
- 11.5. functions
- 11.5.1. comp
- 11.5.2. date
- 11.5.2.1. args_xnetworkdays_intl
- 11.5.2.2. args_xworkday_intl
- 11.5.2.3. day_count
- 11.5.2.4. xdate
- 11.5.2.5. xdatedif
- 11.5.2.6. xdatevalue
- 11.5.2.7. xday
- 11.5.2.8. xdays
- 11.5.2.9. xdays360
- 11.5.2.10. xedate
- 11.5.2.11. xeomonth
- 11.5.2.12. xisoweeknum
- 11.5.2.13. xnetworkdays_intl
- 11.5.2.14. xnow
- 11.5.2.15. xsecond
- 11.5.2.16. xtime
- 11.5.2.17. xtimevalue
- 11.5.2.18. xtoday
- 11.5.2.19. xweekday
- 11.5.2.20. xweeknum
- 11.5.2.21. xworkday_intl
- 11.5.2.22. xyearfrac
- 11.5.2.23. year_days
- 11.5.3. eng
- 11.5.3.1. hex2dec2bin2oct
- 11.5.3.2. xbesseli
- 11.5.3.3. xbesselj
- 11.5.3.4. xbesselk
- 11.5.3.5. xbessely
- 11.5.3.6. xbitand
- 11.5.3.7. xbitlshift
- 11.5.3.8. xbitor
- 11.5.3.9. xbitrshift
- 11.5.3.10. xbitxor
- 11.5.3.11. xcomplex
- 11.5.3.12. xconvert
- 11.5.3.13. xdelta
- 11.5.3.14. xerf
- 11.5.3.15. xerf_precise
- 11.5.3.16. xgestep
- 11.5.3.17. ximargument
- 11.5.3.18. ximpower
- 11.5.4. financial
- 11.5.4.1. args_parser_disc
- 11.5.4.2. args_parser_fvschedule
- 11.5.4.3. args_parser_intrate
- 11.5.4.4. args_parser_received
- 11.5.4.5. mirr_args_parser
- 11.5.4.6. parse_basis
- 11.5.4.7. parse_date
- 11.5.4.8. total_depr
- 11.5.4.9. xaccrint
- 11.5.4.10. xaccrintm
- 11.5.4.11. xamordegrc
- 11.5.4.12. xamorlinc
- 11.5.4.13. xcoupdaybs
- 11.5.4.14. xcoupdays
- 11.5.4.15. xcoupdaysnc
- 11.5.4.16. xcoupncd
- 11.5.4.17. xcoupnum
- 11.5.4.18. xcouppcd
- 11.5.4.19. xcumipmt
- 11.5.4.20. xdate2date
- 11.5.4.21. xdb
- 11.5.4.22. xddb
- 11.5.4.23. xdisc
- 11.5.4.24. xdollarde
- 11.5.4.25. xdollarfr
- 11.5.4.26. xduration
- 11.5.4.27. xeffect
- 11.5.4.28. xfvschedule
- 11.5.4.29. xintrate
- 11.5.4.30. xirr
- 11.5.4.31. xispmt
- 11.5.4.32. xmirr
- 11.5.4.33. xnominal
- 11.5.4.34. xnper
- 11.5.4.35. xnpv
- 11.5.4.36. xoddfprice
- 11.5.4.37. xoddfyield
- 11.5.4.38. xoddlprice
- 11.5.4.39. xoddlyield
- 11.5.4.40. xpduration
- 11.5.4.41. xppmt
- 11.5.4.42. xprice
- 11.5.4.43. xpricedisc
- 11.5.4.44. xpricemat
- 11.5.4.45. xrate
- 11.5.4.46. xreceived
- 11.5.4.47. xrri
- 11.5.4.48. xsln
- 11.5.4.49. xsyd
- 11.5.4.50. xtbilleq
- 11.5.4.51. xtbillprice
- 11.5.4.52. xtbillyield
- 11.5.4.53. xvdb
- 11.5.4.54. xxirr
- 11.5.4.55. xxnpv
- 11.5.4.56. xyield
- 11.5.4.57. xyielddisc
- 11.5.4.58. xyieldmat
- 11.5.5. google
- 11.5.6. info
- 11.5.7. logic
- 11.5.8. look
- 11.5.8.1. args_parser_hlookup
- 11.5.8.2. args_parser_lookup_array
- 11.5.8.3. args_parser_match_array
- 11.5.8.4. args_parser_typed_array
- 11.5.8.5. args_parser_xlookup_array
- 11.5.8.6. args_parser_xmatch_array
- 11.5.8.7. input_parser_xlookup
- 11.5.8.8. input_parser_xmatch
- 11.5.8.9. map_multiindex_take_last_if_tuple
- 11.5.8.10. return_trimrange_func
- 11.5.8.11. return_unique_func
- 11.5.8.12. to_python
- 11.5.8.13. xaddress
- 11.5.8.14. xareas
- 11.5.8.15. xchoosecols
- 11.5.8.16. xcolumn
- 11.5.8.17. xcolumns
- 11.5.8.18. xdrop
- 11.5.8.19. xexpand
- 11.5.8.20. xfilter
- 11.5.8.21. xgroupby
- 11.5.8.22. xhstack
- 11.5.8.23. xindex
- 11.5.8.24. xlookup
- 11.5.8.25. xmatch
- 11.5.8.26. xrow
- 11.5.8.27. xsingle
- 11.5.8.28. xsort
- 11.5.8.29. xsortby
- 11.5.8.30. xtake
- 11.5.8.31. xtocol
- 11.5.8.32. xtranspose
- 11.5.8.33. xtrimrange
- 11.5.8.34. xunique
- 11.5.8.35. xvstack
- 11.5.8.36. xwrapcols
- 11.5.8.37. xxlookup
- 11.5.8.38. xxmatch
- 11.5.9. math
- 11.5.9.1. return_func
- 11.5.9.2. round_up
- 11.5.9.3. sumx2my2
- 11.5.9.4. xarabic
- 11.5.9.5. xarctan2
- 11.5.9.6. xceiling
- 11.5.9.7. xceiling_math
- 11.5.9.8. xcot
- 11.5.9.9. xdecimal
- 11.5.9.10. xeven
- 11.5.9.11. xfact
- 11.5.9.12. xfactdouble
- 11.5.9.13. xgcd
- 11.5.9.14. xlcm
- 11.5.9.15. xmdeterm
- 11.5.9.16. xmmult
- 11.5.9.17. xmod
- 11.5.9.18. xmround
- 11.5.9.19. xmultinominal
- 11.5.9.20. xmunit
- 11.5.9.21. xodd
- 11.5.9.22. xpercentof
- 11.5.9.23. xpower
- 11.5.9.24. xrandbetween
- 11.5.9.25. xroman
- 11.5.9.26. xround
- 11.5.9.27. xsrqtpi
- 11.5.9.28. xsum
- 11.5.9.29. xsumproduct
- 11.5.9.30. xtrunc
- 11.5.10. operators
- 11.5.11. stat
- 11.5.11.1. xbetadist
- 11.5.11.2. xbetainv
- 11.5.11.3. xbinomdist
- 11.5.11.4. xbinomdistrange
- 11.5.11.5. xbinominv
- 11.5.11.6. xchisqdist
- 11.5.11.7. xchisqdistrt
- 11.5.11.8. xchisqinv
- 11.5.11.9. xchisqinvrt
- 11.5.11.10. xchisqtest
- 11.5.11.11. xconfidence_norm
- 11.5.11.12. xconfidence_t
- 11.5.11.13. xcorrel
- 11.5.11.14. xcovariance_p
- 11.5.11.15. xcovariance_s
- 11.5.11.16. xexpon_dist
- 11.5.11.17. xfdist
- 11.5.11.18. xfdistrt
- 11.5.11.19. xfinv
- 11.5.11.20. xfinvrt
- 11.5.11.21. xfisher
- 11.5.11.22. xfisherinv
- 11.5.11.23. xforecast
- 11.5.11.24. xforecast_ets
- 11.5.11.25. xforecast_ets_confint
- 11.5.11.26. xforecast_ets_seasonality
- 11.5.11.27. xforecast_ets_stat
- 11.5.11.28. xfrequency
- 11.5.11.29. xftest
- 11.5.11.30. xfunc
- 11.5.11.31. xgamma
- 11.5.11.32. xgamma_dist
- 11.5.11.33. xgamma_inv
- 11.5.11.34. xgammaln
- 11.5.11.35. xgauss
- 11.5.11.36. xgrowth
- 11.5.11.37. xhypergeom_dist
- 11.5.11.38. xintercept
- 11.5.11.39. xlinest
- 11.5.11.40. xlogest
- 11.5.11.41. xlognormdist
- 11.5.11.42. xlognorminv
- 11.5.11.43. xnegbinomdist
- 11.5.11.44. xnormdist
- 11.5.11.45. xnorminv
- 11.5.11.46. xpearson
- 11.5.11.47. xpercentile
- 11.5.11.48. xpercentrank
- 11.5.11.49. xpermut
- 11.5.11.50. xpermutationa
- 11.5.11.51. xphi
- 11.5.11.52. xpoisson_dist
- 11.5.11.53. xprob
- 11.5.11.54. xquartile
- 11.5.11.55. xrank
- 11.5.11.56. xrsq
- 11.5.11.57. xslope
- 11.5.11.58. xsort
- 11.5.11.59. xstandardize
- 11.5.11.60. xstdev
- 11.5.11.61. xsteyx
- 11.5.11.62. xt_dist
- 11.5.11.63. xt_dist2t
- 11.5.11.64. xt_distrt
- 11.5.11.65. xt_inv
- 11.5.11.66. xt_inv2t
- 11.5.11.67. xt_test
- 11.5.11.68. xtrend
- 11.5.11.69. xtrimmean
- 11.5.11.70. xweibulldist
- 11.5.11.71. xz_test
- 11.5.12. text
- 11.5.12.1. xarraytotext
- 11.5.12.2. xasc
- 11.5.12.3. xbahttext
- 11.5.12.4. xchar
- 11.5.12.5. xclean
- 11.5.12.6. xcode
- 11.5.12.7. xconcat
- 11.5.12.8. xexact
- 11.5.12.9. xfind
- 11.5.12.10. xfixed
- 11.5.12.11. xleft
- 11.5.12.12. xmid
- 11.5.12.13. xnumbervalue
- 11.5.12.14. xregexextract
- 11.5.12.15. xregexreplace
- 11.5.12.16. xregextest
- 11.5.12.17. xreplace
- 11.5.12.18. xrept
- 11.5.12.19. xright
- 11.5.12.20. xsearch
- 11.5.12.21. xsubstitute
- 11.5.12.22. xt
- 11.5.12.23. xtext
- 11.5.12.24. xtextafterbefore
- 11.5.12.25. xtextjoin
- 11.5.12.26. xtextsplit
- 11.5.12.27. xunichar
- 11.5.12.28. xunicode
- 11.5.12.29. xvalue
- 11.5.12.30. xvaluetotext
- 11.5.13. args2list
- 11.5.14. args2vals
- 11.5.15. clean_values
- 11.5.16. convert2float
- 11.5.17. convert_nan
- 11.5.18. convert_noshp
- 11.5.19. flatten
- 11.5.20. get_error
- 11.5.21. get_functions
- 11.5.22. get_shape
- 11.5.23. is_complex
- 11.5.24. is_not_empty
- 11.5.25. is_number
- 11.5.26. not_implemented
- 11.5.27. parse_ranges
- 11.5.28. raise_errors
- 11.5.29. replace_empty
- 11.5.30. return_2d_func
- 11.5.31. str2complex
- 11.5.32. text2num
- 11.5.33. to_number
- 11.5.34. wrap_func
- 11.5.35. wrap_impure_func
- 11.5.36. wrap_ranges_func
- 11.5.37. wrap_ufunc
- 11.5.38. xfilter
- 11.5.39. xfilters
- 11.5.40. Array
Array- 11.5.40.1. __init__
- 11.5.40.2. all
- 11.5.40.3. any
- 11.5.40.4. argmax
- 11.5.40.5. argmin
- 11.5.40.6. argpartition
- 11.5.40.7. argsort
- 11.5.40.8. astype
- 11.5.40.9. byteswap
- 11.5.40.10. choose
- 11.5.40.11. clip
- 11.5.40.12. collapse
- 11.5.40.13. compress
- 11.5.40.14. conj
- 11.5.40.15. conjugate
- 11.5.40.16. copy
- 11.5.40.17. cumprod
- 11.5.40.18. cumsum
- 11.5.40.19. diagonal
- 11.5.40.20. dot
- 11.5.40.21. dump
- 11.5.40.22. dumps
- 11.5.40.23. fill
- 11.5.40.24. flatten
- 11.5.40.25. getfield
- 11.5.40.26. item
- 11.5.40.27. max
- 11.5.40.28. mean
- 11.5.40.29. min
- 11.5.40.30. nonzero
- 11.5.40.31. partition
- 11.5.40.32. prod
- 11.5.40.33. put
- 11.5.40.34. ravel
- 11.5.40.35. repeat
- 11.5.40.36. reshape
- 11.5.40.37. resize
- 11.5.40.38. round
- 11.5.40.39. searchsorted
- 11.5.40.40. setfield
- 11.5.40.41. setflags
- 11.5.40.42. sort
- 11.5.40.43. squeeze
- 11.5.40.44. std
- 11.5.40.45. sum
- 11.5.40.46. swapaxes
- 11.5.40.47. take
- 11.5.40.48. to_device
- 11.5.40.49. tobytes
- 11.5.40.50. tofile
- 11.5.40.51. tolist
- 11.5.40.52. trace
- 11.5.40.53. transpose
- 11.5.40.54. var
- 11.5.40.55. view
- 11.5.40.56. T
- 11.5.40.57. base
- 11.5.40.58. ctypes
- 11.5.40.59. data
- 11.5.40.60. device
- 11.5.40.61. dtype
- 11.5.40.62. flags
- 11.5.40.63. flat
- 11.5.40.64. imag
- 11.5.40.65. itemsize
- 11.5.40.66. mT
- 11.5.40.67. nbytes
- 11.5.40.68. ndim
- 11.5.40.69. real
- 11.5.40.70. shape
- 11.5.40.71. size
- 11.5.40.72. strides
- 11.6. ranges
- 11.7. cell
- 11.8. excel
- 11.8.1. cycle
- 11.8.2. xlreader
- 11.8.3. escape_char
- 11.8.4. ExcelModel
ExcelModel- 11.8.4.1. __init__
- 11.8.4.2. add_anchor
- 11.8.4.3. add_book
- 11.8.4.4. add_cell
- 11.8.4.5. add_references
- 11.8.4.6. add_sheet
- 11.8.4.7. anchors
- 11.8.4.8. assemble
- 11.8.4.9. calculate
- 11.8.4.10. compare
- 11.8.4.11. compile
- 11.8.4.12. compile_cell
- 11.8.4.13. complete
- 11.8.4.14. external_links
- 11.8.4.15. finish
- 11.8.4.16. formula_ranges
- 11.8.4.17. formula_references
- 11.8.4.18. from_dict
- 11.8.4.19. from_ranges
- 11.8.4.20. inverse_references
- 11.8.4.21. load
- 11.8.4.22. loads
- 11.8.4.23. push
- 11.8.4.24. pushes
- 11.8.4.25. solve_circular
- 11.8.4.26. to_dict
- 11.8.4.27. write
- 11.8.4.28. references
- 11.8.5. XlCircular
XlCircular- 11.8.5.1. __init__
- 11.8.5.2. capitalize
- 11.8.5.3. casefold
- 11.8.5.4. center
- 11.8.5.5. count
- 11.8.5.6. encode
- 11.8.5.7. endswith
- 11.8.5.8. expandtabs
- 11.8.5.9. find
- 11.8.5.10. format
- 11.8.5.11. format_map
- 11.8.5.12. index
- 11.8.5.13. isalnum
- 11.8.5.14. isalpha
- 11.8.5.15. isascii
- 11.8.5.16. isdecimal
- 11.8.5.17. isdigit
- 11.8.5.18. isidentifier
- 11.8.5.19. islower
- 11.8.5.20. isnumeric
- 11.8.5.21. isprintable
- 11.8.5.22. isspace
- 11.8.5.23. istitle
- 11.8.5.24. isupper
- 11.8.5.25. join
- 11.8.5.26. ljust
- 11.8.5.27. lower
- 11.8.5.28. lstrip
- 11.8.5.29. maketrans
- 11.8.5.30. partition
- 11.8.5.31. removeprefix
- 11.8.5.32. removesuffix
- 11.8.5.33. replace
- 11.8.5.34. rfind
- 11.8.5.35. rindex
- 11.8.5.36. rjust
- 11.8.5.37. rpartition
- 11.8.5.38. rsplit
- 11.8.5.39. rstrip
- 11.8.5.40. split
- 11.8.5.41. splitlines
- 11.8.5.42. startswith
- 11.8.5.43. strip
- 11.8.5.44. swapcase
- 11.8.5.45. title
- 11.8.5.46. translate
- 11.8.5.47. upper
- 11.8.5.48. zfill
- 12. Changelog
- 12.1. v1.3.4 (2026-03-11)
- 12.2. v1.3.3 (2025-11-04)
- 12.3. v1.3.2 (2025-10-21)
- 12.4. v1.3.1 (2025-09-15)
- 12.5. v1.3.0 (2025-08-20)
- 12.6. v1.2.11 (2025-07-28)
- 12.7. v1.2.10 (2025-05-21)
- 12.8. v1.2.9 (2025-04-05)
- 12.9. v1.2.8 (2024-07-16)
- 12.10. v1.2.7 (2023-11-14)
- 12.11. v1.2.6 (2022-12-13)
- 12.12. v1.2.5 (2022-11-07)
- 12.13. v1.2.4 (2022-07-02)
- 12.14. v1.2.3 (2022-05-10)
- 12.15. v1.2.2 (2022-01-22)
- 12.16. v1.2.1 (2022-01-21)
- 12.17. v1.2.0 (2021-12-23)
- 12.18. v1.1.1 (2021-10-13)
- 12.19. v1.1.0 (2021-02-16)
- 12.20. v1.0.0 (2020-03-12)
- 12.21. v0.4.0 (2019-08-31)
- 12.22. v0.3.0 (2019-04-24)
- 12.23. v0.2.0 (2018-12-11)
- 12.24. v0.1.4 (2018-10-19)
- 12.25. v0.1.3 (2018-10-09)
- 12.26. v0.1.2 (2018-09-12)
- 12.27. v0.1.1 (2018-09-11)
- 12.28. v0.1.0 (2018-07-20)
- 12.29. v0.0.10 (2018-06-05)
- 12.30. v0.0.9 (2018-05-28)
- 12.31. v0.0.8 (2018-05-23)
- 12.32. v0.0.7 (2017-07-20)
- 12.33. v0.0.6 (2017-05-31)
- 12.34. v0.0.5 (2017-05-04)
- 12.35. v0.0.4 (2017-02-10)
- 12.36. v0.0.3 (2017-02-09)
- 12.37. v0.0.2 (2017-02-08)