ransack.transformer module

transformer.py - Provides transformers for converting Lark’s AST into more usable Python objects.

This module contains the ExpressionTransformer and SQLTransformer classes, which extend Lark’s Transformer to convert the parse tree generated by the Lark parser into more useful Python and SQL objects. ExpressionTransformer handles the interpretation of parsed structures like IP addresses, ranges, datetime objects, and arithmetic expressions, transforming them into Python data structures. SQLTransformer translates these expressions into SQL syntax for database queries.

Classes:

TokenWrapper: A wrapper for Lark Token to provide a real_value
attribute.
ExpressionTransformer: Converts nodes from the Lark parse tree
into Python objects (e.g., IP addresses, datetime objects, timedelta, lists, strings).
SQLTransformer: Converts parse tree nodes into SQL expressions
suitable for SQL query generation, supporting logical and arithmetic operations.

class ransack.transformer.ExpressionTransformer(context: dict[str, Any] | None = None)

Bases: Transformer

A transformer that converts various nodes from the Lark parse tree into appropriate objects (ipranges, datetime, list, …).

datetime_full(date: Token, time: Token) → Tree[TokenWrapper]

Transforms a full datetime string into a datetime object.

Parameters:

date – A token representing the date.
time – A token representing the time (can include timezone).

Returns:

A tree node wrapping a datetime object.

datetime_only_date(date: Token) → Tree[TokenWrapper]

Transforms a date string into a datetime object set to midnight UTC.

Parameters:: date – A token representing the date.
Returns:: A tree node wrapping a datetime object set to midnight UTC.

function(name: Token, args: Tree[TokenWrapper]) → Tree[TokenWrapper]

Transforms a function token and its arguments into a function tree node.

Parameters:

name – A token representing the function name, including an opening bracket.
args – A Tree object containing function arguments.

Returns:

A tree node representing the function call.

ipv4_cidr(net: Token) → Tree[TokenWrapper]

Transforms an IPv4 CIDR (network address and prefix) into an IP4Net object.

Parameters:: net – The CIDR network.
Returns:: A tree node wrapping an IP4Net object.

ipv4_range(range_: Token) → Tree[TokenWrapper]

Transforms an IPv4 range (start IP to end IP) into an IP4Range object.

Parameters:: range – The IPv4 range in a format start-end.
Returns:: A tree node wrapping an IP4Range object

ipv4_single(data: Token) → Tree[TokenWrapper]

Transforms a single IPv4 address into an IP4 object.

Parameters:: data – A token representing a single IPv4 address.
Returns:: A tree node wrapping an IP4 object.

ipv6_cidr(net: Token) → Tree[TokenWrapper]

Transforms an IPv6 CIDR (network address and prefix) into an IP6Net object.

Parameters:: net – The CIDR network.
Returns:: A tree node wrapping an IP6Net object.

ipv6_range(range_: Token) → Tree[TokenWrapper]

Transforms an IPv6 range (start IP to end IP) into an IP6Range object.

Parameters:: range – The IPv6 range in a format start-end.
Returns:: A tree node wrapping an IP6Range object.

ipv6_single(data: Token) → Tree[TokenWrapper]

Transforms a single IPv6 address into an IP6 object.

Parameters:: data – A token representing a single IPv6 address.
Returns:: A tree node wrapping an IP6 object.

number(data: Token) → Tree[TokenWrapper]

Transforms a token representing a number into an integer or float.

Parameters:: data – A token representing a number (can be an integer or float in string form).
Returns:: A tree node wrapping the number as int or float.

range_op(start: TokenWrapper, end: TokenWrapper)

Transforms a range operation (start to end) into an appropriate range object.

Parameters:

start – The start token of the range.
end – The end token of the range.

Returns:

A tree node wrapping a range object. If the tokens represent IP addresses, the range will be transformed into an IP4Range or IP6Range object, depending on the IP version; otherwise, it will return a generic range operation node.

string(data: Token) → Tree[TokenWrapper]

Transforms a string (enclosed in quotes) into a regular string.

Parameters:: data – A token representing a string (enclosed in single or double quotes).
Returns:: A tree node wrapping the string with quotes stripped.

timedelta(duration: Token) → Tree[TokenWrapper]

Transforms a token representing a duration into a timedelta object.

Parameters:: duration – A token representing the duration in the format [days]D HH:MM:SS, e.g., ‘2D12:34:56’.
Returns:: A tree node wrapping a timedelta object.

variable(var: Token) → Tree

Resolves a variable token to either a context value or data-driven variable.

Parameters:: var – The variable token to resolve. If prefixed by ‘.’, it is interpreted as coming directly from data; otherwise, it checks the context for predefined constants.
Returns:: A tree node representing the variable’s resolved value, either from context or as a raw variable name from data.

class ransack.transformer.Filter

Bases: Interpreter

A class that evaluates parsed expressions using provided data.

It provides methods to handle various operations such as arithmetic, logical conditions, and data extraction.

add(l_tree: Tree, r_tree: Tree) → Any

and_op(l_tree: Tree, r_tree: Tree) → bool

Performs a logical AND operation.

If the left tree is evaluated to False, the right tree is not traversed.

Parameters:

l_tree – The left subtree.
r_tree – The right subtree.

Returns:

True if both subtrees evaluate to True, otherwise False.

any_eq(l_tree: Tree, r_tree: Tree) → bool

concat_op(l_tree: Tree, r_tree: Tree) → list | str

Concatenates two sequences or strings.

Parameters:

l_tree – Subtree representing the first sequence or string.
r_tree – Subtree representing the second sequence or string.

Returns:

The concatenated result.

contains_op(l_tree: Tree, r_tree: Tree) → bool

Checks if a string data contains string value.

Parameters:

l_tree – Subtree representing the string being searched.
r_tree – Subtree representing the value to check.

Returns:

True if the string contains the value, otherwise False.

data = None

datetime(token: TokenWrapper) → datetime

Extracts a datetime value from a token.

Parameters:: token – A TokenWrapper object.
Returns:: The datetime value associated with the token.

div(l_tree: Tree, r_tree: Tree) → Any

eq(l_tree: Tree, r_tree: Tree) → bool

eval(tree: Tree, data: dict | None = None)

Evaluates the given tree using the provided data.

Parameters:

tree – The parse tree to evaluate.
data – Optional dictionary containing the data being searched.

Returns:

The result of evaluating the tree.

exists_op(path: Token) → bool

Tests whether a variable on a given path exists in data.

Parameters:: path – The variable name as a string.
Returns:: True if the variable exists, otherwise False.

exists_with_default(path: Token, default: Any) → Any

Tests whether a variable on a given path exists in data and returns its value or a default if not found.

Parameters:

path – The variable name as a string.
default – The value to return if the variable does not exist.

Returns:

The value of the variable if it exists, otherwise the default value.

function_(name: TokenWrapper, args: Tree | None)

Calls a predefined function with the given arguments.

Parameters:

name – The name of the function as a TokenWrapper.
args – A Tree object containing function arguments or None.

Returns:

The result of the function call.

Raises:

ValueError – If the function name is not found in predefined functions.

gt(l_tree: Tree, r_tree: Tree) → bool

gte(l_tree: Tree, r_tree: Tree) → bool

in_op(l_tree: Tree, r_tree: Tree) → bool

Checks if a value exists within a data structure.

Parameters:

l_tree – Subtree representing the value to look for.
r_tree – Subtree representing the data structure.

Returns:

True if the value exists in the data structure, otherwise False.

ip(token: TokenWrapper) → IP4

Extracts an IP address from a token.

Parameters:: token – A TokenWrapper object.
Returns:: The IP4 address associated with the token.

like_op(l_tree: Tree, r_tree: Tree) → bool

Checks if a string matches a regular expression pattern.

Parameters:

l_tree – Subtree representing the string to check.
r_tree – Subtree representing the regex pattern.

Returns:

True if the string matches the pattern, otherwise False.

list(data: Tree) → list

Extracts non-None children from a tree structure.

Parameters:: data – A Tree object.
Returns:: A list of non-None children from the tree.

lt(l_tree: Tree, r_tree: Tree) → bool

lte(l_tree: Tree, r_tree: Tree) → bool

mod(l_tree: Tree, r_tree: Tree) → Any

mul(l_tree: Tree, r_tree: Tree) → Any

neg(tree: Tree) → Any

not_op(tree: Tree) → bool

Performs a logical NOT operation.

Parameters:: tree – The subtree.
Returns:: True if the subtree evaluates to False, otherwise False.

number(token: TokenWrapper) → int | float

Extracts a numeric value from a token.

Parameters:: token – A TokenWrapper object.
Returns:: The numeric value associated with the token.

or_op(l_tree: Tree, r_tree: Tree) → bool

Performs a logical OR operation.

If the left tree is evaluated to True, the right tree is not traversed.

Parameters:

l_tree – The left subtree.
r_tree – The right subtree.

Returns:

True if either subtree evaluates to True, otherwise False.

range_op(l_tree: Tree, r_tree: Tree) → tuple

Creates a tuple representing a range.

Parameters:

l_tree – Subtree representing the start of the range.
r_tree – Subtree representing the end of the range.

Returns:

A tuple containing the start and end values.

string_(token: TokenWrapper) → str

Extracts a string value from a token.

Parameters:: token – A TokenWrapper object.
Returns:: The string value associated with the token.

sub(l_tree: Tree, r_tree: Tree) → Any

timedelta_(token: TokenWrapper) → timedelta

