Formulas

A Formula is a typed expression in a small modelling language modelled loosely on Microsoft Excel. Formulas are used by CalculatedField and Calculation to compute values from other fields and named values.

Build expressions with Python operators or with the helper functions in daitum_model.formulas:

import daitum_model.formulas as formulas
from daitum_model.formula import CONST

total = products["price"] * products["quantity"]            # Formula
is_expensive = products["price"] > CONST(100)               # Formula
summary = formulas.SUM(products["price"])                   # Formula

The Formula Class

class Formula[source]

Bases: Buildable, Operand, ABC

Abstract base for every structured formula expression.

A formula is its structured expression tree: Constant, the operator nodes (BinaryOperator/UnaryOperator/MemberAccess/ColumnAccess), and every per-function node subclass this base. data_type and formula_string are projections of the tree (how it type-checks and how it is written to JSON), derived from to_data_type() / to_string() rather than stored.

Subclasses implement to_string / to_data_type (from Operand) and children().

children()[source]

The immediate operand children of this formula node.

Return type:

Sequence[Operand]

dependencies()[source]

The reference leaves (Field / Calculation / Parameter / Table) this formula transitively uses.

The returned set is keyed by object identity (Operand defines no value __eq__ / __hash__), so each referenced object appears once. Reference leaves are operands that are not themselves Formula nodes; a child that is a structured formula recurses.

Return type:

set[Operand]

is_equivalent(other)[source]

Whether other is a formula equivalent to this one.

Two formulas are equivalent when they render to the same platform expression and infer the same data type. Because rendering is deterministic (the same node tree always produces the same string, brackets and spacing included), this reliably distinguishes structurally different formulas — e.g. (x + y) - z from x + (y - z) — and is exactly the check the parser round-trip needs (parse(f.to_string()) ≡ f).

This is a dedicated method rather than an __eq__ override, which would perturb the identity-keyed dependencies() set and the equal_to / not_equal_to operators.

Return type:

bool

property data_type: BaseDataType

The formula’s return data type (a projection of the tree).

property formula_string: str

The rendered platform expression string (a projection of the tree).

build()[source]

Serialise to {"dataType", "formulaString"}.

A custom override: the node’s real state lives in _-prefixed attributes that the default Buildable walk skips, so this emits the two projections explicitly. The data type serialises as its enum value (DataType) or its nested build (ObjectDataType / MapDataType) — matching the legacy output.

Return type:

dict[str, Any]

Built-in Formula Functions

The daitum_model.formulas submodule provides every built-in formula function.

Formula Reference: