kiarina-lib-redisearch 1.0.0__py3-none-any.whl

kiarina/lib/redisearch/filter/_field/numeric.py

@@ -0,0 +1,178 @@
+from .._decorators import check_operator_misuse
+from .._enums import RedisearchFilterOperator
+from .._model import RedisearchFilter
+from .base import RedisearchFieldFilter
+
+
+class Numeric(RedisearchFieldFilter):
+    """
+    Filter for numeric fields.
+    """
+
+    # --------------------------------------------------
+    # Class Variables
+    # --------------------------------------------------
+
+    OPERATORS: dict[RedisearchFilterOperator, str] = {
+        RedisearchFilterOperator.EQ: "==",
+        RedisearchFilterOperator.NE: "!=",
+        RedisearchFilterOperator.LT: "<",
+        RedisearchFilterOperator.GT: ">",
+        RedisearchFilterOperator.LE: "<=",
+        RedisearchFilterOperator.GE: ">=",
+    }
+    """Supported operators"""
+
+    OPERATOR_MAP: dict[RedisearchFilterOperator, str] = {
+        RedisearchFilterOperator.EQ: "@%s:[%s %s]",
+        RedisearchFilterOperator.NE: "(-@%s:[%s %s])",
+        RedisearchFilterOperator.GT: "@%s:[(%s +inf]",
+        RedisearchFilterOperator.LT: "@%s:[-inf (%s]",
+        RedisearchFilterOperator.GE: "@%s:[%s +inf]",
+        RedisearchFilterOperator.LE: "@%s:[-inf %s]",
+    }
+    """Operator and query mapping"""
+
+    SUPPORTED_VALUE_TYPES = (int, float, type(None))
+    """Supported value types"""
+
+    # --------------------------------------------------
+    # Magic Methods
+    # --------------------------------------------------
+
+    def __str__(self) -> str:
+        """
+        Stringification
+
+        Converting filter expressions into query strings
+        """
+        if self._value is None:
+            return "*"
+
+        if (
+            self._operator == RedisearchFilterOperator.EQ
+            or self._operator == RedisearchFilterOperator.NE
+        ):
+            return self.OPERATOR_MAP[self._operator] % (
+                self._field_name,
+                self._value,
+                self._value,
+            )
+        else:
+            return self.OPERATOR_MAP[self._operator] % (self._field_name, self._value)
+
+    @check_operator_misuse
+    def __eq__(self, other: int | float) -> RedisearchFilter:
+        """
+        Create a numerical equivalence filter expression.
+
+        Args:
+            other (int | float): Value to filter by
+
+        Example:
+            >>> import kiarina.lib.redisearch.field as rf
+            >>> filter = rf.Numeric("zipcode") == 90210
+        """
+        self._set(
+            operator=RedisearchFilterOperator.EQ,
+            value=other,
+            value_type=self.SUPPORTED_VALUE_TYPES,  # type: ignore
+        )
+
+        return RedisearchFilter(str(self))
+
+    @check_operator_misuse
+    def __ne__(self, other: int | float) -> RedisearchFilter:
+        """
+        Create a numerical inequality filter expression.
+
+        Args:
+            other (int | float): Value to filter by
+
+        Example:
+            >>> import kiarina.lib.redisearch.field as rf
+            >>> filter = rf.Numeric("zipcode") != 90210
+        """
+        self._set(
+            operator=RedisearchFilterOperator.NE,
+            value=other,
+            value_type=self.SUPPORTED_VALUE_TYPES,  # type: ignore
+        )
+
+        return RedisearchFilter(str(self))
+
+    def __gt__(self, other: int | float) -> RedisearchFilter:
+        """
+        Create a numerical "greater than" filter expression.
+
+        Args:
+            other (int | float): Value to filter by
+
+        Example:
+            >>> import kiarina.lib.redisearch.field as rf
+            >>> filter = rf.Numeric("age") > 18
+        """
+        self._set(
+            operator=RedisearchFilterOperator.GT,
+            value=other,
+            value_type=self.SUPPORTED_VALUE_TYPES,  # type: ignore
+        )
+
+        return RedisearchFilter(str(self))
+
+    def __lt__(self, other: int | float) -> RedisearchFilter:
+        """
+        Create a numerical "less than" filter expression.
+
+        Args:
+            other (int | float): Value to filter by
+
+        Example:
+            >>> import kiarina.lib.redisearch.field as rf
+            >>> filter = rf.Numeric("age") < 18
+        """
+        self._set(
+            operator=RedisearchFilterOperator.LT,
+            value=other,
+            value_type=self.SUPPORTED_VALUE_TYPES,  # type: ignore
+        )
+
+        return RedisearchFilter(str(self))
+
+    def __ge__(self, other: int | float) -> RedisearchFilter:
+        """
+        Create a numerical "greater than or equal to" filter expression.
+
+        Args:
+            other (int | float): Value to filter by
+
+        Example:
+            >>> import kiarina.lib.redisearch.field as rf
+            >>> filter = rf.Numeric("age") >= 18
+        """
+        self._set(
+            operator=RedisearchFilterOperator.GE,
+            value=other,
+            value_type=self.SUPPORTED_VALUE_TYPES,  # type: ignore
+        )
+
+        return RedisearchFilter(str(self))
+
+    def __le__(self, other: int | float) -> RedisearchFilter:
+        """
+        Create a numerical "less than or equal to" filter expression.
+
+        Args:
+            other (int | float): Value to filter by
+
+        Example:
+            >>> import kiarina.lib.redisearch.field as rf
+            >>> filter = rf.Numeric("age") <= 18
+        """
+        self._set(
+            operator=RedisearchFilterOperator.LE,
+            value=other,
+            value_type=self.SUPPORTED_VALUE_TYPES,  # type: ignore
+        )
+
+        return RedisearchFilter(str(self))

