Filters

Serializable filter expressions for row filtering operations.

Overview

The filter system provides a way to build complex filter conditions that can be serialized to JSON and deserialized back. This enables reproducible pipelines that can be saved and shared.

from transformplan import Col, Filter

# Build a filter
filter_expr = (Col("age") >= 18) & (Col("status") == "active")

# Use in pipeline
plan = TransformPlan().rows_filter(filter_expr)

# Serialize
filter_dict = filter_expr.to_dict()

# Deserialize
restored = Filter.from_dict(filter_dict)

Col Class

Col

Col(name: str)

Column reference for building filter expressions.

Col provides a fluent interface for creating filter conditions on DataFrame columns. Use comparison operators and methods to build filters that can be combined using & (and), | (or), and ~ (not).

Parameters:

Name	Type	Description	Default
name	str	The name of the column to reference.	required

Example

Comparison operators

Col("age") >= 18 Col("status") == "active" Col("price") < 100

String methods

Col("email").str_contains("@company.com") Col("name").str_starts_with("A")

Null checks

Col("optional").is_null() Col("required").is_not_null()

Membership

Col("country").is_in(["US", "CA", "MX"]) Col("age").between(18, 65)

Combining conditions

(Col("age") >= 18) & (Col("status") == "active") (Col("role") == "admin") | (Col("role") == "moderator")

Initialize a column reference.

Parameters:

Name	Type	Description	Default
name	str	The name of the column to reference.	required

Source code in transformplan/filters.py

def __init__(self, name: str) -> None:
    """Initialize a column reference.

    Args:
        name: The name of the column to reference.
    """
    self.name = name

__eq__

__eq__(value: object) -> Eq

Create an equality filter (column == value).

Parameters:

Name	Type	Description	Default
value	object	Value to compare against.	required

Returns:

Type	Description
Eq	Eq filter for column equals value.

Source code in transformplan/filters.py

def __eq__(self, value: object) -> Eq:  # type: ignore[override]
    """Create an equality filter (column == value).

    Args:
        value: Value to compare against.

    Returns:
        Eq filter for column equals value.
    """
    return Eq(self.name, value)

__ne__

__ne__(value: object) -> Ne

Create an inequality filter (column != value).

Parameters:

Name	Type	Description	Default
value	object	Value to compare against.	required

Returns:

Type	Description
Ne	Ne filter for column not equals value.

Source code in transformplan/filters.py

def __ne__(self, value: object) -> Ne:  # type: ignore[override]
    """Create an inequality filter (column != value).

    Args:
        value: Value to compare against.

    Returns:
        Ne filter for column not equals value.
    """
    return Ne(self.name, value)

__gt__

__gt__(value: Any) -> Gt

Create a greater-than filter (column > value).

Parameters:

Name	Type	Description	Default
value	Any	Value to compare against.	required

Returns:

Type	Description
Gt	Gt filter for column greater than value.

Source code in transformplan/filters.py

def __gt__(self, value: Any) -> Gt:  # noqa: ANN401
    """Create a greater-than filter (column > value).

    Args:
        value: Value to compare against.

    Returns:
        Gt filter for column greater than value.
    """
    return Gt(self.name, value)

__ge__

__ge__(value: Any) -> Ge

Create a greater-or-equal filter (column >= value).

Parameters:

Name	Type	Description	Default
value	Any	Value to compare against.	required

Returns:

Type	Description
Ge	Ge filter for column greater than or equal to value.

Source code in transformplan/filters.py

def __ge__(self, value: Any) -> Ge:  # noqa: ANN401
    """Create a greater-or-equal filter (column >= value).

    Args:
        value: Value to compare against.

    Returns:
        Ge filter for column greater than or equal to value.
    """
    return Ge(self.name, value)

__lt__

__lt__(value: Any) -> Lt

Create a less-than filter (column < value).

Parameters:

Name	Type	Description	Default
value	Any	Value to compare against.	required

Returns:

Type	Description
Lt	Lt filter for column less than value.

Source code in transformplan/filters.py

def __lt__(self, value: Any) -> Lt:  # noqa: ANN401
    """Create a less-than filter (column < value).

    Args:
        value: Value to compare against.

    Returns:
        Lt filter for column less than value.
    """
    return Lt(self.name, value)

__le__

__le__(value: Any) -> Le

Create a less-or-equal filter (column <= value).

Parameters:

Name	Type	Description	Default
value	Any	Value to compare against.	required

Returns:

Type	Description
Le	Le filter for column less than or equal to value.

Source code in transformplan/filters.py

def __le__(self, value: Any) -> Le:  # noqa: ANN401
    """Create a less-or-equal filter (column <= value).

    Args:
        value: Value to compare against.

    Returns:
        Le filter for column less than or equal to value.
    """
    return Le(self.name, value)

is_in

is_in(values: Sequence[Any]) -> IsIn

Create a membership filter (column in values).

Parameters:

Name	Type	Description	Default
values	Sequence[Any]	Sequence of values to check membership against.	required

Returns:

Type	Description
IsIn	IsIn filter for column value in the given sequence.

Example

Col("status").is_in(["active", "pending"])

Source code in transformplan/filters.py

def is_in(self, values: Sequence[Any]) -> IsIn:
    """Create a membership filter (column in values).

    Args:
        values: Sequence of values to check membership against.

    Returns:
        IsIn filter for column value in the given sequence.

    Example:
        >>> Col("status").is_in(["active", "pending"])
    """
    return IsIn(self.name, values)

is_null

is_null() -> IsNull

Create a null check filter (column is null).

Returns:

Type	Description
IsNull	IsNull filter for column is null.

Example

Col("optional_field").is_null()

Source code in transformplan/filters.py

def is_null(self) -> IsNull:
    """Create a null check filter (column is null).

    Returns:
        IsNull filter for column is null.

    Example:
        >>> Col("optional_field").is_null()
    """
    return IsNull(self.name)

is_not_null

is_not_null() -> IsNotNull

Create a not-null check filter (column is not null).

Returns:

Type	Description
IsNotNull	IsNotNull filter for column is not null.

Example

Col("required_field").is_not_null()

Source code in transformplan/filters.py

def is_not_null(self) -> IsNotNull:
    """Create a not-null check filter (column is not null).

    Returns:
        IsNotNull filter for column is not null.

    Example:
        >>> Col("required_field").is_not_null()
    """
    return IsNotNull(self.name)

str_contains

str_contains(pattern: str, *, literal: bool = True) -> StrContains

Create a string contains filter.

Parameters:

Name	Type	Description	Default
pattern	str	Substring or regex pattern to search for.	required
literal	bool	If True, treat pattern as literal string. If False, as regex.	True

Returns:

Type	Description
StrContains	StrContains filter for column containing pattern.

Example

Col("email").str_contains("@company.com") Col("description").str_contains(r"\d+", literal=False)

Source code in transformplan/filters.py

def str_contains(self, pattern: str, *, literal: bool = True) -> StrContains:
    r"""Create a string contains filter.

    Args:
        pattern: Substring or regex pattern to search for.
        literal: If True, treat pattern as literal string. If False, as regex.

    Returns:
        StrContains filter for column containing pattern.

    Example:
        >>> Col("email").str_contains("@company.com")
        >>> Col("description").str_contains(r"\\d+", literal=False)
    """
    return StrContains(self.name, pattern, literal)

str_starts_with

str_starts_with(prefix: str) -> StrStartsWith

Create a string starts-with filter.

Parameters:

Name	Type	Description	Default
prefix	str	Prefix to check for.	required

Returns:

Type	Description
StrStartsWith	StrStartsWith filter for column starting with prefix.

Example

Col("code").str_starts_with("PRD-")

Source code in transformplan/filters.py

def str_starts_with(self, prefix: str) -> StrStartsWith:
    """Create a string starts-with filter.

    Args:
        prefix: Prefix to check for.

    Returns:
        StrStartsWith filter for column starting with prefix.

    Example:
        >>> Col("code").str_starts_with("PRD-")
    """
    return StrStartsWith(self.name, prefix)

str_ends_with

str_ends_with(suffix: str) -> StrEndsWith

Create a string ends-with filter.

Parameters:

Name	Type	Description	Default
suffix	str	Suffix to check for.	required

Returns:

Type	Description
StrEndsWith	StrEndsWith filter for column ending with suffix.

