nuql 0.0.1__py3-none-any.whl

nuql/api/query/condition.py

@@ -0,0 +1,157 @@
+__all__ = ['Condition']
+
+from typing import Dict, Any, Literal, Optional
+
+from boto3.dynamodb.conditions import ComparisonCondition, Attr, ConditionExpressionBuilder
+
+import nuql
+from nuql import resources, types
+from . import condition_builder
+
+
+class Condition:
+    def __init__(
+            self,
+            table: 'resources.Table',
+            condition: Dict[str, Any] | None = None,
+            condition_type: Literal['FilterExpression', 'ConditionExpression'] = 'FilterExpression',
+    ) -> None:
+        """
+        Base condition builder helper to resolve queries.
+
+        :arg table: Table instance.
+        :param condition: Condition dict.
+        :param condition_type: Condition type (FilterExpression or ConditionExpression).
+        """
+
+        self.table = table
+        self.variables = condition['variables'] if condition and condition.get('variables') else {}
+        self.type = condition_type
+        self.condition = None
+        self.validator = resources.Validator()
+
+        if condition:
+            query = condition_builder.build_query(condition['where'])
+            self.condition = self.resolve(query['condition'])
+
+    @property
+    def resource_args(self) -> Dict[str, Any]:
+        """Boto3 resource args for the condition."""
+        args = {}
+        if self.condition:
+            args[self.type] = self.condition
+        return args
+
+    @property
+    def client_args(self) -> Dict[str, Any]:
+        """Boto3 client args for the condition."""
+        if not self.condition:
+            return {}
+
+        builder = ConditionExpressionBuilder()
+        expression = builder.build_expression(self.condition, is_key_condition=False)
+
+        expression_string = getattr(expression, 'condition_expression')
+        attribute_name_placeholders = getattr(expression, 'attribute_name_placeholders')
+        attribute_value_placeholders = getattr(expression, 'attribute_value_placeholders')
+
+        return {
+            'ConditionExpression': expression_string,
+            'ExpressionAttributeNames': attribute_name_placeholders,
+            'ExpressionAttributeValues': attribute_value_placeholders,
+        }
+
+    def append(self, condition: str) -> None:
+        """
+        Append a condition to the current condition.
+
+        :arg condition: Condition string.
+        """
+        if isinstance(condition, str):
+            condition = condition_builder.build_query(condition)['condition']
+        condition = self.resolve(condition)
+        if self.condition:
+            self.condition &= condition
+        else:
+            self.condition = condition
+
+    def resolve(self, part: Any) -> ComparisonCondition:
+        """
+        Recursively resolves condition parts.
+
+        :arg part: Part to resolve.
+        :return: ComparisonCondition instance.
+        """
+        # Direct condition/function handling
+        if isinstance(part, dict) and part['type'] in ['condition', 'function']:
+            attr = Attr(part['field'])
+            field_name = part['field']
+            field = self.table.fields.get(field_name)
+
+            is_key = field_name in self.table.indexes.index_keys
+            is_projected_to_key = any([x in self.table.indexes.index_keys for x in field.projected_from])
+
+            # Validate that keys cannot be present in the query
+            if (is_key or is_projected_to_key) and self.type == 'FilterExpression':
+                raise nuql.NuqlError(
+                    code='ConditionError',
+                    message=f'Field \'{field_name}\' cannot be used in a condition query'
+                )
+
+            # Functions are called differently
+            if part['type'] == 'function':
+                expression = getattr(attr, part['function'])()
+
+            # Handle basic conditions
+            else:
+                if not field:
+                    raise nuql.NuqlError(
+                        code='ConditionError',
+                        message=f'Field \'{field_name}\' is not defined in the schema'
+                    )
+
+                # Variables provided outside of the query string
+                if part['value_type'] == 'variable':
+                    if part['variable'] not in self.variables:
+                        raise nuql.NuqlError(
+                            code='ConditionError',
+                            message=f'Variable \'{part["variable"]}\' is not defined in the condition'
+                        )
+                    value = self.variables[part['variable']]
+
+                # Rudimentary values passed in the query string
+                else:
+                    value = part['value']
+
+                # Value is serialised for a query
+                expression = getattr(attr, part['operand'])(field(value, action='query', validator=self.validator))
+
+            return expression
+
+        # Handle grouped conditions
+        elif isinstance(part, dict) and part['type'] == 'parentheses':
+            condition = None
+            last_operator = None
+
+            for item in part['conditions']:
+                # Logical operator is stored outside of the loop so that it is used
+                if isinstance(item, dict) and item['type'] == 'logical_operator':
+                    last_operator = item['operator']
+
+                else:
+                    expression = self.resolve(item)
+
+                    if last_operator is None:
+                        condition = expression
+                    elif last_operator == 'and':
+                        condition &= expression
+                    elif last_operator == 'or':
+                        condition |= expression
+
+            return condition
+
+        raise nuql.NuqlError(
+            code='ConditionParsingError',
+            message='Unresolvable condition part was provided',
+            part=part
+        )