kiarina/lib/redisearch/filter/_field/tag.py

@@ -0,0 +1,142 @@
+from typing import Dict, List, Set, Tuple, Union
+
+from .._decorators import check_operator_misuse
+from .._enums import RedisearchFilterOperator
+from .._model import RedisearchFilter
+from .._utils import escape_token
+from .base import RedisearchFieldFilter
+
+
+class Tag(RedisearchFieldFilter):
+    """
+    Filter for tag fields.
+    """
+
+    # --------------------------------------------------
+    # Class Variables
+    # --------------------------------------------------
+
+    OPERATORS: Dict[RedisearchFilterOperator, str] = {
+        RedisearchFilterOperator.EQ: "==",
+        RedisearchFilterOperator.NE: "!=",
+        RedisearchFilterOperator.IN: "==",
+    }
+    """Supported operators"""
+
+    OPERATOR_MAP: Dict[RedisearchFilterOperator, str] = {
+        RedisearchFilterOperator.EQ: "@%s:{%s}",
+        RedisearchFilterOperator.NE: "(-@%s:{%s})",
+        RedisearchFilterOperator.IN: "@%s:{%s}",
+    }
+    """Operator and query mapping"""
+
+    SUPPORTED_VALUE_TYPES = (list, set, tuple, str, type(None))
+    """Supported value types"""
+
+    # --------------------------------------------------
+    # Properties
+    # --------------------------------------------------
+
+    @property
+    def _formatted_tag_value(self) -> str:
+        """
+        Format the tag value for query representation.
+        """
+        return "|".join([escape_token(tag) for tag in self._value])
+
+    # --------------------------------------------------
+    # Magic Methods
+    # --------------------------------------------------
+
+    def __str__(self) -> str:
+        """
+        Stringification
+
+        Converting filter expressions into query strings
+        """
+        if not self._value:
+            return "*"
+
+        return self.OPERATOR_MAP[self._operator] % (
+            self._field_name,
+            self._formatted_tag_value,
+        )
+
+    @check_operator_misuse
+    def __eq__(
+        self, other: Union[List[str], Set[str], Tuple[str], str]
+    ) -> RedisearchFilter:
+        """
+        Create an equality filter expression for tags.
+
+        Args:
+            other (Union[List[str], Set[str], Tuple[str], str]):
+                The tags to filter by.
+
+        Example:
+            >>> import kiarina.lib.redisearch as rf
+            >>> filter = rf.Tag("color") == "blue"
+        """
+        self._set(
+            operator=RedisearchFilterOperator.EQ,
+            value=self._normalize_tag_value(other),
+            value_type=self.SUPPORTED_VALUE_TYPES,  # type: ignore
+        )
+
+        return RedisearchFilter(str(self))
+
+    @check_operator_misuse
+    def __ne__(
+        self, other: Union[List[str], Set[str], Tuple[str], str]
+    ) -> RedisearchFilter:
+        """
+        Create a not-equal filter expression for tags.
+
+        Args:
+            other (Union[List[str], Set[str], Tuple[str], str]):
+                The tags to filter by.
+
+        Example:
+            >>> import kiarina.lib.redisearch as rf
+            >>> filter = rf.Tag("color") != "blue"
+        """
+        self._set(
+            operator=RedisearchFilterOperator.NE,
+            value=self._normalize_tag_value(other),
+            value_type=self.SUPPORTED_VALUE_TYPES,  # type: ignore
+        )
+
+        return RedisearchFilter(str(self))
+
+    # --------------------------------------------------
+    # Private Methods
+    # --------------------------------------------------
+
+    def _normalize_tag_value(
+        self, other: Union[List[str], Set[str], Tuple[str], str]
+    ) -> List[str]:
+        """
+        Normalize the tag value to a list of strings.
+
+        Args:
+            other: The tag value to normalize.
+
+        Returns:
+            List[str]: Normalized tag values.
+
+        Raises:
+            ValueError: If tags within collection cannot be converted to strings.
+        """
+        if isinstance(other, (list, set, tuple)):
+            try:
+                return [str(val) for val in other if val]
+            except ValueError:
+                raise ValueError("All tags within collection must be strings")
+
+        elif not other:
+            return []
+
+        elif isinstance(other, str):
+            return [other]
+
+        return []

