{"id":6648,"library":"formulas","title":"Formulas","description":"Formulas is a Python library that implements an interpreter for Excel formulas, parsing and compiling Excel formula expressions. It can also compile Excel workbooks to Python code and execute them without needing a Microsoft Excel COM server. The current version is 1.3.4, released on March 11, 2026, with an active, though irregular, release cadence.","status":"active","version":"1.3.4","language":"en","source_language":"en","source_url":"https://github.com/vinci1it2000/formulas","tags":["excel","formulas","interpreter","compiler","workbook","calculation","parsing","spreadsheet"],"install":[{"cmd":"pip install formulas","lang":"bash","label":"Core library"},{"cmd":"pip install formulas[all]","lang":"bash","label":"With all optional features (Excel model, plotting, web server)"}],"dependencies":[{"reason":"Enables Excel workbook compilation and execution via `formulas[excel]` extra.","package":"openpyxl","optional":true},{"reason":"Enables plotting formula Abstract Syntax Trees (ASTs) and Excel models via `formulas[plot]` extra.","package":"matplotlib","optional":true},{"reason":"Enables the HTTP API server (`formulas serve`) via `formulas[web]` extra.","package":"Flask","optional":true}],"imports":[{"symbol":"Parser","correct":"from formulas import Parser"},{"note":"ExcelModel is directly available from the top-level 'formulas' package after installation of the 'excel' extra.","wrong":"from formulas.excel import ExcelModel","symbol":"ExcelModel","correct":"from formulas import ExcelModel"},{"symbol":"get_functions","correct":"import formulas\nfunctions = formulas.get_functions()"}],"quickstart":{"code":"import formulas\n\n# 1. Parse and compile a simple Excel formula\nparser = formulas.Parser()\nast_node = parser.ast(\"=SUM(10, 20)\")[1] # [1] gets the formula node\ncompiled_func = ast_node.compile()\nresult_sum = compiled_func() # Expected: 30\nprint(f\"Result of '=SUM(10, 20)': {result_sum}\")\n\n# 2. Add a custom function\nFUNCTIONS = formulas.get_functions()\nFUNCTIONS['MYCUSTOMADD'] = lambda x, y: x + y + 100\n\ncustom_func_node = parser.ast(\"=MYCUSTOMADD(5, 7)\")[1]\ncompiled_custom_func = custom_func_node.compile()\nresult_custom = compiled_custom_func() # Expected: 5 + 7 + 100 = 112\nprint(f\"Result of '=MYCUSTOMADD(5, 7)': {result_custom}\")","lang":"python","description":"This quickstart demonstrates how to parse and compile a basic Excel formula using the `Parser` class and how to extend the interpreter with custom Python functions. It showcases two core capabilities of the library: formula evaluation and customization."},"warnings":[{"fix":"Ensure installation with `pip install formulas[excel]` or `pip install formulas[all]` if `ExcelModel` is used.","message":"To work with Excel workbooks (e.g., loading, calculating, writing Excel files via `ExcelModel`), you must install the `formulas` library with the `excel` extra. Use `pip install formulas[excel]` or `pip install formulas[all]`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Thoroughly test existing complex formulas after upgrading the `formulas` library to ensure consistent behavior. Refer to the project's changelog for specific parser adjustments.","message":"The library's interpretation of complex Excel formulas, especially those with empty parameters or nuanced operator precedence, has evolved. Formulas that rely on edge-case behaviors might produce different results across minor versions due to internal parser corrections.","severity":"gotcha","affected_versions":"All versions, particularly when upgrading from older 1.x releases."},{"fix":"Always retrieve the global functions dictionary using `formulas.get_functions()` and assign your custom function to a key (its Excel name) within that dictionary before parsing formulas that use it.","message":"When defining custom functions, they must be explicitly registered with the `formulas.get_functions()` dictionary. Forgetting this step will lead to formula parsing errors when the custom function is referenced.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}