Example

Col("filename").str_ends_with(".csv")

Source code in transformplan/filters.py

def str_ends_with(self, suffix: str) -> StrEndsWith:
    """Create a string ends-with filter.

    Args:
        suffix: Suffix to check for.

    Returns:
        StrEndsWith filter for column ending with suffix.

    Example:
        >>> Col("filename").str_ends_with(".csv")
    """
    return StrEndsWith(self.name, suffix)

between

between(lower: Any, upper: Any) -> Between

Create a range filter (lower <= column <= upper).

Parameters:

Name	Type	Description	Default
lower	Any	Lower bound (inclusive).	required
upper	Any	Upper bound (inclusive).	required

Returns:

Type	Description
Between	Between filter for column within range.

Example

Col("age").between(18, 65) Col("date").between("2024-01-01", "2024-12-31")

Source code in transformplan/filters.py

def between(self, lower: Any, upper: Any) -> Between:  # noqa: ANN401
    """Create a range filter (lower <= column <= upper).

    Args:
        lower: Lower bound (inclusive).
        upper: Upper bound (inclusive).

    Returns:
        Between filter for column within range.

    Example:
        >>> Col("age").between(18, 65)
        >>> Col("date").between("2024-01-01", "2024-12-31")
    """
    return Between(self.name, lower, upper)

Filter Base Class

Filter

Bases: ABC

Abstract base class for all filter expressions.

Filters are composable, serializable expressions that define row selection criteria. They can be combined using logical operators (&, |, ~) and serialized to dictionaries for storage and transmission.

Subclasses must implement

• to_expr(): Convert to a Polars expression
• to_dict(): Serialize to a dictionary
• _from_dict(): Deserialize from a dictionary (classmethod)

Example

filter1 = Col("age") >= 18 filter2 = Col("status") == "active" combined = filter1 & filter2 # And filter inverted = ~filter1 # Not filter

to_expr abstractmethod

to_expr() -> Expr

Convert to a Polars expression.

Returns:

Type	Description
Expr	A Polars expression that can be used with DataFrame.filter().

Source code in transformplan/filters.py

@abstractmethod
def to_expr(self) -> pl.Expr:
    """Convert to a Polars expression.

    Returns:
        A Polars expression that can be used with DataFrame.filter().
    """
    ...

to_dict abstractmethod

to_dict() -> dict[str, Any]

Serialize to a dictionary for JSON storage.

The dictionary includes a 'type' key identifying the filter class, plus any parameters needed to reconstruct the filter.

Returns:

Type	Description
dict[str, Any]	Dictionary representation of the filter.

Source code in transformplan/filters.py

@abstractmethod
def to_dict(self) -> dict[str, Any]:
    """Serialize to a dictionary for JSON storage.

    The dictionary includes a 'type' key identifying the filter class,
    plus any parameters needed to reconstruct the filter.

    Returns:
        Dictionary representation of the filter.
    """
    ...

from_dict classmethod

from_dict(data: dict[str, Any]) -> Filter

Deserialize a filter from a dictionary.

Uses the 'type' key to determine which filter class to instantiate.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Dictionary with 'type' key and filter parameters.	required

Returns:

Type	Description
Filter	Reconstructed Filter instance.

Raises:

Type	Description
ValueError	If 'type' is missing or unknown.

Example

data = {"type": "eq", "column": "status", "value": "active"} filter_obj = Filter.from_dict(data)

Source code in transformplan/filters.py

@classmethod
def from_dict(cls, data: dict[str, Any]) -> Filter:
    """Deserialize a filter from a dictionary.

    Uses the 'type' key to determine which filter class to instantiate.

    Args:
        data: Dictionary with 'type' key and filter parameters.

    Returns:
        Reconstructed Filter instance.

    Raises:
        ValueError: If 'type' is missing or unknown.

    Example:
        >>> data = {"type": "eq", "column": "status", "value": "active"}
        >>> filter_obj = Filter.from_dict(data)
    """
    filter_type = data.get("type")
    if filter_type is None:
        msg = "Missing 'type' in filter dict"
        raise ValueError(msg)

    filter_cls = _FILTER_REGISTRY.get(filter_type)
    if filter_cls is None:
        msg = f"Unknown filter type: {filter_type}"
        raise ValueError(msg)

    return filter_cls._from_dict(data)