kiarina/lib/redisearch/filter/_field/text.py

@@ -0,0 +1,111 @@
+from .._decorators import check_operator_misuse
+from .._enums import RedisearchFilterOperator
+from .._model import RedisearchFilter
+from .base import RedisearchFieldFilter
+
+
+class Text(RedisearchFieldFilter):
+    """
+    Field for text fields.
+    """
+
+    # --------------------------------------------------
+    # Class Variables
+    # --------------------------------------------------
+
+    OPERATORS: dict[RedisearchFilterOperator, str] = {
+        RedisearchFilterOperator.EQ: "==",
+        RedisearchFilterOperator.NE: "!=",
+        RedisearchFilterOperator.LIKE: "%",
+    }
+    """Supported operators"""
+
+    OPERATOR_MAP: dict[RedisearchFilterOperator, str] = {
+        RedisearchFilterOperator.EQ: '@%s:("%s")',
+        RedisearchFilterOperator.NE: '(-@%s:"%s")',
+        RedisearchFilterOperator.LIKE: "@%s:(%s)",
+    }
+    """Operator and query mapping"""
+
+    SUPPORTED_VALUE_TYPES = (str, type(None))
+    """Supported value types"""
+
+    # --------------------------------------------------
+    # Magic Methods
+    # --------------------------------------------------
+
+    def __str__(self) -> str:
+        """
+        Stringification
+
+        Converting filter expressions into query strings
+        """
+        if not self._value:
+            return "*"
+
+        return self.OPERATOR_MAP[self._operator] % (
+            self._field_name,
+            self._value,
+        )
+
+    @check_operator_misuse
+    def __eq__(self, other: str) -> RedisearchFilter:
+        """
+        Create an equality (exact match) filter expression for strings.
+
+        Args:
+            other (str): The text value to filter by.
+
+        Example:
+            >>> import kiarina.lib.redisearch as rf
+            >>> filter = rf.Text("job") == "engineer"
+        """
+        self._set(
+            operator=RedisearchFilterOperator.EQ,
+            value=other,
+            value_type=self.SUPPORTED_VALUE_TYPES,  # type: ignore
+        )
+
+        return RedisearchFilter(str(self))
+
+    @check_operator_misuse
+    def __ne__(self, other: str) -> RedisearchFilter:
+        """
+        Create a non-equality (not equal) filter expression for strings.
+
+        Args:
+            other (str): The text value to filter by.
+
+        Example:
+            >>> import kiarina.lib.redisearch as rf
+            >>> filter = rf.Text("job") != "engineer"
+        """
+        self._set(
+            operator=RedisearchFilterOperator.NE,
+            value=other,
+            value_type=self.SUPPORTED_VALUE_TYPES,  # type: ignore
+        )
+
+        return RedisearchFilter(str(self))
+
+    def __mod__(self, other: str) -> RedisearchFilter:
+        """
+        Create a "LIKE" filter expression for strings.
+
+        Args:
+            other (str): The text value to filter by.
+
+        Example:
+            >>> import kiarina.lib.redisearch as rf
+            >>> filter = rf.Text("job") % "engine*"         # Suffix wildcard match
+            >>> filter = rf.Text("job") % "%%engine%%"      # Fuzzy match (using edit distance)
+            >>> filter = rf.Text("job") % "engineer|doctor" # Contains either term
+            >>> filter = rf.Text("job") % "engineer doctor" # Contains both terms
+        """
+        self._set(
+            operator=RedisearchFilterOperator.LIKE,
+            value=other,
+            value_type=self.SUPPORTED_VALUE_TYPES,  # type: ignore
+        )
+
+        return RedisearchFilter(str(self))

