calculator_functions

shortfx.fxNumeric.calculator_functions

Safe scientific expression evaluator.

Evaluates mathematical expressions from string input using AST-based parsing. NEVER uses eval() — instead, it parses the expression into an Abstract Syntax Tree and walks it, only allowing whitelisted mathematical operations and functions.

Key Features

• Safe evaluation without eval() or exec()
• Supports arithmetic operators: +, -, *, /, //, %, **
• Supports unary operators: +, -
• Built-in scientific functions: sin, cos, tan, log, sqrt, etc.
• Built-in constants: pi, e, tau, phi, inf
• Parenthesized sub-expressions
• Clear error messages for invalid input

Example

from shortfx.fxNumeric.calculator_functions import evaluate_expression evaluate_expression("sin(pi/4) + sqrt(2)") 3.1213203435596424 evaluate_expression("log(100, 10)") 2.0

Attributes

Functions

evaluate_expression(expression: str) -> Union[int, float]

Safely evaluates a mathematical expression from a string.

Description

Parses and evaluates a mathematical expression using AST-based parsing. Supports arithmetic operators, scientific functions, and mathematical constants. Does NOT use eval() — only whitelisted operations are allowed.

Parameters:

Name	Type	Description	Default
expression	str	A mathematical expression string. Examples: "sin(pi/4) + sqrt(2)", "log(100, 10)", "2**10 + 1"	required

Returns:

Type	Description
Union[int, float]	Union[int, float]: The numeric result of the expression.

Raises:

Type	Description
TypeError	If expression is not a string.
ValueError	If the expression is empty, too long, contains syntax errors, or uses unsupported operations.

Usage Example

from shortfx.fxNumeric.calculator_functions import evaluate_expression evaluate_expression("2 + 3 * 4") 14 evaluate_expression("sin(pi/2)") 1.0 evaluate_expression("sqrt(2) ** 2") 2.0000000000000004 evaluate_expression("log(1000, 10)") 2.9999999999999996 evaluate_expression("factorial(5)") 120 evaluate_expression("comb(10, 3)") 120

Cost: O(n) where n is the expression length.

Source code in shortfx/fxNumeric/calculator_functions.py

def evaluate_expression(expression: str) -> Union[int, float]:
    """Safely evaluates a mathematical expression from a string.

    Description:
        Parses and evaluates a mathematical expression using AST-based
        parsing. Supports arithmetic operators, scientific functions,
        and mathematical constants. Does NOT use ``eval()`` — only
        whitelisted operations are allowed.

    Args:
        expression (str): A mathematical expression string.
            Examples: "sin(pi/4) + sqrt(2)", "log(100, 10)", "2**10 + 1"

    Returns:
        Union[int, float]: The numeric result of the expression.

    Raises:
        TypeError: If expression is not a string.
        ValueError: If the expression is empty, too long, contains syntax
            errors, or uses unsupported operations.

    Usage Example:
        >>> from shortfx.fxNumeric.calculator_functions import evaluate_expression
        >>> evaluate_expression("2 + 3 * 4")
        14
        >>> evaluate_expression("sin(pi/2)")
        1.0
        >>> evaluate_expression("sqrt(2) ** 2")
        2.0000000000000004
        >>> evaluate_expression("log(1000, 10)")
        2.9999999999999996
        >>> evaluate_expression("factorial(5)")
        120
        >>> evaluate_expression("comb(10, 3)")
        120

    Cost: O(n) where n is the expression length.
    """
    if not isinstance(expression, str):
        raise TypeError("Expression must be a string.")

    expression = expression.strip()

    if not expression:
        raise ValueError("Expression cannot be empty.")

    if len(expression) > _MAX_EXPRESSION_LENGTH:
        raise ValueError(
            f"Expression too long ({len(expression)} chars). "
            f"Maximum allowed: {_MAX_EXPRESSION_LENGTH}."
        )

    try:
        tree = ast.parse(expression, mode="eval")
    except SyntaxError as exc:
        raise ValueError(f"Invalid expression syntax: {exc.msg}") from exc

    evaluator = _ExpressionEvaluator()
    return evaluator.visit(tree)

list_available_constants() -> list[str]

Lists all constants available in the expression evaluator.

Description

Returns the names of all mathematical constants that can be used inside evaluate_expression().

Returns:

Type	Description
list[str]	list[str]: Sorted list of available constant names.

Usage Example

from shortfx.fxNumeric.calculator_functions import list_available_constants "pi" in list_available_constants() True

Cost: O(n log n)

Source code in shortfx/fxNumeric/calculator_functions.py

def list_available_constants() -> list[str]:
    """Lists all constants available in the expression evaluator.

    Description:
        Returns the names of all mathematical constants that can be
        used inside ``evaluate_expression()``.

    Returns:
        list[str]: Sorted list of available constant names.

    Usage Example:
        >>> from shortfx.fxNumeric.calculator_functions import list_available_constants
        >>> "pi" in list_available_constants()
        True

    Cost: O(n log n)
    """
    return sorted(_CONSTANTS.keys())

list_available_functions() -> list[str]

Lists all functions available in the expression evaluator.

Description

Returns the names of all mathematical functions that can be used inside evaluate_expression().

Returns:

Type	Description
list[str]	list[str]: Sorted list of available function names.

Usage Example

from shortfx.fxNumeric.calculator_functions import list_available_functions "sin" in list_available_functions() True

Cost: O(n log n)

Source code in shortfx/fxNumeric/calculator_functions.py

def list_available_functions() -> list[str]:
    """Lists all functions available in the expression evaluator.

    Description:
        Returns the names of all mathematical functions that can be
        used inside ``evaluate_expression()``.

    Returns:
        list[str]: Sorted list of available function names.

    Usage Example:
        >>> from shortfx.fxNumeric.calculator_functions import list_available_functions
        >>> "sin" in list_available_functions()
        True

    Cost: O(n log n)
    """
    return sorted(_FUNCTIONS.keys())