nuql 0.0.1__tar.gz

nuql-0.0.1/.gitignore

@@ -0,0 +1,4 @@
+.venv
+.idea
+local.py
+.coverage

nuql-0.0.1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: nuql
+Version: 0.0.1
+Summary: Nuql (pronounced 'nuckle') is a lightweight DynamoDB library for implementing the single table model pattern.
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.13
+Requires-Dist: boto3>=1.40.0
+Requires-Dist: pyparsing>=3.2.3
+Requires-Dist: python-ulid>=3.0.0
+Requires-Dist: uuid-utils>=0.11.0

nuql-0.0.1/nuql/__init__.py

@@ -0,0 +1,3 @@
+from .exceptions import *
+from .connection import *
+from .client import *

nuql-0.0.1/nuql/api/__init__.py

@@ -0,0 +1,13 @@
+from .adapter import *
+from .query import *
+from .batch_write import *
+from .get import *
+from .delete import *
+from .update import *
+from .put_item import *
+from .create import *
+from .upsert import *
+from .put_update import *
+from .condition_check import *
+from .transaction import *
+from .batch_get import *

nuql-0.0.1/nuql/api/adapter.py

@@ -0,0 +1,34 @@
+__all__ = ['Boto3Adapter']
+
+from typing import Any, Dict
+
+import nuql
+from nuql import resources
+
+
+class Boto3Adapter:
+    def __init__(self, client: 'nuql.Nuql', table: 'resources.Table'):
+        """
+        Wrapper around API actions against boto3.
+
+        :arg client: Nuql instance.
+        """
+        self.client = client
+        self.connection = client.connection
+        self.table = table
+
+    def prepare_client_args(self, *args, **kwargs) -> Dict[str, Any]:
+        """Prepares the arguments for boto3 API invocation (for the client API)."""
+        raise NotImplementedError('Argument preparation for the client API has not been implemented for this method.')
+
+    def prepare_args(self, *args, **kwargs) -> Dict[str, Any]:
+        """Prepares the arguments for boto3 API invocation."""
+        raise NotImplementedError('Argument preparation has not been implemented for this method.')
+
+    def invoke_sync(self, *args, **kwargs) -> Any:
+        """Synchronously invokes boto3 API."""
+        raise NotImplementedError('Synchronous API invocation has not been implemented for this method.')
+
+    async def invoke_async(self, *args, **kwargs) -> Any:
+        """Asynchronously invokes boto3 API."""
+        raise NotImplementedError('Asynchronous API invocation has not been implemented for this method.')

nuql-0.0.1/nuql/api/batch_get/__init__.py

@@ -0,0 +1,2 @@
+from .queue import *
+from .batch_get import *

nuql-0.0.1/nuql/api/batch_get/batch_get.py