kiarina/lib/redisearch/filter/_model.py

@@ -0,0 +1,93 @@
+from typing import Self
+
+from ._enums import RedisearchFilterOperator
+
+
+class RedisearchFilter:
+    """
+    A class representing the filter condition expression for a Redisearch query.
+
+    RedisearchFilter can be combined using & and | operators to create
+    complex logical expressions that are evaluated in the Redis Query language.
+
+    This interface allows users to construct complex queries without needing to know
+    the Redis Query language.
+
+    Filter-based fields are not initialised directly.
+    Instead, they are constructed by combining RedisFilterFields
+    using the & and | operators.
+
+    Examples:
+        >>> import kiarina.lib.redisearch.filter as rf
+        >>> filter = (rf.Tag("color") == "blue") & (rf.Numeric("price") < 100)
+        >>> print(str(filter))
+        (@color:{blue} @price:[-inf (100)])
+    """
+
+    def __init__(
+        self,
+        query: str | None = None,
+        *,
+        left: Self | None = None,
+        operator: RedisearchFilterOperator | None = None,
+        right: Self | None = None,
+    ):
+        """
+        Initialization
+        """
+        self._query: str | None = query
+        """Query string"""
+
+        self._left: Self | None = left
+        """Left operand"""
+
+        self._operator: RedisearchFilterOperator | None = operator
+        """Logical operator"""
+
+        self._right: Self | None = right
+        """Right operand"""
+
+    def __and__(self, other: Self) -> Self:
+        """
+        AND operator for concatenation
+        """
+        return type(self)(
+            left=self,
+            operator=RedisearchFilterOperator.AND,
+            right=other,
+        )
+
+    def __or__(self, other: Self) -> Self:
+        """
+        OR operator for concatenation
+        """
+        return type(self)(
+            left=self,
+            operator=RedisearchFilterOperator.OR,
+            right=other,
+        )
+
+    def __str__(self) -> str:
+        """
+        Stringification
+        """
+        if self._query:
+            return self._query
+
+        if self._left and self._operator and self._right:
+            operator = " | " if self._operator == RedisearchFilterOperator.OR else " "
+
+            left, right = str(self._left), str(self._right)
+
+            if (left == right) and (right == "*"):
+                return "*"
+
+            if (left == "*") and (right != "*"):
+                return right
+
+            if (left != "*") and (right == "*"):
+                return left
+
+            return f"({left}{operator}{right})"
+
+        raise ValueError("Improperly initialized RedisearchFilter")

kiarina/lib/redisearch/filter/_registry.py