Comparison Filters

Eq (Equal)

Eq dataclass

Eq(column: str, value: Any)

Bases: Filter

Equality filter: column == value.

Attributes:

Name	Type	Description
column	str	Name of the column to compare.
value	Any	Value to compare against.

to_expr

to_expr() -> Expr

Convert to Polars equality expression.

Returns:

Type	Description
Expr	Polars expression for equality comparison.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars equality expression.

    Returns:
        Polars expression for equality comparison.
    """
    return pl.col(self.column) == self.value

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, column, and value.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type, column, and value.
    """
    return {"type": "eq", "column": self.column, "value": self.value}

Ne (Not Equal)

Ne dataclass

Ne(column: str, value: Any)

Bases: Filter

Inequality filter: column != value.

Attributes:

Name	Type	Description
column	str	Name of the column to compare.
value	Any	Value to compare against.

to_expr

to_expr() -> Expr

Convert to Polars inequality expression.

Returns:

Type	Description
Expr	Polars expression for inequality comparison.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars inequality expression.

    Returns:
        Polars expression for inequality comparison.
    """
    return pl.col(self.column) != self.value

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, column, and value.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type, column, and value.
    """
    return {"type": "ne", "column": self.column, "value": self.value}

Gt (Greater Than)

Gt dataclass

Gt(column: str, value: Any)

Bases: Filter

Greater-than filter: column > value.

Attributes:

Name	Type	Description
column	str	Name of the column to compare.
value	Any	Value to compare against.

to_expr

to_expr() -> Expr

Convert to Polars greater-than expression.

Returns:

Type	Description
Expr	Polars expression for greater-than comparison.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars greater-than expression.

    Returns:
        Polars expression for greater-than comparison.
    """
    return pl.col(self.column) > self.value

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, column, and value.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type, column, and value.
    """
    return {"type": "gt", "column": self.column, "value": self.value}

Ge (Greater Than or Equal)

Ge dataclass

Ge(column: str, value: Any)

Bases: Filter

Greater-or-equal filter: column >= value.

Attributes:

Name	Type	Description
column	str	Name of the column to compare.
value	Any	Value to compare against.

to_expr

to_expr() -> Expr

Convert to Polars greater-or-equal expression.

Returns:

Type	Description
Expr	Polars expression for greater-or-equal comparison.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars greater-or-equal expression.

    Returns:
        Polars expression for greater-or-equal comparison.
    """
    return pl.col(self.column) >= self.value

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, column, and value.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type, column, and value.
    """
    return {"type": "ge", "column": self.column, "value": self.value}

Lt (Less Than)

Lt dataclass

Lt(column: str, value: Any)

Bases: Filter

Less-than filter: column < value.

Attributes:

Name	Type	Description
column	str	Name of the column to compare.
value	Any	Value to compare against.

to_expr

to_expr() -> Expr

Convert to Polars less-than expression.

Returns:

Type	Description
Expr	Polars expression for less-than comparison.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars less-than expression.

    Returns:
        Polars expression for less-than comparison.
    """
    return pl.col(self.column) < self.value

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, column, and value.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type, column, and value.
    """
    return {"type": "lt", "column": self.column, "value": self.value}

Le (Less Than or Equal)

Le dataclass

Le(column: str, value: Any)

Bases: Filter

Less-or-equal filter: column <= value.

Attributes:

Name	Type	Description
column	str	Name of the column to compare.
value	Any	Value to compare against.

to_expr

to_expr() -> Expr

Convert to Polars less-or-equal expression.

Returns:

Type	Description
Expr	Polars expression for less-or-equal comparison.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars less-or-equal expression.

    Returns:
        Polars expression for less-or-equal comparison.
    """
    return pl.col(self.column) <= self.value

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, column, and value.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type, column, and value.
    """
    return {"type": "le", "column": self.column, "value": self.value}

IsIn

IsIn dataclass

IsIn(column: str, values: Sequence[Any])

Bases: Filter

Membership filter: column value in list of values.

Attributes:

Name	Type	Description
column	str	Name of the column to check.
values	Sequence[Any]	Sequence of values to check membership against.

to_expr

to_expr() -> Expr

Convert to Polars is_in expression.

Returns:

Type	Description
Expr	Polars expression for membership check.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars is_in expression.

    Returns:
        Polars expression for membership check.
    """
    return pl.col(self.column).is_in(self.values)

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, column, and values.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type, column, and values.
    """
    return {"type": "is_in", "column": self.column, "values": list(self.values)}

Between

Between dataclass

Between(column: str, lower: Any, upper: Any)

Bases: Filter

Range filter: lower <= column <= upper.

Attributes:

Name	Type	Description
column	str	Name of the column to check.
lower	Any	Lower bound (inclusive).
upper	Any	Upper bound (inclusive).

to_expr

to_expr() -> Expr

Convert to Polars is_between expression.

Returns:

Type	Description
Expr	Polars expression for range check.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars is_between expression.

    Returns:
        Polars expression for range check.
    """
    return pl.col(self.column).is_between(self.lower, self.upper)

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, column, lower, and upper.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type, column, lower, and upper.
    """
    return {
        "type": "between",
        "column": self.column,
        "lower": self.lower,
        "upper": self.upper,
    }

Null Filters

IsNull

IsNull dataclass

IsNull(column: str)

Bases: Filter

Null check filter: column is null.

Attributes:

Name	Type	Description
column	str	Name of the column to check.

to_expr

to_expr() -> Expr

Convert to Polars is_null expression.

Returns:

Type	Description
Expr	Polars expression for null check.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars is_null expression.

    Returns:
        Polars expression for null check.
    """
    return pl.col(self.column).is_null()

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type and column.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type and column.
    """
    return {"type": "is_null", "column": self.column}

IsNotNull

IsNotNull dataclass

IsNotNull(column: str)

Bases: Filter

Not-null check filter: column is not null.

Attributes:

Name	Type	Description
column	str	Name of the column to check.

to_expr

to_expr() -> Expr

Convert to Polars is_not_null expression.

Returns:

Type	Description
Expr	Polars expression for not-null check.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars is_not_null expression.

    Returns:
        Polars expression for not-null check.
    """
    return pl.col(self.column).is_not_null()

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type and column.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type and column.
    """
    return {"type": "is_not_null", "column": self.column}

String Filters

StrContains

StrContains dataclass

StrContains(column: str, pattern: str, literal: bool = True)

Bases: Filter

String contains filter: column contains pattern.

Attributes:

Name	Type	Description
column	str	Name of the string column to search.
pattern	str	Substring or regex pattern to find.
literal	bool	If True, treat pattern as literal. If False, as regex.

to_expr

to_expr() -> Expr

Convert to Polars str.contains expression.

Returns:

Type	Description
Expr	Polars expression for string containment check.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars str.contains expression.

    Returns:
        Polars expression for string containment check.
    """
    return pl.col(self.column).str.contains(self.pattern, literal=self.literal)

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, column, pattern, and literal.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type, column, pattern, and literal.
    """
    return {
        "type": "str_contains",
        "column": self.column,
        "pattern": self.pattern,
        "literal": self.literal,
    }

StrStartsWith

StrStartsWith dataclass

StrStartsWith(column: str, prefix: str)

Bases: Filter

String starts-with filter: column starts with prefix.

Attributes:

Name	Type	Description
column	str	Name of the string column to check.
prefix	str	Prefix to match at the start.

to_expr

to_expr() -> Expr

Convert to Polars str.starts_with expression.

Returns:

Type	Description
Expr	Polars expression for prefix check.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars str.starts_with expression.

    Returns:
        Polars expression for prefix check.
    """
    return pl.col(self.column).str.starts_with(self.prefix)

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, column, and prefix.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type, column, and prefix.
    """
    return {"type": "str_starts_with", "column": self.column, "prefix": self.prefix}

StrEndsWith

StrEndsWith dataclass

StrEndsWith(column: str, suffix: str)

Bases: Filter

String ends-with filter: column ends with suffix.

Attributes:

Name	Type	Description
column	str	Name of the string column to check.
suffix	str	Suffix to match at the end.

to_expr

