polars.plugins.register_plugin_function

polars.plugins.register_plugin_function(

*,

plugin_path: Path | str,

function_name: str,

args: IntoExpr | Iterable[IntoExpr],

kwargs: dict[str, Any] | None = None,

is_elementwise: bool = False,

changes_length: bool = False,

returns_scalar: bool = False,

cast_to_supertype: bool = False,

input_wildcard_expansion: bool = False,

pass_name_to_apply: bool = False,

use_abs_path: bool = False,

is_deterministic: bool = True,

) → Expr

Register a plugin function.

See the user guide for more information about plugins.

Parameters:

plugin_path

Path to the plugin package. Accepts either the file path to the dynamic library file or the path to the directory containing it.

function_name

The name of the Rust function to register.

args

The arguments passed to this function. These get passed to the input argument on the Rust side, and have to be expressions (or be convertible to expressions).

kwargs

Non-expression arguments to the plugin function. These must be JSON serializable.

is_elementwise

Indicate that the function operates on scalars only. This will potentially trigger fast paths.

changes_length

Indicate that the function will change the length of the expression. For example, a unique or slice operation.

returns_scalar

Automatically explode on unit length if the function ran as final aggregation. This is the case for aggregations like sum, min, covariance etc.

cast_to_supertype

Cast the input expressions to their supertype.

input_wildcard_expansion

Expand wildcard expressions before executing the function.

pass_name_to_apply

If set to True, the Series passed to the function in a group-by operation will ensure the name is set. This is an extra heap allocation per group.

use_abs_path

If set to True, the path will be resolved to an absolute path. The path to the dynamic library is relative to the virtual environment by default.

is_deterministic

Indicate that the function produces the same output for the same inputs, allowing common subexpression and subplan elimination. Set to False for functions with randomness, observable side effects, or results that depend on external state.

Returns:

Expr

Warning

This is highly unsafe as this will call the C function loaded by plugin::function_name.

The parameters you set dictate how Polars will handle the function. Make sure they are correct!