criteria-pattern 0.1.1__py3-none-any.whl

criteria_pattern/__init__.py

@@ -0,0 +1,11 @@
+__version__ = '0.1.1'
+
+from .models import Criteria, Filter, FilterOperator, Order, OrderDirection
+
+__all__ = (
+    'Criteria',
+    'Filter',
+    'FilterOperator',
+    'Order',
+    'OrderDirection',
+)

criteria_pattern/converter/__init__.py

@@ -0,0 +1,3 @@
+from .sql_converter import SqlConverter
+
+__all__ = ('SqlConverter',)

criteria_pattern/converter/sql_converter.py

@@ -0,0 +1,387 @@
+"""
+Raw SQL converter module.
+"""
+
+from collections.abc import Mapping, Sequence
+from typing import Any, assert_never
+
+from criteria_pattern import Criteria, FilterOperator, OrderDirection
+from criteria_pattern.exceptions import InvalidColumnError, InvalidTableError
+from criteria_pattern.models.criteria import AndCriteria, NotCriteria, OrCriteria
+
+
+class SqlConverter:
+    """
+    Raw SQL converter.
+
+    Example:
+    ```python
+    from criteria_pattern import Criteria, Filter, FilterOperator
+    from criteria_pattern.converter import SqlConverter
+
+    is_adult = Criteria(filters=[Filter('age', FilterOperator.GREATER_OR_EQUAL, 18)])
+    email_is_gmail = Criteria(filters=[Filter('email', FilterOperator.ENDS_WITH, '@gmail.com')])
+    email_is_yahoo = Criteria(filters=[Filter('email', FilterOperator.ENDS_WITH, '@yahoo.com')])
+
+    query, parameters = SqlConverter.convert(criteria=is_adult & (email_is_gmail | email_is_yahoo), table='user')
+    print(query)
+    print(parameters)
+    # >>> SELECT * FROM user WHERE (age >= %(parameter_0)s AND (email LIKE '%%' || %(parameter_1)s OR email LIKE '%%' || %(parameter_2)s));
+    # >>> {'parameter_0': 18, 'parameter_1': '@gmail.com', 'parameter_2': '@yahoo.com'}
+    ```
+    """  # noqa: E501
+
+    @classmethod
+    def convert(
+        cls,
+        criteria: Criteria,
+        table: str,
+        columns: Sequence[str] | None = None,
+        columns_mapping: Mapping[str, str] | None = None,
+        check_table_injection: bool = False,
+        check_column_injection: bool = False,
+        check_criteria_injection: bool = False,
+        valid_tables: Sequence[str] | None = None,
+        valid_columns: Sequence[str] | None = None,
+    ) -> tuple[str, dict[str, Any]]:
+        """
+        Convert the Criteria object to a raw SQL query.
+
+        Args:
+            criteria (Criteria): Criteria to convert.
+            table (str): Name of the table to query.
+            columns (Sequence[str], optional): Columns of the table to select. Default to *. Default to *.
+            columns_mapping (Mapping[str, str], optional): Mapping of column names to aliases. Default to empty dict.
+            check_criteria_injection (bool, optional): Raise an error if the criteria field is not in the list of valid
+            columns. Default to False.
+            check_table_injection (bool, optional): Raise an error if the table is not in the list of valid tables.
+            Default to False.
+            check_column_injection (bool, optional): Raise an error if the column is not in the list of valid columns.
+            Default to False.
+            valid_tables (Sequence[str], optional): List of valid tables to query. Default to empty list.
+            valid_columns (Sequence[str], optional): List of valid columns to select. Default to empty list.
+
+        Raises:
+            InvalidTableError: If the table is not in the list of valid tables (only if check_table_injection=True).
+            InvalidColumnError: If the column is not in the list of valid columns (only if check_column_injection=True).
+
+        Returns:
+            tuple[str, dict[str, Any]]: The raw SQL query string and the query parameters.
+
+        Example:
+        ```python
+        from criteria_pattern import Criteria, Filter, FilterOperator
+        from criteria_pattern.converter import SqlConverter
+
+        is_adult = Criteria(filters=[Filter('age', FilterOperator.GREATER_OR_EQUAL, 18)])
+        email_is_gmail = Criteria(filters=[Filter('email', FilterOperator.ENDS_WITH, '@gmail.com')])
+        email_is_yahoo = Criteria(filters=[Filter('email', FilterOperator.ENDS_WITH, '@yahoo.com')])
+
+        query, parameters = SqlConverter.convert(criteria=is_adult & (email_is_gmail | email_is_yahoo), table='user')
+        print(query)
+        print(parameters)
+        # >>> SELECT * FROM user WHERE (age >= %(parameter_0)s AND (email LIKE '%%' || %(parameter_1)s OR email LIKE '%%' || %(parameter_2)s));
+        # >>> {'parameter_0': 18, 'parameter_1': '@gmail.com', 'parameter_2': '@yahoo.com'}
+        ```
+        """  # noqa: E501
+        columns = columns or ['*']
+        columns_mapping = columns_mapping or {}
+        valid_tables = valid_tables or []
+        valid_columns = valid_columns or []
+
+        if check_table_injection:
+            cls._validate_table(table=table, valid_tables=valid_tables)
+
+        if check_column_injection:
+            cls._validate_columns(columns=columns, columns_mapping=columns_mapping, valid_columns=valid_columns)
+
+        if check_criteria_injection:
+            cls._validate_criteria(criteria=criteria, valid_columns=valid_columns)
+
+        query = f'SELECT {", ".join(columns)} FROM {table}'  # noqa: S608  # nosec
+        parameters: dict[str, Any] = {}
+
+        if criteria.has_filters():
+            where_clause, parameters = cls._process_filters(criteria=criteria, columns_mapping=columns_mapping)
+            query += f' WHERE {where_clause}'
+
+        if criteria.has_orders():
+            order_clause = cls._process_orders(criteria=criteria, columns_mapping=columns_mapping)
+            query += f' ORDER BY {order_clause}'
+
+        return f'{query};', parameters
+
+    @classmethod
+    def _validate_table(cls, table: str, valid_tables: Sequence[str]) -> None:
+        """
+        Validate the table name to prevent SQL injection.
+
+        Args:
+            table (str): Name of the table to query.
+            valid_tables (Sequence[str]): List of valid tables to query.
+
+        Raises:
+            InvalidTableError: If the table is not in the list of valid tables.
+        """
+        if table not in valid_tables:
+            raise InvalidTableError(table=table, valid_tables=valid_tables)
+
+    @classmethod
+    def _validate_columns(
+        cls,
+        columns: Sequence[str],
+        columns_mapping: Mapping[str, str],
+        valid_columns: Sequence[str],
+    ) -> None:
+        """
+        Validate the column names to prevent SQL injection.
+
+        Args:
+            columns (Sequence[str]): Columns of the table to select.
+            columns_mapping (Mapping[str, str]): Mapping of column names to aliases.
+            valid_columns (Sequence[str]): List of valid columns to select.
+
+        Raises:
+            InvalidColumnError: If the column is not in the list of valid columns.
+        """
+        for column in columns:
+            if column not in valid_columns:
+                raise InvalidColumnError(column=column, valid_columns=valid_columns)
+
+        for column in columns_mapping.values():
+            if column not in valid_columns:
+                raise InvalidColumnError(column=column, valid_columns=valid_columns)
+
+    @classmethod
+    def _validate_criteria(cls, criteria: Criteria, valid_columns: Sequence[str]) -> None:
+        """
+        Validate the Criteria object to prevent SQL injection.
+
+        Args:
+            criteria (Criteria): Criteria to validate.
+            valid_columns (Sequence[str]): List of valid columns to select.
+
+        Raises:
+            InvalidColumnError: If the column is not in the list of valid columns.
+        """
+        for filter in criteria.filters:
+            if filter.field not in valid_columns:
+                raise InvalidColumnError(column=filter.field, valid_columns=valid_columns)
+
+        for order in criteria.orders:
+            if order.field not in valid_columns:
+                raise InvalidColumnError(column=order.field, valid_columns=valid_columns)
+
+    @classmethod
+    def _process_filters(cls, criteria: Criteria, columns_mapping: Mapping[str, str]) -> tuple[str, dict[str, Any]]:
+        """
+        Process the Criteria object to return an SQL WHERE clause.
+
+        Args:
+            criteria (Criteria): Criteria to process.
+            columns_mapping (Mapping[str, str]): Mapping of column names to aliases.
+
+        Returns:
+            tuple[str, dict[str, Any]]: Processed filter string for SQL WHERE clause and parameters for the SQL query.
+        """
+        return cls._process_filters_recursive(criteria=criteria, columns_mapping=columns_mapping)
+
+    @classmethod
+    def _process_filters_recursive(  # noqa: C901
+        cls,
+        criteria: Criteria,
+        columns_mapping: Mapping[str, str],
+        parameters_counter: int = 0,
+    ) -> tuple[str, dict[str, Any]]:
+        """
+        Process the Criteria object to return an SQL WHERE clause.
+
+        Args:
+            criteria (Criteria): Criteria to process.
+            columns_mapping (Mapping[str, str]): Mapping of column names to aliases.
+            parameters_counter (int): Counter for parameter names to ensure uniqueness.
+
+        Returns:
+            tuple[str, dict[str, Any]]: Processed filter string for SQL WHERE clause and parameters for the SQL query.
+        """
+        filters = ''
+        parameters: dict[str, Any] = {}
+
+        if isinstance(criteria, AndCriteria):
+            left_conditions, left_parameters = cls._process_filters_recursive(
+                criteria=criteria.left,
+                columns_mapping=columns_mapping,
+                parameters_counter=parameters_counter,
+            )
+            parameters_counter += len(left_parameters)
+            parameters.update(left_parameters)
+
+            right_conditions, right_parameters = cls._process_filters_recursive(
+                criteria=criteria.right,
+                columns_mapping=columns_mapping,
+                parameters_counter=parameters_counter,
+            )
+            parameters_counter += len(right_parameters)
+            parameters.update(right_parameters)
+
+            filters += f'({left_conditions} AND {right_conditions})'
+
+            return filters, parameters
+
+        if isinstance(criteria, OrCriteria):
+            left_conditions, left_parameters = cls._process_filters_recursive(
+                criteria=criteria.left,
+                columns_mapping=columns_mapping,
+                parameters_counter=parameters_counter,
+            )
+            parameters_counter += len(left_parameters)
+            parameters.update(left_parameters)
+
+            right_conditions, right_parameters = cls._process_filters_recursive(
+                criteria=criteria.right,
+                columns_mapping=columns_mapping,
+                parameters_counter=parameters_counter,
+            )
+            parameters_counter += len(right_parameters)
+            parameters.update(right_parameters)
+
+            filters += f'({left_conditions} OR {right_conditions})'
+
+            return filters, parameters
+
+        if isinstance(criteria, NotCriteria):
+            not_conditions, not_parameters = cls._process_filters_recursive(
+                criteria=criteria.criteria,
+                columns_mapping=columns_mapping,
+                parameters_counter=parameters_counter,
+            )
+            parameters_counter += len(not_parameters)
+            parameters.update(not_parameters)
+
+            filters += f'NOT ({not_conditions})'
+
+            return filters, parameters
+
+        for filter in criteria.filters:
+            filter_field = columns_mapping.get(filter.field, filter.field)
+            parameter_name = f'parameter_{parameters_counter}'
+            parameters[parameter_name] = filter.value
+            placeholder = f'%({parameter_name})s'
+            parameters_counter += 1
+
+            match filter.operator:
+                case FilterOperator.EQUAL:
+                    filters += f'{filter_field} = {placeholder}'
+
+                case FilterOperator.NOT_EQUAL:
+                    filters += f'{filter_field} != {placeholder}'
+
+                case FilterOperator.GREATER:
+                    filters += f'{filter_field} > {placeholder}'
+
+                case FilterOperator.GREATER_OR_EQUAL:
+                    filters += f'{filter_field} >= {placeholder}'
+
+                case FilterOperator.LESS:
+                    filters += f'{filter_field} < {placeholder}'
+
+                case FilterOperator.LESS_OR_EQUAL:
+                    filters += f'{filter_field} <= {placeholder}'
+
+                case FilterOperator.LIKE:
+                    filters += f'{filter_field} LIKE {placeholder}'
+
+                case FilterOperator.NOT_LIKE:
+                    filters += f'{filter_field} NOT LIKE {placeholder}'
+
+                case FilterOperator.CONTAINS:
+                    filters += f"{filter_field} LIKE '%%' || {placeholder} || '%%'"
+
+                case FilterOperator.NOT_CONTAINS:
+                    filters += f"{filter_field} NOT LIKE '%%' || {placeholder} || '%%'"
+
+                case FilterOperator.STARTS_WITH:
+                    filters += f"{filter_field} LIKE {placeholder} || '%%'"
+
+                case FilterOperator.NOT_STARTS_WITH:
+                    filters += f"{filter_field} NOT LIKE {placeholder} || '%%'"
+
+                case FilterOperator.ENDS_WITH:
+                    filters += f"{filter_field} LIKE '%%' || {placeholder}"
+
+                case FilterOperator.NOT_ENDS_WITH:
+                    filters += f"{filter_field} NOT LIKE '%%' || {placeholder}"
+
+                case FilterOperator.BETWEEN:
+                    parameters.pop(parameter_name)
+                    parameters_counter -= 1
+
+                    start_parameter_name = f'parameter_{parameters_counter}'
+                    end_parameter_name = f'parameter_{parameters_counter + 1}'
+                    parameters[start_parameter_name] = filter.value[0]
+                    parameters[end_parameter_name] = filter.value[1]
+                    start_placeholder = f'%({start_parameter_name})s'
+                    end_placeholder = f'%({end_parameter_name})s'
+                    parameters_counter += 2
+
+                    filters += f'{filter_field} BETWEEN {start_placeholder} AND {end_placeholder}'
+
+                case FilterOperator.NOT_BETWEEN:
+                    parameters.pop(parameter_name)
+                    parameters_counter -= 1
+
+                    start_parameter_name = f'parameter_{parameters_counter}'
+                    end_parameter_name = f'parameter_{parameters_counter + 1}'
+                    parameters[start_parameter_name] = filter.value[0]
+                    parameters[end_parameter_name] = filter.value[1]
+                    start_placeholder = f'%({start_parameter_name})s'
+                    end_placeholder = f'%({end_parameter_name})s'
+                    parameters_counter += 2
+
+                    filters += f'{filter_field} NOT BETWEEN {start_placeholder} AND {end_placeholder}'
+
+                case FilterOperator.IS_NULL:
+                    parameters.pop(parameter_name)
+                    parameters_counter -= 1
+
+                    filters += f'{filter_field} IS NULL'
+
+                case FilterOperator.IS_NOT_NULL:
+                    parameters.pop(parameter_name)
+                    parameters_counter -= 1
+
+                    filters += f'{filter_field} IS NOT NULL'
+
+                case _:  # pragma: no cover
+                    assert_never(filter.operator)
+
+        return filters, parameters
+
+    @classmethod
+    def _process_orders(cls, criteria: Criteria, columns_mapping: Mapping[str, str]) -> str:
+        """
+        Process the Criteria object to return an SQL ORDER BY clause.
+
+        Args:
+            criteria (Criteria): Criteria to process.
+            columns_mapping (Mapping[str, str]): Mapping of column names to aliases.
+
+        Returns:
+            str: Processed order string for SQL ORDER BY clause.
+        """
+        orders = ''
+
+        for order in criteria.orders:
+            order_field = columns_mapping.get(order.field, order.field)
+
+            match order.direction:
+                case OrderDirection.ASC:
+                    orders += f'{order_field} ASC, '
+
+                case OrderDirection.DESC:
+                    orders += f'{order_field} DESC, '
+
+                case _:  # pragma: no cover
+                    assert_never(order.direction)
+
+        return orders.rstrip(', ')