Extracts a timedelta value from a token.

Parameters:: token – A TokenWrapper object.
Returns:: The timedelta value associated with the token.

var_from_context(var) → Any

Retrieves a variable directly from the context.

Parameters:: var – The variable name.
Returns:: The value of the variable in the context.

var_from_data(var: TokenWrapper)

Retrieves a variable’s value from the data dictionary.

Parameters:: var – The variable name as a string.
Returns:: The value associated with the variable in the data dictionary.
Raises:: EvaluationError – If var is not found in the provided data.

class ransack.transformer.SQLTransformer(visit_tokens: bool = True)

Bases: Transformer

A transformer that converts nodes from the Lark parse tree into SQL expressions.

The SQLTransformer class supports logical, comparison, and arithmetic operations, translating them into valid SQL syntax. It enables the creation of SQL expressions from parsed data, including IP addresses, timestamps, intervals, and strings.

add(left: str, right: str) → str: Addition in SQL.

and_op(left: str, right: str) → str

Transforms an AND operation into SQL syntax.

Parameters:

left – The left operand in the AND operation.
right – The right operand in the AND operation.

Returns:

The SQL AND operation as a string.

datetime(dtime: TokenWrapper) → str

Transforms a datetime object into SQL syntax.

Parameters:: dtime – The datetime object to convert.
Returns:: The SQL representation of the datetime with timestamp format.

div(left: str, right: str) → str: Division in SQL.

eq(left: str, right: str) → str: Equality comparison in SQL.

gt(left: str, right: str) → str: Greater than comparison in SQL.

gte(left: str, right: str) → str: Greater than or equal to comparison in SQL.

in_op(values, data) → str

Transforms an IN or BETWEEN operation into SQL syntax.

Parameters:

values – The value or expression to check.
data – The list of values for IN or the range for BETWEEN.

Returns:

The SQL IN or BETWEEN operation as a string.

ip(data: TokenWrapper) → str

Transforms an IP address node into SQL syntax.

Parameters:: data – The IP address data.
Returns:: The SQL representation of the IP address.

like_op(column: str, pattern: str) → str

Transforms a LIKE operation into SQL syntax.

Parameters:

column – The column name to search.
pattern – The pattern to match in the LIKE operation.

Returns:

The SQL LIKE operation as a string.

list(data: Tree) → str

Transforms a list node into SQL syntax.

Parameters:: data – A tree node containing the list elements.
Returns:: The SQL representation of the list.

lt(left: str, right: str) → str: Less than comparison in SQL.

lte(left: str, right: str) → str: Less than or equal to comparison in SQL.

mod(left: str, right: str) → str: Modulus operation in SQL.

mul(left: str, right: str) → str: Multiplication in SQL.

not_op(cond: str) → str

Transforms a NOT operation into SQL syntax.

Parameters:: cond – The condition to negate in the NOT operation.
Returns:: The SQL NOT operation as a string.

number(number: TokenWrapper) → str

Transforms a datetime object into SQL syntax.

Parameters:: dtime – The datetime object to convert.
Returns:: The SQL representation of the datetime with timestamp format.

or_op(left: str, right: str) → str

Transforms an OR operation into SQL syntax.

Parameters:

left – The left operand in the OR operation.
right – The right operand in the OR operation.

Returns:

The SQL OR operation as a string.

range_op(start, end) → str

Transforms a range into SQL BETWEEN syntax.

Parameters:: range – A tuple representing the start and end of the range.
Returns:: The SQL BETWEEN representation of the range.

string_(data: TokenWrapper) → str

Transforms a string node into SQL syntax.

Parameters:: data – The string value.
Returns:: The SQL representation of the string.

sub(left: str, right: str) → str: Subtraction in SQL.

timedelta_(timedelta: TokenWrapper) → str

Transforms a timedelta object into SQL interval syntax.

Parameters:: timedelta – The timedelta object to convert.
Returns:: The SQL interval representation of the timedelta.

var_from_context(var)

Transforms a context variable node into SQL syntax.

Parameters:: var – The variable name sourced from context.
Returns:: The SQL representation of the context variable.

var_from_data(var)

Transforms a data variable node into SQL syntax.

Parameters:: var – The variable name sourced from data.
Returns:: The SQL representation of the data variable.

class ransack.transformer.TokenWrapper(token: Token, value: Any)

Bases: object

A wrapper of Lark Token to provide a real_value attribute.

property real_value: Any: Returns the stored value.

ransack.transformer.get_values(data: Mapping | MutableSequence | None, path: str) → list

Public API method to retrieve values from a nested data structure using a dotted path. Returns a flat list of values or an empty list if nothing is found.

Parameters:

path – A string representing a path of keys, separated by dots.
data – The data to search within.

Returns:

A list of values found at the specified path.