nuql/api/query/condition_builder.py

@@ -0,0 +1,211 @@
+__all__ = ['build_query']
+
+from typing import Dict, Any, List
+
+from pyparsing import Word, alphas, alphanums, Regex, Group, Forward, oneOf, infixNotation, opAssoc, QuotedString, \
+    pyparsing_common, ParseException
+
+import nuql
+
+
+ATTR_OPERATORS = {
+    # Equals
+    'equals': 'eq',
+    '=': 'eq',
+    '==': 'eq',
+    'eq': 'eq',
+    'is': 'eq',
+
+    # Not equals
+    'not_equals': 'ne',
+    '!=': 'ne',
+    '<>': 'ne',
+    'ne': 'ne',
+    'is_not': 'ne',
+
+    # Less than
+    'less_than': 'lt',
+    '<': 'lt',
+    'lt': 'lt',
+
+    # Less than or equal to
+    'less_than_or_equals': 'lte',
+    'less_than_equals': 'lte',
+    '<=': 'lte',
+    'lte': 'lte',
+
+    # Greater than
+    'greater_than': 'gt',
+    '>': 'gt',
+    'gt': 'gt',
+
+    # Greater than or equal to
+    'greater_than_or_equals': 'gte',
+    'greater_than_equals': 'gte',
+    '>=': 'gte',
+    'gte': 'gte',
+
+    # Special
+    'begins_with': 'begins_with',
+    'between': 'between',
+    'attribute_type': 'attribute_type',
+    'contains': 'contains',
+    'match': 'contains',
+    'attribute_exists': 'exists',
+    'attribute_not_exists': 'not_exists',
+    'is_in': 'is_in',
+    'in': 'is_in',
+}
+
+
+field = Word(alphas + '_' + alphanums + '.').set_results_name('field')
+
+# Operands and functions
+operand = oneOf('''
+    = == equals eq is
+    != <> not_equals ne is_not
+    < less_than lt
+    <= less_than_equals less_than_or_equals lte
+    > greater_than gt
+    >= greater_than_equals greater_than_or_equals gte
+    contains match
+    begins_with
+    between
+    is_in in
+''', caseless=True).set_results_name('operand')
+func = oneOf('attribute_exists attribute_not_exists', caseless=True).set_results_name('func')
+
+# Value parsing
+variable = Regex(r'\$\{[^}]*\}').set_results_name('variable')
+quoted_string = (
+        QuotedString('"', unquote_results=False).set_results_name('string') |
+        QuotedString("'", unquote_results=False).set_results_name('string')
+)
+integer = pyparsing_common.integer.set_results_name('integer')
+number = pyparsing_common.number.set_results_name('number')
+boolean = oneOf('true false', caseless=True)
+value = variable | quoted_string | number | integer | boolean
+
+# Equation groups
+condition_group = Group(field + operand + value)
+function_group = Group(func + '(' + field + ')')
+
+expression = Forward()
+expression <<= infixNotation(
+    (condition_group | function_group), [
+        (oneOf('and', caseless=True), 2, opAssoc.LEFT),
+        (oneOf('or', caseless=True), 2, opAssoc.LEFT),
+    ]
+)
+
+
+def build_query(query: str | None) -> Dict[str, Any]:
+    """
+    Build query dict from string.
+
+    :arg query: Query string.
+    :return: Query dict payload.
+    """
+    try:
+        parsed = expression.parse_string(query)[0].as_list()
+    except ParseException as e:
+        raise nuql.NuqlError(
+            code='ConditionParsingError',
+            message=f'Unable to parse condition: {e}',
+        )
+
+    variables = []
+
+    def recursive_unpack(part: Any, captured_variables: List[str]) -> Dict[str, Any]:
+        """
+        Recursively unpacks condition parts.
+
+        :arg part: Condition part.
+        :arg captured_variables: List of variables captured in query.
+        :return: Dict representation of condition.
+        """
+        if is_condition(part):
+            value_is_variable = isinstance(part[2], str) and part[2].startswith('${') and part[2].endswith('}')
+            if value_is_variable:
+                captured_variables.append(part[2].replace('${', '').replace('}', ''))
+            return {
+                'type': 'condition',
+                'field': part[0],
+                'operand': ATTR_OPERATORS[part[1].lower()],
+                **parse_value(part[2])
+            }
+
+        elif is_function(part):
+            return {
+                'type': 'function',
+                'field': part[2],
+                'function': ATTR_OPERATORS[part[0].lower()]
+            }
+
+        elif is_logical_operator(part):
+            return {'type': 'logical_operator', 'operator': part}
+
+        else:
+            return {
+                'type': 'parentheses',
+                'conditions': [recursive_unpack(item, captured_variables) for item in part]
+            }
+
+    result = recursive_unpack(parsed, variables)
+
+    return {'condition': result, 'variables': list(set(variables))}
+
+
+def is_condition(part: Any):
+    return isinstance(part, list) and all(isinstance(item, str) for item in part[:-1]) and len(part) == 3
+
+
+def is_function(part: Any):
+    return isinstance(part, list) and all(isinstance(item, str) for item in part) and len(part) == 4
+
+
+def is_logical_operator(part: Any):
+    return isinstance(part, str) and part in ['and', 'AND', 'or', 'OR']
+
+
+def parse_value(var: str) -> Dict[str, Any]:
+    """
+    Parses provided variable.
+
+    :arg var: Variable to parse.
+    :return: Condition result keys.
+    """
+    # Parse variable
+    try:
+        var = variable.parse_string(var)
+        return {'value_type': 'variable', 'variable': var.variable.replace('${', '').replace('}', '')}
+    except (ParseException, AttributeError):
+        pass
+
+    # Parse quoted string
+    try:
+        var = quoted_string.parse_string(var)
+        return {
+            'value_type': 'string',
+            'value': var.string.lstrip('"').rstrip('"')
+            if var.string.startswith('"')
+            else var.string.lstrip("'").rstrip("'")
+        }
+    except (ParseException, AttributeError):
+        pass
+
+    # Parse integer type
+    if isinstance(var, int):
+        return {'value_type': 'integer', 'value': var}
+
+    # Parse number
+    if isinstance(var, float):
+        return {'value_type': 'number', 'value': var}
+
+    if isinstance(var, str) and var.lower() == 'true':
+        return {'value_type': 'boolean', 'value': True}
+
+    if isinstance(var, str) and var.lower() == 'false':
+        return {'value_type': 'boolean', 'value': False}
+
+    raise nuql.NuqlError(code='ConditionParsingError', message=f'Unable to parse variable \'{var}\' in condition.')