to_expr() -> Expr

Convert to Polars str.ends_with expression.

Returns:

Type	Description
Expr	Polars expression for suffix check.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars str.ends_with expression.

    Returns:
        Polars expression for suffix check.
    """
    return pl.col(self.column).str.ends_with(self.suffix)

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, column, and suffix.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary.

    Returns:
        Dictionary representation with type, column, and suffix.
    """
    return {"type": "str_ends_with", "column": self.column, "suffix": self.suffix}

Logical Combinators

And

And dataclass

And(left: Filter, right: Filter)

Bases: Filter

Logical AND filter: both conditions must be true.

Typically created using the & operator between filters.

Attributes:

Name	Type	Description
left	Filter	First filter condition.
right	Filter	Second filter condition.

Example

(Col("age") >= 18) & (Col("status") == "active")

to_expr

to_expr() -> Expr

Convert to Polars AND expression.

Returns:

Type	Description
Expr	Polars expression combining both conditions with AND.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars AND expression.

    Returns:
        Polars expression combining both conditions with AND.
    """
    return self.left.to_expr() & self.right.to_expr()

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary with nested filter dicts.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, left, and right.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary with nested filter dicts.

    Returns:
        Dictionary representation with type, left, and right.
    """
    return {
        "type": "and",
        "left": self.left.to_dict(),
        "right": self.right.to_dict(),
    }

Or

Or dataclass

Or(left: Filter, right: Filter)

Bases: Filter

Logical OR filter: at least one condition must be true.

Typically created using the | operator between filters.

Attributes:

Name	Type	Description
left	Filter	First filter condition.
right	Filter	Second filter condition.

Example

(Col("role") == "admin") | (Col("role") == "moderator")

to_expr

to_expr() -> Expr

Convert to Polars OR expression.

Returns:

Type	Description
Expr	Polars expression combining both conditions with OR.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars OR expression.

    Returns:
        Polars expression combining both conditions with OR.
    """
    return self.left.to_expr() | self.right.to_expr()

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary with nested filter dicts.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type, left, and right.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary with nested filter dicts.

    Returns:
        Dictionary representation with type, left, and right.
    """
    return {
        "type": "or",
        "left": self.left.to_dict(),
        "right": self.right.to_dict(),
    }

Not

Not dataclass

Not(operand: Filter)

Bases: Filter

Logical NOT filter: inverts the condition.

Typically created using the ~ operator on a filter.

Attributes:

Name	Type	Description
operand	Filter	Filter condition to invert.

Example

~(Col("deleted") == True)

to_expr

to_expr() -> Expr

Convert to Polars NOT expression.

Returns:

Type	Description
Expr	Polars expression inverting the operand condition.

Source code in transformplan/filters.py

def to_expr(self) -> pl.Expr:
    """Convert to Polars NOT expression.

    Returns:
        Polars expression inverting the operand condition.
    """
    return ~self.operand.to_expr()

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary with nested filter dict.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with type and operand.

Source code in transformplan/filters.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary with nested filter dict.

    Returns:
        Dictionary representation with type and operand.
    """
    return {"type": "not", "operand": self.operand.to_dict()}

Examples

Simple Comparisons

from transformplan import Col

# Numeric comparisons
Col("age") >= 18
Col("price") < 100
Col("quantity") == 0

# String equality
Col("status") == "active"
Col("country") != "US"

String Matching

# Contains substring
Col("email").str_contains("@company.com")

# Starts/ends with
Col("code").str_starts_with("PRD-")
Col("filename").str_ends_with(".csv")

Membership Tests

# Check if value is in list
Col("status").is_in(["active", "pending"])

# Range check
Col("age").between(18, 65)

Null Checks

# Filter nulls
Col("email").is_not_null()
Col("optional_field").is_null()

Combining Conditions

# AND: both conditions must be true
(Col("age") >= 18) & (Col("status") == "active")

# OR: at least one condition must be true
(Col("role") == "admin") | (Col("role") == "moderator")

# NOT: invert condition
~(Col("deleted") == True)

# Complex combinations
(
    (Col("age") >= 18) &
    (Col("country").is_in(["US", "CA"])) &
    ~(Col("status") == "banned")
)