def validate(self, value=_undefined, name=None):
"""
Parameters
----------
value : Any, default undefined
Raises TypeError if argument is mandatory but not value has been
given.
name : Optional[str]
Argument name for error message
"""
if self.optional:
if value is _undefined or value is None:
if self.default is None:
return None
elif util.is_function(self.default):
value = self.default()
else:
value = self.default
elif value is _undefined:
if name is not None:
name_msg = "argument `{}`".format(name)
else:
name_msg = "unnamed argument"
raise TypeError("Missing required value for {}".format(name_msg))
return self.validator(value)
def validate(self, value=_undefined, name=None):
"""
Parameters
----------
value : Any, default undefined
Raises TypeError if argument is mandatory but not value has been
given.
name : Optional[str]
Argument name for error message
"""
if self.optional:
if value is _undefined or value is None:
if self.default is None:
return None
elif util.is_function(self.default):
value = self.default()
else:
value = self.default
elif value is _undefined:
if name is not None:
name_msg = "argument `{}`".format(name)
else:
name_msg = "unnamed argument"
raise TypeError("Missing required value for {}".format(name_msg))
return self.validator(value)
def __call__(self, arg, **kwargs):
if arg is None:
if self.default is None:
return None
elif util.is_function(self.default):
arg = self.default()
else:
arg = self.default
return self.validator(arg, **kwargs)
def mutate(table, exprs=None, **kwds):
"""
Convenience function for table projections involving adding columns
Parameters
----------
exprs : list, default None
List of named expressions to add as columns
kwds : keywords for new columns
Examples
--------
expr = table.mutate(qux=table.foo + table.bar, baz=5)
Returns
-------
mutated : TableExpr
"""
if exprs is None:
exprs = []
else:
exprs = util.promote_list(exprs)
for k, v in sorted(kwds.items()):
if util.is_function(v):
v = v(table)
else:
v = as_value_expr(v)
exprs.append(v.name(k))
has_replacement = False
for expr in exprs:
if expr.get_name() in table:
has_replacement = True
if has_replacement:
by_name = dict((x.get_name(), x) for x in exprs)
used = set()
proj_exprs = []
for c in table.columns:
if c in by_name:
proj_exprs.append(by_name[c])
used.add(c)
else:
proj_exprs.append(c)
for x in exprs:
if x.get_name() not in used:
proj_exprs.append(x)
return table.projection(proj_exprs)
else:
return table.projection([table] + exprs)
def mutate(table, exprs=None, **kwds):
"""
Convenience function for table projections involving adding columns
Parameters
----------
exprs : list, default None
List of named expressions to add as columns
kwds : keywords for new columns
Examples
--------
expr = table.mutate(qux=table.foo + table.bar, baz=5)
Returns
-------
mutated : TableExpr
"""
if exprs is None:
exprs = []
else:
exprs = util.promote_list(exprs)
for k, v in sorted(kwds.items()):
if util.is_function(v):
v = v(table)
else:
v = as_value_expr(v)
exprs.append(v.name(k))
has_replacement = False
for expr in exprs:
if expr.get_name() in table:
has_replacement = True
if has_replacement:
by_name = dict((x.get_name(), x) for x in exprs)
used = set()
proj_exprs = []
for c in table.columns:
if c in by_name:
proj_exprs.append(by_name[c])
used.add(c)
else:
proj_exprs.append(c)
for x in exprs:
if x.get_name() not in used:
proj_exprs.append(x)
return table.projection(proj_exprs)
else:
return table.projection([table] + exprs)
def function_of(
argument,
fn,
*,
output_rule=any,
preprocess=identity,
this,
):
if not util.is_function(fn):
raise com.IbisTypeError('argument `fn` must be a function or lambda')
return output_rule(fn(preprocess(getattr(this, argument))), this=this)
def function_of(
arg,
fn,
*,
output_rule=any,
this,
):
if not util.is_function(fn):
raise com.IbisTypeError(
'argument `fn` must be a function, lambda or deferred operation')
if isinstance(arg, str):
arg = this[arg]
elif callable(arg):
arg = arg(this=this)
return output_rule(fn(arg), this=this)
def mutate(
self,
exprs: Sequence[ir.Expr] | None = None,
**mutations: ir.Value,
) -> Table:
"""Add columns to a table expression.
Parameters
----------
exprs
List of named expressions to add as columns
mutations
Named expressions using keyword arguments
Returns
-------
Table
Table expression with additional columns
Examples
--------
Using keywords arguments to name the new columns
>>> import ibis
>>> table = ibis.table(
... [('foo', 'double'), ('bar', 'double')],
... name='t'
... )
>>> expr = table.mutate(qux=table.foo + table.bar, baz=5)
>>> expr
r0 := UnboundTable[t]
foo float64
bar float64
Selection[r0]
selections:
r0
baz: 5
qux: r0.foo + r0.bar
Use the [`name`][ibis.expr.types.generic.Value.name] method to name
the new columns.
>>> new_columns = [ibis.literal(5).name('baz',),
... (table.foo + table.bar).name('qux')]
>>> expr2 = table.mutate(new_columns)
>>> expr.equals(expr2)
True
"""
from ibis.expr import analysis as an
from ibis.expr import rules as rlz
exprs = [] if exprs is None else util.promote_list(exprs)
for name, expr in sorted(
mutations.items(), key=operator.itemgetter(0)
):
if util.is_function(expr):
value = expr(self)
elif isinstance(expr, Deferred):
value = expr.resolve(self)
else:
value = rlz.any(expr)
exprs.append(value.name(name))
mutation_exprs = an.get_mutation_exprs(exprs, self)
return self.projection(mutation_exprs)