kd.expr API

Expr utilities.

kd.expr.as_expr(arg: Any) -> Expr

Converts Python values into Exprs.

kd.expr.get_input_names(expr: Expr, container: InputContainer = InputContainer('I')) -> list[str]

Returns names of `container` inputs used in `expr`.

kd.expr.get_name(expr: Expr) -> str | None

Returns the name of the given Expr, or None if it does not have one.

kd.expr.is_input(expr: Expr) -> bool

Returns True if `expr` is an input `I`.

kd.expr.is_literal(expr: Expr) -> bool

Returns True if `expr` is a Koda Literal.

kd.expr.is_packed_expr(ds: Any) -> DataSlice

Returns kd.present if the argument is a DataItem containing an Expr.

kd.expr.is_variable(expr: Expr) -> bool

Returns True if `expr` is a variable `V`.

kd.expr.literal(value)

Constructs an expr with a LiteralOperator wrapping the provided QValue.

kd.expr.pack_expr(expr: Expr) -> DataSlice

Packs the given Expr into a DataItem.

kd.expr.sub(expr: Expr, *subs: Any | tuple[Expr, Any]) -> Expr

Returns `expr` with provided expressions replaced.

Example usage:
  kd.sub(expr, (from_1, to_1), (from_2, to_2), ...)

For the special case of a single substitution, you can also do:
  kd.sub(expr, from, to)

It does the substitution by traversing 'expr' post-order and comparing
fingerprints of sub-Exprs in the original expression and those in in 'subs'.
For example,

  kd.sub(I.x + I.y, (I.x, I.z), (I.x + I.y, I.k)) -> I.k

  kd.sub(I.x + I.y, (I.x, I.y), (I.y + I.y, I.z)) -> I.y + I.y

It does not do deep transformation recursively. For example,

  kd.sub(I.x + I.y, (I.x, I.z), (I.y, I.x)) -> I.z + I.x

Args:
  expr: Expr which substitutions are applied to
  *subs: Either zero or more (sub_from, sub_to) tuples, or exactly two
    arguments from and to. The keys should be expressions, and the values
    should be possible to convert to expressions using kd.as_expr.

Returns:
  A new Expr with substitutions.

kd.expr.sub_by_name(expr: Expr, /, **subs: Any) -> Expr

Returns `expr` with named subexpressions replaced.

Use `kde.with_name(expr, name)` to create a named subexpression.

Example:
  foo = kde.with_name(I.x, 'foo')
  bar = kde.with_name(I.y, 'bar')
  expr = foo + bar
  kd.sub_by_name(expr, foo=I.z)
  # -> I.z + kde.with_name(I.y, 'bar')

Args:
  expr: an expression.
  **subs: mapping from subexpression name to replacement node.

kd.expr.sub_inputs(expr: Expr, container: InputContainer = InputContainer('I'), /, **subs: Any) -> Expr

Returns an expression with `container` inputs replaced with Expr(s).

kd.expr.unpack_expr(ds: DataSlice) -> Expr

Unpacks an Expr stored in a DataItem.

kd.expr.unwrap_named(expr: Expr) -> Expr

Unwraps a named Expr, raising if it is not named.