nuql 0.0.1__py3-none-any.whl

nuql/api/query/query.py

@@ -0,0 +1,166 @@
+__all__ = ['Query']
+
+from typing import Any, Dict, Optional
+
+from botocore.exceptions import ClientError
+
+import nuql
+from nuql import types, api, resources
+
+
+class Query(api.Boto3Adapter):
+    def prepare_client_args(
+            self,
+            key_condition: Dict[str, Any] | None = None,
+            condition: Dict[str, Any] | None = None,
+            index_name: str = 'primary',
+            limit: int | None = None,
+            scan_index_forward: bool = True,
+            exclusive_start_key: Dict[str, Any] | None = None,
+            consistent_read: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Prepares args for performing a query against the table (client API).
+
+        :param key_condition: Key condition expression as a dict.
+        :param condition: Filter condition expression as a dict.
+        :param index_name: Index to perform query against.
+        :param limit: Number of items to retrieve.
+        :param scan_index_forward: Direction of scan.
+        :param exclusive_start_key: Exclusive start key.
+        :param consistent_read: Perform query as a consistent read.
+        :return: Query result.
+        """
+        # Key condition is parsed from a dict and validated
+        key_condition = api.KeyCondition(self.table, key_condition, index_name)
+
+        # Filter condition is parsed from a string and validated
+        resources.validate_condition_dict(condition)
+        filter_condition = api.Condition(
+            table=self.table,
+            condition=condition,
+            condition_type='FilterExpression'
+        )
+
+        return {
+            **key_condition.client_args,
+            **filter_condition.client_args,
+            'ScanIndexForward': scan_index_forward,
+            'ConsistentRead': consistent_read,
+        }
+
+    def prepare_args(
+            self,
+            key_condition: Dict[str, Any] | None = None,
+            condition: Dict[str, Any] | None = None,
+            index_name: str = 'primary',
+            limit: int | None = None,
+            scan_index_forward: bool = True,
+            exclusive_start_key: Dict[str, Any] | None = None,
+            consistent_read: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Prepares args for performing a query against the table (resource API).
+
+        :param key_condition: Key condition expression as a dict.
+        :param condition: Filter condition expression as a dict.
+        :param index_name: Index to perform query against.
+        :param limit: Number of items to retrieve.
+        :param scan_index_forward: Direction of scan.
+        :param exclusive_start_key: Exclusive start key.
+        :param consistent_read: Perform query as a consistent read.
+        :return: Query result.
+        """
+        # Key condition is parsed from a dict and validated
+        key_condition = api.KeyCondition(self.table, key_condition, index_name)
+
+        # Filter condition is parsed from a string and validated
+        resources.validate_condition_dict(condition)
+        filter_condition = api.Condition(
+            table=self.table,
+            condition=condition,
+            condition_type='FilterExpression'
+        )
+
+        return {
+            **key_condition.resource_args,
+            **filter_condition.resource_args,
+            'ScanIndexForward': scan_index_forward,
+            'ConsistentRead': consistent_read,
+        }
+
+    def invoke_sync(
+            self,
+            key_condition: Dict[str, Any] | None = None,
+            condition: Dict[str, Any] | None = None,
+            index_name: str = 'primary',
+            limit: int | None = None,
+            scan_index_forward: bool = True,
+            exclusive_start_key: Dict[str, Any] | None = None,
+            consistent_read: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Synchronously invokes a query against the table.
+
+        :param key_condition: Key condition expression as a dict.
+        :param condition: Filter condition expression as a dict.
+        :param index_name: Index to perform query against.
+        :param limit: Number of items to retrieve.
+        :param scan_index_forward: Direction of scan.
+        :param exclusive_start_key: Exclusive start key.
+        :param consistent_read: Perform query as a consistent read.
+        :return: Query result.
+        """
+        args = self.prepare_args(
+            key_condition=key_condition,
+            condition=condition,
+            index_name=index_name,
+            limit=limit,
+            scan_index_forward=scan_index_forward,
+            exclusive_start_key=exclusive_start_key,
+            consistent_read=consistent_read,
+        )
+
+        data = []
+        last_evaluated_key = exclusive_start_key
+        fulfilled = False
+
+        while not fulfilled:
+            # Subtract processed records from limit
+            if isinstance(limit, int):
+                args['Limit'] = limit - len(data)
+
+            # Break when limit is reached
+            if 'Limit' in args and args['Limit'] == 0:
+                break
+
+            # Pagination is achieved by using LEK as exclusive start key
+            if last_evaluated_key:
+                args['ExclusiveStartKey'] = last_evaluated_key
+
+            try:
+                response = self.connection.table.query(**args)
+            except ClientError as exc:
+                raise nuql.Boto3Error(exc, args)
+
+            data.extend(response.get('Items', []))
+            last_evaluated_key = response.get('LastEvaluatedKey')
+
+            if not last_evaluated_key:
+                fulfilled = True
+
+        # Deserialise the data
+        data = [self.table.serialiser.deserialise(item) for item in data]
+
+        output = {'items': [], 'last_evaluated_key': last_evaluated_key}
+
+        # Follow functionality on local/global indexes - batch gets all retrieved items
+        index = self.table.indexes.get_index(index_name) if index_name != 'primary' else self.table.indexes.primary
+
+        if 'follow' in index and index['follow'] is True:
+            batch_get = api.BatchGet(self.client, self.table)
+            output.update(batch_get.invoke_sync(data))
+        else:
+            output['items'] = data
+
+        return output

nuql/api/transaction.py

@@ -0,0 +1,145 @@
+__all__ = ['Transaction']
+
+from typing import Dict, Any
+
+from botocore.exceptions import ClientError
+
+import nuql
+from nuql import types, api, resources
+
+
+# Maximum number of actions in a transaction
+MAX_TRANSACTION_ACTIONS = 100
+
+
+class Transaction:
+    def __init__(self, client: 'nuql.Nuql') -> None:
+        """
+        Context manager for executing DynamoDB transactions.
+
+        :arg client: Nuql instance.
+        """
+        self.client = client
+
+        self._actions = []
+        self._started = False
+
+    def __enter__(self):
+        """Enter the context manager."""
+        self._actions = []
+        self._started = True
+
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Dispatch the transaction to DynamoDB."""
+        if not self._actions:
+            raise nuql.NuqlError(
+                code='TransactionError',
+                message='Transaction has no actions'
+            )
+
+        args = {'TransactItems': self._actions}
+
+        try:
+            self.client.connection.client.transact_write_items(**args)
+        except ClientError as exc:
+            raise nuql.Boto3Error(exc, args)
+
+        self._started = False
+        return False
+
+    def _validate(self) -> None:
+        """Validates that the context manager has been started and maximum has not been exceeded."""
+        if not self._started:
+            raise nuql.NuqlError(
+                code='TransactionError',
+                message='Transaction context manager has not been started'
+            )
+        if len(self._actions) > MAX_TRANSACTION_ACTIONS:
+            raise nuql.NuqlError(
+                code='TransactionError',
+                message=f'Maximum number of actions exceeded in transaction (limit {MAX_TRANSACTION_ACTIONS})'
+            )
+
+    def create(
+            self,
+            table: 'resources.Table',
+            data: Dict[str, Any],
+            condition: Dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Create a new item on a table as part of a transaction.
+
+        :arg table: Table instance.
+        :arg data: Data to create.
+        :param condition: Optional condition expression dict.
+        """
+        self._validate()
+
+        create = api.Create(self.client, table)
+        args = create.prepare_client_args(data=data, condition=condition)
+
+        self._actions.append({'Put': {'TableName': self.client.connection.table_name, **args}})
+
+    def update(
+            self,
+            table: 'resources.Table',
+            data: Dict[str, Any],
+            condition: Dict[str, Any] | None = None,
+            shallow: bool = False,
+    ) -> None:
+        """
+        Update an item on a table as part of a transaction.
+
+        :arg table: Table instance.
+        :arg data: Data to update.
+        :param condition: Optional condition expression dict.
+        :param shallow: Activates shallow update mode (so that whole nested items are updated at once).
+        """
+        self._validate()
+
+        update = api.UpdateItem(self.client, table)
+        args = update.prepare_client_args(data=data, condition=condition, shallow=shallow)
+
+        self._actions.append({'Update': {'TableName': self.client.connection.table_name, **args}})
+
+    def delete(
+            self,
+            table: 'resources.Table',
+            key: Dict[str, Any],
+            condition: Dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Delete an item on a table as part of a transaction.
+
+        :arg table: Table instance.
+        :arg key: Record key as a dict.
+        :param condition: Optional condition expression dict.
+        """
+        self._validate()
+
+        delete = api.Delete(self.client, table)
+        args = delete.prepare_client_args(key=key, condition=condition)
+
+        self._actions.append({'Delete': {'TableName': self.client.connection.table_name, **args}})
+
+    def condition_check(
+            self,
+            table: 'resources.Table',
+            key: Dict[str, Any],
+            condition: Dict[str, Any],
+    ) -> None:
+        """
+        Perform a condition check on an item as part of a transaction.
+
+        :arg table: Table instance.
+        :arg key: Record key as a dict.
+        :arg condition: Condition expression dict.
+        """
+        self._validate()
+
+        condition_check = api.ConditionCheck(self.client, table)
+        args = condition_check.prepare_client_args(key=key, condition=condition)
+
+        self._actions.append({'ConditionCheck': {'TableName': self.client.connection.table_name, **args}})

nuql/api/update/__init__.py

@@ -0,0 +1,3 @@
+from .utils import *
+from .expression_builder import *
+from .update_item import *

nuql/api/update/expression_builder.py

@@ -0,0 +1,33 @@
+__all__ = ['UpdateExpressionBuilder']
+
+from typing import Dict, Any
+
+from .utils import flatten_dict, UpdateKeys, UpdateValues
+
+
+class UpdateExpressionBuilder:
+    def __init__(self, data: Dict[str, Any], shallow: bool = False) -> None:
+        """
+        DynamoDB update expression builder.
+
+        :arg data: Serialised data to build expression from.
+        :param shallow: Activates shallow update mode (so that whole nested items are updated at once).
+        """
+        if not shallow:
+            data = flatten_dict(data)
+
+        self.keys = UpdateKeys()
+        self.update_expression = UpdateValues()
+
+        for index, (key, value) in enumerate(data.items()):
+            key = self.keys.add(key)
+            self.update_expression.add(key, value)
+
+    @property
+    def args(self):
+        """Returns the arguments for the boto3 API call."""
+        return {
+            'ExpressionAttributeNames': self.keys.expression_names,
+            'ExpressionAttributeValues': self.update_expression.values,
+            'UpdateExpression': 'SET ' + ', '.join(self.update_expression.expressions),
+        }

nuql/api/update/update_item.py

@@ -0,0 +1,139 @@
+__all__ = ['UpdateItem']
+
+from typing import Any, Dict, Optional, Literal
+
+from boto3.dynamodb.types import TypeSerializer
+from botocore.exceptions import ClientError
+
+import nuql
+from nuql import types, api, resources
+
+
+class UpdateItem(api.Boto3Adapter):
+    serialisation_action: Literal['create', 'update'] = 'update'
+
+    def prepare_client_args(
+            self,
+            data: Dict[str, Any],
+            condition: Dict[str, Any] | None = None,
+            shallow: bool = False,
+            **kwargs,
+    ) -> Dict[str, Any]:
+        """
+        Prepares the request args for updating an item in the table (client API).
+
+        :arg data: Data to update.
+        :param condition: Optional condition expression.
+        :param shallow: Activates shallow update mode (so that whole nested items are updated at once).
+        :param kwargs: Additional args to pass to the request.
+        :return: New item dict.
+        """
+        # Serialise the data for update
+        key = self.table.serialiser.serialise_key(data)
+        serialised_data = {k: v for k, v in self.table.serialiser.serialise('update', data).items() if k not in key}
+
+        # Marshall the key into DynamoDB format
+        serialiser = TypeSerializer()
+        marshalled_key = {k: serialiser.serialize(v) for k, v in key.items()}
+
+        # Generate the update condition
+        resources.validate_condition_dict(condition)
+        condition = api.Condition(
+            table=self.table,
+            condition=condition,
+            condition_type='ConditionExpression'
+        )
+        self.on_condition(condition)
+
+        # Generate the update expression
+        update = api.UpdateExpressionBuilder(serialised_data, shallow=shallow)
+        args = {
+            'Key': marshalled_key,
+            **resources.merge_dicts(update.args, condition.client_args),
+            **kwargs
+        }
+
+        # Serialise ExpressionAttributeValues into DynamoDB format
+        if 'ExpressionAttributeValues' in args:
+            for key, value in args['ExpressionAttributeValues'].items():
+                args['ExpressionAttributeValues'][key] = serialiser.serialize(value)
+
+        # Remove empty ExpressionAttributeValues
+        if 'ExpressionAttributeValues' in args and not args['ExpressionAttributeValues']:
+            args.pop('ExpressionAttributeValues')
+
+        return args
+
+    def prepare_args(
+            self,
+            data: Dict[str, Any],
+            condition: Dict[str, Any] | None = None,
+            shallow: bool = False,
+            **kwargs,
+    ) -> Dict[str, Any]:
+        """
+        Prepares the request args for updating an item in the table (resource API).
+
+        :arg data: Data to update.
+        :param condition: Optional condition expression.
+        :param shallow: Activates shallow update mode (so that whole nested items are updated at once).
+        :param kwargs: Additional args to pass to the request.
+        :return: New item dict.
+        """
+        # Serialise the data for update
+        key = self.table.serialiser.serialise_key(data)
+        serialised_data = {k: v for k, v in self.table.serialiser.serialise('update', data).items() if k not in key}
+
+        # Generate the update condition
+        resources.validate_condition_dict(condition)
+        condition = api.Condition(
+            table=self.table,
+            condition=condition,
+            condition_type='ConditionExpression'
+        )
+        self.on_condition(condition)
+
+        # Generate the update expression
+        update = api.UpdateExpressionBuilder(serialised_data, shallow=shallow)
+        return {'Key': key, **update.args, **condition.resource_args, **kwargs}
+
+    def on_condition(self, condition: 'api.Condition') -> None:
+        """
+        Make changes to the condition expression before request.
+
+        :arg condition: Condition instance.
+        """
+        index = self.table.indexes.primary
+        keys = [index['hash']]
+
+        # Append sort key if defined in primary index, but only if it exists in the schema
+        if 'sort' in index and index['sort'] and index['sort'] in self.table.fields:
+            keys.append(index['sort'])
+
+        expression = ' and '.join([f'attribute_exists({key})' for key in keys])
+
+        # Add the expression to the existing condition
+        condition.append(expression)
+
+    def invoke_sync(
+            self,
+            data: Dict[str, Any],
+            condition: Dict[str, Any] | None = None,
+            shallow: bool = False
+    ) -> Dict[str, Any]:
+        """
+        Updates an item in the table.
+
+        :arg data: Data to update.
+        :param condition: Optional condition expression.
+        :param shallow: Activates shallow update mode (so that whole nested items are updated at once).
+        :return: New item dict.
+        """
+        args = self.prepare_args(data=data, condition=condition, shallow=shallow, ReturnValues='ALL_NEW')
+
+        try:
+            response = self.connection.table.update_item(**args)
+        except ClientError as exc:
+            raise nuql.Boto3Error(exc, args)
+
+        return self.table.serialiser.deserialise(response['Attributes'])

nuql/api/update/utils.py

@@ -0,0 +1,126 @@
+__all__ = ['flatten_dict', 'UpdateKeys', 'UpdateValues', 'Incrementor', 'decrement', 'increment']
+
+from decimal import Decimal
+from typing import Dict, Any
+
+
+def flatten_dict(data: Dict[str, Any], parent: str = None) -> Dict[str, Any]:
+    """
+    Flattens a nested dict with dot notation keys.
+
+    :arg data: Dict to flatten.
+    :param parent: Parent key name if recursive.
+    :return: Flattened dict.
+    """
+    # Default initialiser
+    if parent is None:
+        parent = ''
+
+    items = []
+
+    for key, value in data.items():
+        new_key = (parent + '.' + key) if parent else key
+
+        # Process nested dict
+        if isinstance(value, dict):
+            if not value:
+                items.append((new_key, value))
+            else:
+                items.extend(flatten_dict(value, new_key).items())
+
+        else:
+            items.append((new_key, value))
+
+    return dict(items)
+
+
+class UpdateKeys:
+    def __init__(self) -> None:
+        """State manager for keys in an update expression."""
+        self.current_index = 0
+        self.key_dict = {}
+
+    @property
+    def expression_names(self):
+        return {value: key for key, value in self.key_dict.items()}
+
+    def add(self, key: str) -> str:
+        """
+        Parse a key for the update expression.
+
+        :arg key: Key to parse.
+        :return: Resulting keys for the update expression.
+        """
+        keys = []
+
+        # Parse nested parts and see if the key exists in the dictionary
+        for part in key.split('.'):
+            if part in self.key_dict:
+                keys.append(self.key_dict[part])
+            else:
+                keys.append(f'#key_{self.current_index}')
+                self.key_dict[part] = f'#key_{self.current_index}'
+                self.current_index += 1
+
+        return '.'.join(keys)
+
+
+class UpdateValues:
+    def __init__(self) -> None:
+        """State manager for values in an update expression."""
+        self.current_index = 0
+        self.values = {}
+        self.expressions = []
+
+    def add(self, key: str, value: Any) -> None:
+        """
+        Add a value to the update expression.
+
+        :arg key: Key in the update expression.
+        :arg value: Any value.
+        :return: Resulting value key for the update expression.
+        """
+        value_key = f':val_{self.current_index}'
+
+        if isinstance(value, Incrementor):
+            self.values[value_key] = value.value
+            self.expressions.append(f'{key} = {key} {"-" if value.negative else "+"} {value_key}')
+        else:
+            self.values[value_key] = value
+            self.expressions.append(f'{key} = {value_key}')
+
+        self.current_index += 1
+
+
+class Incrementor:
+    def __init__(self, value: int | float | Decimal, negative: bool = False) -> None:
+        """
+        Data class for increment/decrement operations.
+        :arg value: Value to increment/decrement.
+        :param negative: Set to true to decrement the value.
+        """
+        if not isinstance(value, Decimal):
+            value = Decimal(str(value))
+
+        self.value = value
+        self.negative = negative
+
+
+def increment(value: int | float | Decimal) -> Incrementor:
+    """
+    Increment a value on an update expression.
+
+    :arg value: Value to increment.
+    :return: Incrementor instance.
+    """
+    return Incrementor(value, negative=False)
+
+
+def decrement(value: int | float | Decimal) -> Incrementor:
+    """
+    Decrement a value on an update expression.
+
+    :arg value: Value to decrement.
+    :return: Incrementor instance.
+    """
+    return Incrementor(value, negative=True)

nuql/api/upsert.py

@@ -0,0 +1,32 @@
+__all__ = ['Upsert']
+
+from typing import Any, Dict
+
+import nuql
+from nuql import api
+
+
+class Upsert(api.Boto3Adapter):
+    def invoke_sync(self, data: Dict[str, Any], shallow: bool = False) -> Dict[str, Any]:
+        """
+        Updates an item in the table if it exists, otherwise creates a new one.
+
+        [NOTE]
+        Conditions aren't allowed for this API to avoid ambiguous
+        ConditionCheckFailedException (as this is a catch-all for any condition).
+
+        :arg data: Data to upsert.
+        :param shallow: Activates shallow update mode (so that whole nested items are updated at once).
+        :return: New item dict.
+        """
+        try:
+            update = api.UpdateItem(self.client, self.table)
+            return update.invoke_sync(data=data, shallow=shallow)
+
+        except nuql.Boto3Error as exc:
+            # When condition failed the create API will be used instead.
+            if exc.code == 'ConditionalCheckFailedException':
+                create = api.Create(self.client, self.table)
+                return create.invoke_sync(data=data)
+
+            raise exc