{"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":"python","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,"search_vec":"'1.3.4':43 '11':47 '2026':48 'activ':51 'also':22 'cadenc':55 'calcul':61 'code':28 'com':37 'compil':16,23,59 'current':40 'excel':12,17,24,36,56 'execut':30 'express':19 'formula':1,2,13,18,57 'implement':8 'interpret':10,58 'irregular':53 'librari':6 'march':46 'microsoft':35 'need':33 'pars':14,62 'python':5,27 'releas':44,54 'server':38 'spreadsheet':63 'though':52 'version':41 'without':32 'workbook':25,60","created_at":"2026-04-15T18:36:56.791266+00:00","updated_at":"2026-04-16T15:10:49.956981+00:00","problems":[{"fix":"Install the library using pip: `pip install formulas`","cause":"The 'formulas' library is not installed in your Python environment or there is a typo in the import statement.","error":"ModuleNotFoundError: No module named 'formulas'"},{"fix":"Review the Excel file for formula validity, ensuring all cell, range, and sheet references are correct and exist. For example, if 'Sheet 1'!#REF! is the issue, verify 'Sheet 1' and the referenced cell/range within it are valid.","cause":"The Excel formula being processed by the 'formulas' library contains an invalid reference, similar to Excel's #REF! error, often caused by deleted cells or incorrect sheet/range names in the formula itself.","error":"FormulaError: ('Not a valid formula:\\n%s', \"='Sheet 1'!#REF!\")"},{"fix":"Ensure the Excel workbook is correctly loaded and parsed using `formulas.ExcelModel().loads(filename).finish()` before calling `calculate()`.","cause":"This error typically occurs when attempting to call the 'calculate()' method on an 'ExcelModel' object before the Excel workbook has been successfully loaded and 'finished' (i.e., parsed and compiled).","error":"AttributeError: 'ExcelModel' object has no attribute 'calculate'"},{"fix":"Review the Excel formula and the data types of its inputs. Ensure that all operands involved in arithmetic or other type-sensitive operations are of compatible types. If necessary, adjust the Excel formula or preprocess the input data to ensure type consistency.","cause":"This generic Python error often arises when the 'formulas' library processes an Excel formula that implicitly or explicitly attempts an operation (like addition) between incompatible data types (e.g., a number and a text string) during Python's evaluation.","error":"TypeError: unsupported operand type(s) for +: 'int' and 'str'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.3.4","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/vinci1it2000/formulas","docs":"http://formulas.readthedocs.io","changelog":null,"pypi":"https://pypi.org/project/formulas/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}