Qickstart

Creating a Formula

The usage of the package is quite simple. For creating a formula, you simply import the Formula class and call its constructor with the formula as the argument:

from formparse import Formula

formula = Formula('3*x**2')

Since the package uses ast for building the syntax tree the syntax and operators are those used in Python. Concretely, the currently available operators are +, -, *, / and **.

Additionally, there the functions min(), max() and abs() are available. They can be used the same way as in Python.

Evaluating a Formula

For evaluating the formula you simply call the .eval() method, passing it a dictionary with the variables you want to provide the formula with.

result = formula.eval({'x': 2})

Validation:

When calling the contructor, a validator is automatically called. It ensures that the formula is parseable, is not longer than the length constraint and all the operators are supported. If there is an error, a FormulaSyntaxError is raised. You can manually validate a formula using the .validate() class method.

valid, problem = Formula.validate('a^2')
if not valid:
    print(problem) # outputs 'Unsopported operator'

The function returns if the formula is valid and, if it is not, the reason why it is invalid.

Complexity Check:

Before acutally evaluating a formula with the eval() method, a complexity check is run automatically. This is intended to prevent user from crashing the program complex calculations. The check is based on the power of tens of the operands. If the maximum possible result is bigger than 10^18, a FormulaComplexityError is thrown. For examle:

Formula('65**500').eval() # throws `FormulaComplexityError` error

Limitations

Currently, there is not support for currying/partially applying the formula. If you don’t pass in all arguments, a formula.FormulaRuntimeError will be thrown.

Also, currently there is no support for positinal arguments. If you pass anything different than a dictionary as argument, a formula.FormulaRuntimeError will be thrown.

It is possible to evaluate a formula that does not contain any variables. Also, passing additional variables in the dictionary does not cause an error. Therefore, you can use Formula also for constant values if needed.