@@ -0,0 +1,40 @@
+__all__ = ['BatchGet']
+
+from typing import Any, List, Dict
+
+from botocore.exceptions import ClientError
+
+import nuql
+from nuql import api
+from nuql.api import Boto3Adapter
+
+
+class BatchGet(Boto3Adapter):
+    def invoke_sync(self, keys: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Performs a batch get operation against the table.
+
+        :arg keys: Keys to get.
+        :return: Batch get result.
+        """
+        queue = api.BatchGetQueue(self.table, keys)
+        fulfilled = False
+
+        # Loop through until all keys have been processed
+        while not fulfilled:
+            batch = queue.get_batch()
+
+            if batch is None:
+                fulfilled = True
+                continue
+
+            args = {'RequestItems': batch}
+
+            try:
+                response = self.client.connection.client.batch_get_item(**args)
+                queue.process_response(response)
+
+            except ClientError as exc:
+                raise nuql.Boto3Error(exc, args)
+
+        return queue.result

nuql-0.0.1/nuql/api/batch_get/queue.py

@@ -0,0 +1,120 @@
+__all__ = ['BatchGetQueue']
+
+from typing import List, Dict, Any
+
+from boto3.dynamodb.types import TypeSerializer, TypeDeserializer
+
+from nuql import resources
+
+
+class BatchGetQueue:
+    def __init__(self, table: 'resources.Table', keys: List[Dict[str, Any]]):
+        """
+        Queue helper for performing batch get operations.
+
+        :arg table: Table instance.
+        :arg keys: List of record keys to retrieve.
+        """
+        self.table = table
+        self.db_table_name = self.table.provider.connection.table_name
+
+        self._store = self.prepare(keys)
+
+    @staticmethod
+    def get_key_hash(key: Dict[str, Any]) -> str:
+        """
+        Simple hash function to make the store accessible by key.
+
+        :arg key: Key dict.
+        :return: Str hash of the key.
+        """
+        return ','.join([str(key[sorted_key]) for sorted_key in sorted(key.keys())])
+
+    @property
+    def result(self) -> Dict[str, Any]:
+        return {
+            'items': [x['item'] for x in self._store.values() if x['item'] is not None],
+            'unprocessed_keys': [
+                x['deserialised_key'] for x in self._store.values() if x['item'] is None
+            ]
+        }
+
+    def prepare(self, keys: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Prepare the initial queue.
+
+        :arg keys: Full list of record keys.
+        :return: Queue dict.
+        """
+        output = {}
+        serialiser = TypeSerializer()
+
+        for key in keys:
+            serialised_key = self.table.serialiser.serialise_key(key)
+            key_hash = self.get_key_hash(serialised_key)
+
+            marshalled_key = {k: serialiser.serialize(v) for k, v in serialised_key.items()}
+
+            output[key_hash] = {
+                'key': marshalled_key,
+                'item': None,
+                'dispatched': False,
+                'processed': False,
+                'deserialised_key': key
+            }
+
+        return output
+
+    def process_response(self, response: Dict[str, Any]) -> None:
+        """
+        Process the raw response from DynamoDB.
+
+        :arg response: Response dict.
+        """
+        processed = response.get('Responses', {}).get(self.db_table_name, [])
+        unprocessed = response.get('UnprocessedKeys', {}).get(self.db_table_name, {}).get('Keys', [])
+        deserialiser = TypeDeserializer()
+
+        # Handle successful keys
+        for item in processed:
+            item = {k: deserialiser.deserialize(v) for k, v in item.items()}
+            data = self.table.serialiser.deserialise(item)
+            key_hash = self.get_key_hash(self.table.serialiser.serialise_key(data))
+
+            self._store[key_hash]['item'] = data
+            self._store[key_hash]['processed'] = True
+
+        # Handle unprocessed keys (throttled)
+        for key in unprocessed:
+            data = self.table.serialiser.deserialise(key)
+            key_hash = self.get_key_hash(data)
+
+            # Reset the item
+            self._store[key_hash]['item'] = None
+            self._store[key_hash]['processed'] = False
+            self._store[key_hash]['dispatched'] = False
+
+    def get_batch(self, size: int = 100) -> Dict[str, Any] | None:
+        """
+        Get a batch of unprocessed keys.
+
+        :param size: Max number of keys to return.
+        :return: List of key dicts or None.
+        """
+        # Collect items not yet processed or dispatched
+        items = [
+            (key_hash, entry)
+            for key_hash, entry in self._store.items()
+            if not entry['processed'] and not entry['dispatched']
+        ]
+        selected = items[:size]
+
+        if not selected:
+            return None
+
+        # Mark dispatched to avoid re-dispatching
+        for key_hash, entry in selected:
+            entry['dispatched'] = True
+
+        batch_keys = [entry['key'] for _, entry in selected]
+        return {self.db_table_name: {'Keys': batch_keys}}

nuql-0.0.1/nuql/api/batch_write.py

@@ -0,0 +1,99 @@
+__all__ = ['BatchWrite']
+
+from typing import Dict, Any, Optional
+
+from botocore.exceptions import ClientError
+
+import nuql
+from nuql import resources, types, api
+
+
+class BatchWrite:
+    def __init__(self, client: 'nuql.Nuql') -> None:
+        """
+        Batch writer context manager.
+
+        :arg client: Nuql instance.
+        """
+        self.client = client
+
+        self._actions = {'put_item': [], 'delete_item': []}
+        self._started = False
+
+    def __enter__(self):
+        """Enter the context manager."""
+        self._actions = {'put_item': [], 'delete_item': []}
+        self._started = True
+
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Dispatch batch write to DynamoDB."""
+        try:
+            with self.client.connection.table.batch_writer() as batch:
+                for args in self._actions['put_item']:
+                    batch.put_item(**args)
+
+                for args in self._actions['delete_item']:
+                    batch.delete_item(**args)
+
+        except ClientError as exc:
+            raise nuql.Boto3Error(exc, self._actions)
+
+        self._started = False
+        return False
+
+    def _validate_started(self) -> None:
+        """Validates that the context manager has been started."""
+        if not self._started:
+            raise nuql.NuqlError(
+                code='BatchWriteError',
+                message='Batch write context manager has not been started'
+            )
+
+    def create(self,
+            table: 'resources.Table',
+            data: Dict[str, Any],
+    ) -> None:
+        """
+        Create a new item on the table as part of a batch write.
+
+        :arg table: Table instance.
+        :arg data: Data to create.
+        """
+        self._validate_started()
+        create = api.Create(self.client, table)
+        args = create.prepare_args(data=data, exclude_condition=True)
+        self._actions['put_item'].append(args)
+
+    def update(
+            self,
+            table: 'resources.Table',
+            data: Dict[str, Any],
+    ) -> None:
+        """
+        Update an existing item on the table as part of a batch write.
+
+        :arg table: Table instance.
+        :arg data: Data to update.
+        """
+        self._validate_started()
+        put_update = api.PutUpdate(self.client, table)
+        args = put_update.prepare_args(data=data, exclude_condition=True)
+        self._actions['put_item'].append(args)
+
+    def delete(
+            self,
+            table: 'resources.Table',
+            key: Dict[str, Any],
+    ) -> None:
+        """
+        Delete an item on the table as part of a batch write.
+
+        :arg table: Table instance.
+        :arg key: Item key.
+        """
+        self._validate_started()
+        delete = api.Delete(self.client, table)
+        args = delete.prepare_args(key=key, exclude_condition=True)
+        self._actions['delete_item'].append(args)

nuql-0.0.1/nuql/api/condition_check.py

@@ -0,0 +1,39 @@
+__all__ = ['ConditionCheck']
+
+from typing import Dict, Any
+
+from boto3.dynamodb.types import TypeSerializer
+
+from nuql import types, api, resources
+from nuql.api import Boto3Adapter
+
+
+class ConditionCheck(Boto3Adapter):
+    def prepare_client_args(self, key: Dict[str, Any], condition: Dict[str, Any], **kwargs) -> Dict[str, Any]:
+        """
+        Prepare the request args for a condition check operation against the table (client API).
+
+        :arg key: Record key as a dict.
+        :arg condition: Condition expression.
+        :param kwargs: Optional parameters to add to the request.
+        :return: Client request args.
+        """
+        serialised_data = self.table.serialiser.serialise('query', key)
+        resources.validate_condition_dict(condition, required=True)
+        condition = api.Condition(self.table, condition, 'ConditionExpression')
+
+        # Marshall into the DynamoDB format
+        serialiser = TypeSerializer()
+        marshalled_data = {k: serialiser.serialize(v) for k, v in serialised_data.items()}
+
+        args = {'Key': marshalled_data, **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)
+
+        if 'ExpressionAttributeValues' in args and not args['ExpressionAttributeValues']:
+            args.pop('ExpressionAttributeValues')
+
+        return args

nuql-0.0.1/nuql/api/create.py

@@ -0,0 +1,25 @@
+__all__ = ['Create']
+
+from nuql import api
+
+
+class Create(api.PutItem):
+    serialisation_action = 'create'
+
+    def on_condition(self, condition: 'api.Condition') -> None:
+        """
+        Sets the condition expression to assert creation.
+
+        :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_not_exists({key})' for key in keys])
+
+        # Add the expression to the existing condition
+        condition.append(expression)

nuql-0.0.1/nuql/api/delete.py

@@ -0,0 +1,88 @@
+__all__ = ['Delete']
+
+from typing import Any, Dict, Optional
+
+from boto3.dynamodb.types import TypeSerializer
+from botocore.exceptions import ClientError
+
+import nuql
+from nuql import types, api, resources
+from nuql.api import Boto3Adapter, Condition
+
+
+class Delete(Boto3Adapter):
+    def prepare_client_args(
+            self,
+            key: Dict[str, Any],
+            condition: Dict[str, Any] | None = None,
+            exclude_condition: bool = False,
+            **kwargs,
+    ) -> Dict[str, Any]:
+        """
+        Prepares the request args for a delete operation of an item on the table (client API).
+
+        :arg key: Record key as a dict.
+        :param condition: Condition expression as a dict.
+        :param exclude_condition: Exclude condition from request (i.e. for BatchWrite).
+        :param kwargs: Additional args to pass to the request.
+        """
+        serialised_data = self.table.serialiser.serialise('query', key)
+        resources.validate_condition_dict(condition)
+        condition = api.Condition(self.table, condition, 'ConditionExpression')
+
+        # Marshall into the DynamoDB format
+        serialiser = TypeSerializer()
+        marshalled_data = {k: serialiser.serialize(v) for k, v in serialised_data.items()}
+
+        args = {'Key': marshalled_data, **kwargs}
+
+        if not exclude_condition:
+            args.update(condition.client_args)
+
+        return args
+
+    def prepare_args(
+            self,
+            key: Dict[str, Any],
+            condition: Dict[str, Any] | None = None,
+            exclude_condition: bool = False,
+            **kwargs,
+    ) -> Dict[str, Any]:
+        """
+        Prepares the request args for a delete operation of an item on the table (resource API).
+
+        :arg key: Record key as a dict.
+        :param condition: Condition expression as a dict.
+        :param exclude_condition: Exclude condition from request (i.e. for BatchWrite).
+        :param kwargs: Additional args to pass to the request.
+        """
+        resources.validate_condition_dict(condition)
+        condition_expression = Condition(
+            table=self.table,
+            condition=condition,
+            condition_type='ConditionExpression'
+        )
+        args = {'Key': self.table.serialiser.serialise_key(key), **kwargs}
+
+        if not exclude_condition:
+            args.update(condition_expression.resource_args)
+
+        return args
+
+    def invoke_sync(
+            self,
+            key: Dict[str, Any],
+            condition: Dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Performs a delete operation for an item on the table.
+
+        :arg key: Record key as a dict.
+        :param condition: Condition expression as a dict.
+        """
+        args = self.prepare_args(key=key, condition=condition)
+
+        try:
+            self.client.connection.table.delete_item(**args)
+        except ClientError as exc:
+            raise nuql.Boto3Error(exc, args)

nuql-0.0.1/nuql/api/get.py

@@ -0,0 +1,30 @@
+__all__ = ['Get']
+
+from typing import Any, Dict
+
+from botocore.exceptions import ClientError
+
+import nuql
+from nuql.api import Boto3Adapter
+
+
+class Get(Boto3Adapter):
+    def invoke_sync(self, key: Dict[str, Any], consistent_read: bool = False) -> Dict[str, Any]:
+        """
+        Retrieves a record from the table using the key.
+
+        :arg key: Record key as a dict.
+        :param consistent_read: Perform a consistent read.
+        :return: Deserialised record dict.
+        """
+        args = {'Key': self.table.serialiser.serialise_key(key), 'ConsistentRead': consistent_read}
+
+        try:
+            response = self.client.connection.table.get_item(**args)
+        except ClientError as exc:
+            raise nuql.Boto3Error(exc, args)
+
+        if 'Item' not in response:
+            raise nuql.ItemNotFound(args['Key'])
+
+        return self.table.serialiser.deserialise(response['Item'])

nuql-0.0.1/nuql/api/put_item.py

@@ -0,0 +1,112 @@
+__all__ = ['PutItem']
+
+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
+from nuql.api import Boto3Adapter
+
+
+class PutItem(Boto3Adapter):
+    serialisation_action: Literal['create', 'update', 'write'] = 'write'
+
+    def prepare_client_args(
+            self,
+            data: Dict[str, Any],
+            condition: Optional['types.QueryWhere'] = None,
+            exclude_condition: bool = False,
+            **kwargs,
+    ) -> Dict[str, Any]:
+        """
+        Prepare the request args for a put operation against the table (client API).
+
+        :arg data: Data to put.
+        :param condition: Optional condition expression dict.
+        :param exclude_condition: Exclude condition from request (i.e. for BatchWrite).
+        :param kwargs: Additional args to pass to the request.
+        :return: New item dict.
+        """
+        serialised_data = self.table.serialiser.serialise(self.serialisation_action, data)
+        condition = api.Condition(self.table, condition, 'ConditionExpression')
+        condition_args = condition.client_args
+
+        # Marshall into the DynamoDB format
+        serialiser = TypeSerializer()
+        marshalled_data = {k: serialiser.serialize(v) for k, v in serialised_data.items()}
+
+        # Implement ability to modify condition before the request
+        self.on_condition(condition)
+
+        # Serialise ExpressionAttributeValues into DynamoDB format
+        if 'ExpressionAttributeValues' in condition_args:
+            condition_args = {**condition_args}
+            for k, v in condition_args['ExpressionAttributeValues'].items():
+                condition_args['ExpressionAttributeValues'][k] = serialiser.serialize(v)
+
+        args: Dict[str, Any] = {'Item': marshalled_data, **kwargs}
+
+        if not exclude_condition:
+            args.update(condition.client_args)
+
+        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,
+            exclude_condition: bool = False,
+            **kwargs,
+    ) -> Dict[str, Any]:
+        """
+        Prepare the request args for a put operation against the table (resource API).
+
+        :arg data: Data to put.
+        :param condition: Optional condition expression dict.
+        :param exclude_condition: Exclude condition from request (i.e. for BatchWrite).
+        :param kwargs: Additional args to pass to the request.
+        :return: New item dict.
+        """
+        serialised_data = self.table.serialiser.serialise(self.serialisation_action, data)
+        resources.validate_condition_dict(condition, required=False)
+        condition = api.Condition(self.table, condition, 'ConditionExpression')
+
+        # Implement ability to modify condition before the request
+        self.on_condition(condition)
+
+        args = {'Item': serialised_data, **kwargs}
+
+        if not exclude_condition:
+            args.update(condition.resource_args)
+
+        return args
+
+    def on_condition(self, condition: 'api.Condition') -> None:
+        """
+        Make changes to the condition expression before request.
+
+        :arg condition: Condition instance.
+        """
+        pass
+
+    def invoke_sync(self, data: Dict[str, Any], condition: Dict[str, Any] | None = None) -> Dict[str, Any]:
+        """
+        Perform a put operation against the table.
+
+        :arg data: Data to put.
+        :param condition: Optional condition expression dict.
+        :return: New item dict.
+        """
+        args = self.prepare_args(data=data, condition=condition)
+
+        try:
+            self.connection.table.put_item(**args)
+        except ClientError as exc:
+            raise nuql.Boto3Error(exc, args)
+
+        return args['Item']

nuql-0.0.1/nuql/api/put_update.py

@@ -0,0 +1,25 @@
+__all__ = ['PutUpdate']
+
+from nuql import api
+
+
+class PutUpdate(api.PutItem):
+    serialisation_action = 'create'
+
+    def on_condition(self, condition: 'api.Condition') -> None:
+        """
+        Sets the condition expression to assert creation.
+
+        :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)

nuql-0.0.1/nuql/api/query/__init__.py

@@ -0,0 +1,4 @@
+from .key_condition import *
+from .condition_builder import *
+from .condition import *
+from .query import *