simpleeval

By default, SimpleEval supports compound types (dict, tuple, list, set) if they are passed in via names.

To allow the creation of these types within expressions (e.g., using list comprehensions like [x + 1 for x in [1,2,3]]), use the EvalWithCompoundTypes class instead of SimpleEval. This class includes a safety mechanism MAX_COMPREHENSION_LENGTH to prevent resource exhaustion from deeply nested or overly large comprehensions.

from simpleeval import EvalWithCompoundTypes

s = EvalWithCompoundTypes()
s.eval("[x + 1 for x in [1, 2, 3]]")

The simple_eval function provides a quick way to evaluate mathematical or logical expressions safely. It supports standard arithmetic, complex nested expressions, and custom functions.

from simpleeval import simple_eval

# Simple arithmetic
result = simple_eval("21 + 21") # returns 42

# Complex expressions
result = simple_eval("21 + 19 / 7 + (8 % 3) ** 9") # returns 535.714285714

# Using custom functions
result = simple_eval("square(11)", functions={"square": lambda x: x*x}) # returns 121

By default, simpleeval enables a 'sweetener' that allows accessing dictionary keys using dot notation (e.g., foo.bar where foo is {'bar': 42}).

To disable this behavior, set the module global ATTR_INDEX_FALLBACK = False or set it on a specific instance: evaller.ATTR_INDEX_FALLBACK = False.

# Using the dot notation sweetener
simple_eval("foo.bar", names={"foo": {"bar": 42}})
# Returns 42

You can use Python-style ternary conditional expressions (x if condition else y) within your evaluated strings. These can be nested.

from simpleeval import simple_eval

# Basic if expression
result = simple_eval("'equal' if x == y else 'not equal'", names={"x": 1, "y": 2})

# Nested if expressions
result = simple_eval("'a' if 1 == 2 else 'b' if 2 == 3 else 'c'") # returns 'c'

For high-frequency evaluations, instantiate a SimpleEval object instead of calling the simple_eval function repeatedly. This allows you to reuse configuration and, more importantly, parse an expression once and evaluate it multiple times with different names to improve performance.

To optimize performance, use s.parse(expression) to get a parsed tree, then pass that tree to s.eval(expression, previously_parsed=parsed) in a loop while updating s.names.

# Set up & Cache the parse tree:
expression = "foo + bar"
s = SimpleEval()
parsed = s.parse(expression)

# evaluate the expression multiple times:
for names in [{"foo": 1, "bar": 10}, {"foo": 100, "bar": 42}]:
    s.names = names
    print(s.eval(expression, previously_parsed=parsed))

You can configure a SimpleEval instance either during initialization or by modifying its attributes after creation. Common attributes to modify include functions and names.

Note: Because names and functions are dictionaries, you can even define functions within the expression that modify the evaluator's own state (e.g., a set function).

# Configuration during creation
s = SimpleEval(functions={"boo": boo})

# Configuration after creation
s.names['fortytwo'] = 42

# Advanced: modifying state via an expression
s = SimpleEval()
def set_val(name, value):
    s.names[name.value] = value.value
    return value.value

s.functions = {'set': set_val}
s.eval("set('age', 111)")

By default, simpleeval supports standard Python operators (arithmetic, comparison, bitwise, and in). You can override or add new operators by using the SimpleEval class and modifying its operators dictionary, which maps AST nodes to callable functions.

For example, to change the ^ operator from bitwise XOR to a power function:

import ast
import operator
from simpleeval import SimpleEval, safe_power

s = SimpleEval()
s.operators[ast.BitXor] = safe_power
result = s.eval("3 ^ 2") # returns 9

Security Note: The ** (power) operator is limited by default to prevent DOS attacks. You can adjust this limit by modifying the simpleeval.MAX_POWER module-level value. To remove all limits, you can map ast.Pow to operator.pow.

Direct module access is disallowed by default. To safely expose a module (like os.path or numpy), wrap it in ModuleWrapper. This enforces restrictions on private attributes (starting with _) and methods listed in DISALLOW_METHODS even if you use an allowlist.

from simpleeval import SimpleEval, ModuleWrapper
import os.path

# Basic module exposure
s = SimpleEval(names={'path': ModuleWrapper(os.path)})
s.eval("path.exists('/etc/passwd')")

# Restricted module exposure
s = SimpleEval(names={
    'path': ModuleWrapper(os.path, allowed_attrs={'exists', 'join'})
})
s.eval("path.exists('/etc/passwd')") # Works
s.eval("path.dirname('/etc/passwd')") # Raises FeatureNotAvailable

You can extend SimpleEval by overriding internal methods. For example, to create an evaluator that explicitly forbids method calls (attribute access on functions), override _eval_call and check the AST node type.

import ast
import simpleeval

class EvalNoMethods(simpleeval.SimpleEval):
    def _eval_call(self, node):
        if isinstance(node.func, ast.Attribute):
            raise simpleeval.FeatureNotAvailable("No methods please, we're British")
        return super(EvalNoMethods, self)._eval_call(node)