@@ -0,0 +1,153 @@
+from ..schema import RedisearchSchema
+from ._field.numeric import Numeric
+from ._field.tag import Tag
+from ._field.text import Text
+from ._model import RedisearchFilter
+from ._types import RedisearchFilterConditions
+
+
+def create_redisearch_filter(
+    *,
+    filter: RedisearchFilter | RedisearchFilterConditions,
+    schema: RedisearchSchema,
+) -> RedisearchFilter | None:
+    """
+    Create a RedisearchFilter from a list of conditions.
+
+    Each condition is combined using the & operator.
+
+    Examples:
+        >>> create_redisearch_filter(
+        ...     schema=schema,
+        ...     conditions=[
+        ...         ["color", "in", ["blue", "red"]],
+        ...         ["price", "<", 1000],
+        ...         ["title", "like", "*hello*"]
+        ...     ],
+        ... )
+    """
+    if isinstance(filter, RedisearchFilter):
+        return filter
+
+    conditions = filter
+
+    filters: list[RedisearchFilter] = []
+
+    for condition in conditions:
+        if len(condition) != 3:
+            raise ValueError("Each condition must have exactly 3 elements")
+
+        field_name = condition[0]
+
+        if not isinstance(field_name, str):
+            raise ValueError("Field name must be a string")
+
+        field = schema.get_field(field_name)
+
+        if field is None:
+            raise ValueError(f"Field '{field_name}' not found in schema")
+
+        if field.type == "tag":
+            filters.append(_create_tag_filter(condition))
+        elif field.type == "numeric":
+            filters.append(_create_numeric_filter(condition))
+        elif field.type == "text":
+            filters.append(_create_text_filter(condition))
+        else:
+            raise ValueError(
+                f"Unsupported field type: {field.type}, field: {field_name}"
+            )
+
+    if not filters:
+        return None
+
+    return _combine_filters(filters)
+
+
+def _create_tag_filter(condition: list[str | tuple[str]]) -> RedisearchFilter:
+    """
+    Create a Redisearch tag filter.
+    """
+    field, operator, values = condition
+
+    tag_field = Tag(str(field))
+
+    result: RedisearchFilter
+
+    if operator == "==" or operator == "=":
+        result = tag_field == values
+    elif operator == "!=":
+        result = tag_field != values
+    elif operator == "in":
+        result = tag_field == values
+    elif operator == "not in":
+        result = tag_field != values
+    else:
+        raise ValueError(f"Invalid operator: {operator}")
+
+    return result
+
+
+def _create_numeric_filter(condition: list[str | int | float]) -> RedisearchFilter:
+    """
+    Create a Redisearch numeric filter.
+    """
+    field, operator, value = condition
+
+    if isinstance(value, str):
+        raise ValueError("Numeric value must be int or float")
+
+    numeric_field = Numeric(str(field))
+
+    result: RedisearchFilter
+
+    if operator == "==" or operator == "=":
+        result = numeric_field == value
+    elif operator == "!=":
+        result = numeric_field != value
+    elif operator == ">":
+        result = numeric_field > value
+    elif operator == "<":
+        result = numeric_field < value
+    elif operator == ">=":
+        result = numeric_field >= value
+    elif operator == "<=":
+        result = numeric_field <= value
+    else:
+        raise ValueError(f"Invalid operator: {operator}")
+
+    return result
+
+
+def _create_text_filter(condition: list[str]) -> RedisearchFilter:
+    """
+    Create a Redisearch text filter.
+    """
+    field, operator, value = condition
+
+    text_field = Text(str(field))
+    value = str(value)
+    result: RedisearchFilter
+
+    if operator == "==" or operator == "=":
+        result = text_field == value
+    elif operator == "!=":
+        result = text_field != value
+    elif operator == "%" or operator == "like":
+        result = text_field % value
+    else:
+        raise ValueError(f"Invalid operator: {operator}")
+
+    return result
+
+
+def _combine_filters(filters: list[RedisearchFilter]) -> RedisearchFilter:
+    """
+    Combine multiple RedisearchFilter instances using the & operator.
+    """
+    combined = filters[0]
+
+    for filter in filters[1:]:
+        combined = combined & filter
+
+    return combined