nuql/api/query/key_condition.py

@@ -0,0 +1,200 @@
+__all__ = ['KeyCondition']
+
+from typing import Dict, Any
+
+from boto3.dynamodb.conditions import Key, ConditionExpressionBuilder
+
+import nuql
+from nuql import resources
+
+
+KEY_OPERANDS = {
+    # Equals
+    'equals': 'eq',
+    '=': 'eq',
+    '==': 'eq',
+    'eq': 'eq',
+
+    # Less than
+    'less_than': 'lt',
+    '<': 'lt',
+    'lt': 'lt',
+
+    # Less than or equal to
+    'less_than_or_equals': 'lte',
+    'less_than_equals': 'lte',
+    '<=': 'lte',
+    'lte': 'lte',
+
+    # Greater than
+    'greater_than': 'gt',
+    '>': 'gt',
+    'gt': 'gt',
+
+    # Greater than or equal to
+    'greater_than_or_equals': 'gte',
+    'greater_than_equals': 'gte',
+    '>=': 'gte',
+    'gte': 'gte',
+
+    # Special
+    'begins_with': 'begins_with',
+    'between': 'between',
+}
+
+
+class KeyCondition:
+    def __init__(self, table: 'resources.Table', condition: Dict[str, Any] | None = None, index_name: str = 'primary'):
+        """
+        DynamoDB key condition builder.
+
+        :arg table: Table instance.
+        :param condition: Condition dict.
+        :param index_name: Optional index name.
+        """
+        if not isinstance(condition, (dict, type(None))):
+            raise nuql.NuqlError(code='KeyConditionError', message='Key condition must be a dict or None.')
+
+        if not condition:
+            condition = {}
+
+        self.index_name = index_name
+
+        if index_name == 'primary':
+            self.index = table.indexes.primary
+        else:
+            self.index = table.indexes.get_index(index_name)
+
+        if self.index['hash'] not in condition:
+            condition[self.index['hash']] = None
+
+        parsed_conditions = {}
+
+        for key, value in condition.items():
+            # Validate that the key exists
+            if key not in table.fields:
+                raise nuql.NuqlError(code='KeyConditionError', message=f'Field \'{key}\' is not defined in the schema.')
+
+            field = table.fields[key]
+
+            is_hash_key = key == self.index['hash']
+            is_sort_key = key == self.index.get('sort')
+            projects_to_hash = self.index['hash'] in field.projected_from
+            projects_to_sort = self.index.get('sort') in field.projected_from
+
+            # Validate that the key is available on the index
+            if not any([is_hash_key, is_sort_key, projects_to_hash, projects_to_sort]):
+                raise nuql.NuqlError(
+                    code='KeyConditionError',
+                    message=f'Field \'{key}\' cannot be used in a key condition on \'{index_name}\' index '
+                            f'as it is not a hash/sort key and it doesn\'t project to the hash/sort key.'
+                )
+
+            operand, condition_value = self.extract_condition(key, value)
+
+            # Directly set the key field where not projected
+            if is_hash_key or is_sort_key:
+                parsed_conditions[key] = [operand, condition_value]
+
+            # Process projected field
+            else:
+                key_name = self.index['hash'] if is_hash_key else self.index['sort']
+
+                if key_name not in parsed_conditions:
+                    parsed_conditions[key_name] = ['eq', {}]
+
+                if parsed_conditions[key_name][0] != 'eq' and operand != 'eq':
+                    raise nuql.NuqlError(
+                        code='KeyConditionError',
+                        message=f'Multiple non-equals operators provided for the key \'{key_name}\' '
+                                'will result in an ambiguous key condition.'
+                    )
+
+                if operand != 'eq':
+                    parsed_conditions[key_name][0] = operand
+
+                parsed_conditions[key_name][1][key] = condition_value
+
+        self.condition = None
+        validator = resources.Validator()
+
+        # Generate key condition
+        for key, (operand, value) in parsed_conditions.items():
+            field = table.fields[key]
+            key_obj = Key(key)
+
+            if operand == 'between':
+                if len(value) != 2:
+                    raise nuql.NuqlError(
+                        code='KeyConditionError',
+                        message=f'Between operator requires exactly two values for the key \'{key}\'.'
+                    )
+                serialised_value = (field(value[0], 'query', validator), field(value[1], 'query', validator))
+                key_condition = getattr(key_obj, operand)(*serialised_value)
+            else:
+                serialised_value = field(value, 'query', validator)
+                key_condition = getattr(key_obj, operand)(serialised_value)
+
+            if self.condition is None:
+                self.condition = key_condition
+            else:
+                self.condition &= key_condition
+
+    @property
+    def resource_args(self) -> Dict[str, Any]:
+        """Query request args."""
+        if self.condition is None:
+            raise nuql.NuqlError(code='KeyConditionError', message='Key condition is empty.')
+
+        args: Dict[str, Any] = {'KeyConditionExpression': self.condition}
+        if self.index_name != 'primary':
+            args['IndexName'] = self.index_name
+
+        return args
+
+    @property
+    def client_args(self) -> Dict[str, Any]:
+        """Boto3 client args for the condition."""
+        if self.condition is None:
+            raise nuql.NuqlError(code='KeyConditionError', message='Key condition is empty.')
+
+        args = {}
+
+        if self.index_name != 'primary':
+            args['IndexName'] = self.index_name
+
+        builder = ConditionExpressionBuilder()
+        expression = builder.build_expression(self.condition, is_key_condition=True)
+
+        args['KeyConditionExpression'] = getattr(expression, 'condition_expression')
+        args['ExpressionAttributeNames'] = getattr(expression, 'attribute_name_placeholders')
+        args['ExpressionAttributeValues'] = getattr(expression, 'attribute_value_placeholders')
+
+        return args
+
+    @staticmethod
+    def extract_condition(key: str, value: Any) -> (str, Any):
+        """
+        Parses and extracts the operand and value from the condition.
+
+        :arg key: Condition key.
+        :arg value: Condition value or dict.
+        :return: Tuple containing the operand and value.
+        """
+        value_keys = list(value.keys()) if isinstance(value, dict) else []
+        if isinstance(value, dict) and all([x.lower() in KEY_OPERANDS for x in value.keys()]):
+            if len(value_keys) > 1:
+                raise nuql.NuqlError(
+                    code='KeyConditionError',
+                    message=f'Multiple operators provided for the key \'{key}\' (' + ', '.join(value_keys) + ').'
+                )
+
+            condition_dict = next(iter(value.items()))
+
+            operand = KEY_OPERANDS[condition_dict[0].lower()]
+            condition_value = condition_dict[1]
+        else:
+            operand = 'eq'
+            condition_value = value
+
+        return operand, condition_value