ransack.transformer module

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

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

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).

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.

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.

Caches the returned value for a given tuple - function name and its arguments - so it can return the same value for subsequent calls.

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.

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 | IP4Range | IP6Range

Creates a tuple representing a range, or IP4Range/IP6Range.

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 or IP4Range/IP6Range object for ip ranges.

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.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.