criteria_pattern/exceptions/__init__.py

@@ -0,0 +1,9 @@
+from .invalid_column_error import InvalidColumnError
+from .invalid_table_error import InvalidTableError
+from .sql_converter_error import SqlConverterError
+
+__all__ = (
+    'InvalidColumnError',
+    'InvalidTableError',
+    'SqlConverterError',
+)

criteria_pattern/exceptions/invalid_column_error.py

@@ -0,0 +1,53 @@
+"""
+Invalid column error exception.
+"""
+
+from collections.abc import Sequence
+
+from .sql_converter_error import SqlConverterError
+
+
+class InvalidColumnError(SqlConverterError):
+    """
+    Exception raised when an invalid column is specified in a SQL operation.
+
+    This exception is used to indicate that a column name provided by the user is not among the allowed valid columns,
+    helping to prevent SQL injection attacks and ensuring data integrity.
+    """
+
+    __column: str
+    __valid_columns: set[str]
+
+    def __init__(self, column: str, valid_columns: Sequence[str]) -> None:
+        """
+        Initialize the InvalidColumnError with the specified column and valid columns.
+
+        Args:
+            column (str): The name of the invalid column that caused the error.
+            valid_columns (Sequence[str]): A sequence of valid column names to reference.
+        """
+        self.__column = column
+        self.__valid_columns = set(valid_columns)
+
+        message = f'Invalid column specified: <<<{column}>>>. Valid columns are: <<<{", ".join(valid_columns)}>>>.'
+        super().__init__(message)
+
+    @property
+    def column(self) -> str:
+        """
+        Get the name of the invalid column that caused the error.
+
+        Returns:
+            str: The name of the column that was invalid.
+        """
+        return self.__column  # pragma: no cover
+
+    @property
+    def valid_columns(self) -> set[str]:
+        """
+        Get the list of valid columns that can be referenced.
+
+        Returns:
+            set[str]: A set of valid column names.
+        """
+        return self.__valid_columns  # pragma: no cover

