Expressions
item and fitem build scalar placeholder expressions for flows. col(),
lit(), when(), and coalesce() build record expressions for Rows and for
record-capable Flow operations.
from fpstreams import col, flow, item
numbers = flow(range(5)).filter(item % 2 == 0).map(item * 10)
active = flow([{"status": "active"}]).filter(col("status") == "active").select("status")
Scalar filter() and map() calls keep an ordinary Flow. A nonconflicting
record method such as select() enters Rows automatically; call .rows() first
when you need a conflicting relational method such as Rows where() with field
equalities.
Building row expressions
| Call | Meaning |
|---|---|
col(selector) |
Read a field, index, attribute, nested path, or callable selector |
lit(value) |
Return the same value for every row |
when(condition, then, otherwise) |
Choose a value from a condition |
coalesce(*values) |
Return the first value that is not None |
Row-expression methods such as cast(), isin(), fill_null(), lower(), and
contains() return new expressions; they do not read rows immediately.
Scalar expressions
fitem accepts exact int and float constants and converts them to a float
when the expression is built. Booleans, numeric subclasses, and objects with
custom conversion methods are rejected. Use a callable when you need those
objects' Python behavior.
The working tree fixes a signed-zero error: FExpr.constant(-0.0) keeps its
negative sign, including after a positive-zero expression has populated the cache.
It also fixes cache collisions between numerically equal constants of different
types. For example, FExpr("const", value=9007199254740993) keeps that integer
result even if a float expression ran first. Directly constructed expressions
with nonstandard operand types use Python in auto mode; forcing native
raises NativeUnsupportedError. The accepted inputs to item, fitem, and
their constant factories are unchanged. These fixes are not in 2.1.0.
fpstreams.Expr
dataclass
Represent an integer expression for Python evaluation and native i64 execution.
operation, left, right, and value form the tree; kind records whether the result is integer or Boolean for planning. Postfix instructions and the Python evaluator are populated lazily in per-instance cache fields.
constant
staticmethod
Return a constant integer expression after exact-type validation.
bool and all non-int objects raise TypeError even though bool is an int subclass.
native_instructions
Return and cache this tree's postfix instructions for Python or native execution.
Each pair contains a numeric opcode and an integer operand. Only const opcodes consume the operand; other instructions store zero as a placeholder.
Row expressions
fpstreams.RowExpr
dataclass
Represent a labeled row expression as both a callable and an inspectable IR graph.
Direct construction wraps the supplied evaluator as an opaque PythonUDF. Expressions created by this module retain their specific nodes and compile lazily on first evaluation.
inspect
Analyze field use and execution properties without evaluating the expression.
map
Apply a Python callable to this expression's value during row evaluation.
The callable is stored as a PythonUDF, so structural inspection marks the resulting graph opaque and cannot infer its field dependencies.
cast
Call target with this expression's value during row evaluation.
target may be a type or any one-argument callable; its normal return value and exceptions are preserved.
isin
Materialize values as a tuple immediately, then test membership during row evaluation.
Consuming the iterable at construction makes later evaluations reuse the same choices.
is_not_null
Build a non-null test by logically inverting this expression's IsNull node.
fill_null
Return this expression's value unless it is None, then evaluate the replacement.
The replacement is coerced to a row expression at construction and remains unevaluated for rows whose primary value is non-null.
coalesce
Delegate to coalesce with this expression as the first candidate.