criteria_pattern/exceptions/invalid_table_error.py

@@ -0,0 +1,53 @@
+"""
+Invalid table error exception.
+"""
+
+from collections.abc import Sequence
+
+from .sql_converter_error import SqlConverterError
+
+
+class InvalidTableError(SqlConverterError):
+    """
+    Exception raised when an invalid table is specified in a SQL operation.
+
+    This exception is used to indicate that a table name provided by the user is not among the allowed valid tables,
+    helping to prevent SQL injection attacks.
+    """
+
+    __table: str
+    __valid_tables: set[str]
+
+    def __init__(self, table: str, valid_tables: Sequence[str]) -> None:
+        """
+        Initialize the InvalidTableError with the specified table and valid tables.
+
+        Args:
+            table (str): The name of the invalid table that caused the error.
+            valid_tables (Sequence[str]): A sequence of valid table names to reference.
+        """
+        self.__table = table
+        self.__valid_tables = set(valid_tables)
+
+        message = f'Invalid table specified: <<<{table}>>>. Valid tables are: <<<{", ".join(valid_tables)}>>>.'
+        super().__init__(message)
+
+    @property
+    def table(self) -> str:
+        """
+        Get the name of the invalid table that caused the error.
+
+        Returns:
+            str: The name of the table that was invalid.
+        """
+        return self.__table  # pragma: no cover
+
+    @property
+    def valid_tables(self) -> set[str]:
+        """
+        Get the list of valid tables that can be referenced.
+
+        Returns:
+            set[str]: A set of valid table names.
+        """
+        return self.__valid_tables  # pragma: no cover

criteria_pattern/exceptions/sql_converter_error.py

@@ -0,0 +1,26 @@
+"""
+SQL converter base exception.
+"""
+
+
+class SqlConverterError(Exception):
+    """
+    SQL converter base exception.
+    """
+
+    __message: str
+
+    def __init__(self, message: str) -> None:
+        """
+        SQL converter base exception constructor.
+        """
+        self.__message = message
+
+        super().__init__(message)
+
+    @property
+    def message(self) -> str:
+        """
+        Get the exception message.
+        """
+        return self.__message  # pragma: no cover

criteria_pattern/models/__init__.py

@@ -0,0 +1,13 @@
+from .criteria import Criteria
+from .filter import Filter
+from .filter_operator import FilterOperator
+from .order import Order
+from .order_direction import OrderDirection
+
+__all__ = (
+    'Criteria',
+    'Filter',
+    'FilterOperator',
+    'Order',
+    'OrderDirection',
+)