nuql 0.0.1__py3-none-any.whl

nuql/client.py

@@ -0,0 +1,88 @@
+__all__ = ['Nuql']
+
+from typing import List, Type, Dict, Any
+
+from boto3 import Session
+
+from nuql import types, api, resources
+from . import Connection, exceptions
+
+
+class Nuql:
+    def __init__(
+            self,
+            name: str,
+            indexes: List[Dict[str, Any]] | Dict[str, Any],
+            schema: Dict[str, Any],
+            session: Session | None = None,
+            custom_fields: List[Type['types.FieldType']] | None = None,
+            global_fields: Dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Nuql - a lightweight DynamoDB library for implementing
+        the single table model pattern.
+
+        :arg name: DynamoDB table name.
+        :arg indexes: Table index definition.
+        :arg schema: Table design.
+        :param session: Boto3 Session instance.
+        :param custom_fields: List of custom field types.
+        :param global_fields: Additional field definitions to apply to all tables.
+        """
+        if not isinstance(session, Session):
+            session = Session()
+
+        if custom_fields is None:
+            custom_fields = []
+
+        # Insert global fields on to all tables
+        if isinstance(global_fields, dict):
+            for table in schema.values():
+                table.update(global_fields)
+
+        self.connection = Connection(name, session)
+        self.fields = custom_fields
+        self.__schema = schema
+        self.__indexes = resources.Indexes(indexes)
+
+        resources.validate_schema(self.__schema, self.fields)
+
+    @property
+    def indexes(self) -> 'resources.Indexes':
+        return self.__indexes
+
+    @property
+    def schema(self) -> 'types.SchemaConfig':
+        return self.__schema
+
+    def batch_write(self) -> 'api.BatchWrite':
+        """
+        Instantiates a `BatchWrite` object for performing batch writes to DynamoDB.
+
+        :return: BatchWrite instance.
+        """
+        return api.BatchWrite(self)
+
+    def transaction(self) -> 'api.Transaction':
+        """
+        Instantiates a `Transaction` object for performing transactions on a DynamoDB table.
+
+        :return: Transaction instance.
+        """
+        return api.Transaction(self)
+
+    def get_table(self, name: str) -> 'resources.Table':
+        """
+        Instantiates a `Table` object for the chosen table in the schema.
+
+        :arg name: Table name (in schema) to instantiate.
+        :return: Table instance.
+        """
+        if name not in self.__schema:
+            raise exceptions.NuqlError(
+                code='TableNotDefined',
+                message=f'Table \'{name}\' is not defined in the schema.'
+            )
+
+        schema = self.__schema[name]
+        return resources.Table(name=name, provider=self, schema=schema, indexes=self.indexes)

nuql/connection.py

@@ -0,0 +1,43 @@
+__all__ = ['Connection']
+
+from boto3 import Session
+
+
+class Connection:
+    def __init__(self, table_name: str, boto3_session: Session, **connection_args) -> None:
+        """
+        Wrapper for the `boto3` DynamoDB resources/clients to be
+        shared throughout the library.
+
+        :arg table_name: DynamoDB table name.
+        :arg boto3_session: Session instance.
+        :param connection_args: Additional args to pass to the client/resource.
+        """
+        self.table_name = table_name
+        self.session = boto3_session
+        self.__connection_args = connection_args
+
+        self.__resource = None
+        self.__client = None
+        self.__table = None
+
+    @property
+    def resource(self):
+        """Creates a `boto3` DynamoDB resource if it doesn't exist."""
+        if self.__resource is None:
+            self.__resource = self.session.resource('dynamodb', **self.__connection_args)
+        return self.__resource
+
+    @property
+    def client(self):
+        """Creates a `boto3` DynamoDB client if it doesn't exist."""
+        if self.__client is None:
+            self.__client = self.session.client('dynamodb', **self.__connection_args)
+        return self.__client
+
+    @property
+    def table(self):
+        """Creates a `boto3` DynamoDB table if it doesn't exist."""
+        if self.__table is None:
+            self.__table = self.resource.Table(self.table_name)
+        return self.__table

nuql/exceptions.py

@@ -0,0 +1,66 @@
+__all__ = ['NuqlError', 'ValidationError', 'Boto3Error', 'ItemNotFound']
+
+from typing import List, Dict, Any
+
+from botocore.exceptions import ClientError
+
+from nuql import types
+
+
+class NuqlError(Exception):
+    def __init__(self, code: str, message: str, **details) -> None:
+        """
+        Base exception for Nuql.
+
+        :arg code: Error code.
+        :arg message: Error message.
+        :param details: Arbitrary details to add to the exception.
+        """
+        self.code = code
+        self.message = message
+        self.details = details
+
+        super().__init__(f'[{self.code}] {self.message}')
+
+
+class ValidationError(NuqlError):
+    def __init__(self, errors: List['types.ValidationErrorItem']):
+        """
+        Exception for validation errors during the serialisation process.
+
+        :arg errors: List of ValidationErrorItem dicts.
+        """
+        self.errors = errors
+
+        formatted_message = 'Schema validation errors occurred:\n\n'
+
+        for error in self.errors:
+            formatted_message += f' \'{error["name"]}\': {error["message"]}\n'
+
+        super().__init__('ValidationError', formatted_message)
+
+
+class Boto3Error(NuqlError):
+    def __init__(self, exc: ClientError, request_args: Dict[str, Any]):
+        """
+        Exception wrapper for boto3 ClientError.
+
+        :arg exc: ClientError instance.
+        """
+        self.request_args = request_args
+        self.error_info = exc.response.get('Error', {})
+        self.code = self.error_info.get('Code', 'UnknownError')
+        self.message = self.error_info.get('Message', str(exc))
+
+        super().__init__(code=self.code, message=self.message)
+
+
+class ItemNotFound(NuqlError):
+    def __init__(self, key: Dict[str, Any]) -> None:
+        """
+        Thrown when an item is not found when doing a get_item request.
+
+        :arg key: Key used to retrieve the item.
+        """
+        self.key = key
+        super().__init__('ItemNotFound', f'Item not found: {key}')

nuql/fields/__init__.py

@@ -0,0 +1,11 @@
+from .string import *
+from .key import *
+from .boolean import *
+from .datetime import *
+from .datetime_timestamp import *
+from .list import *
+from .map import *
+from .integer import *
+from .float import *
+from .uuid import *
+from .ulid import *

nuql/fields/boolean.py

@@ -0,0 +1,29 @@
+__all__ = ['Boolean']
+
+from nuql.resources import FieldBase
+
+
+class Boolean(FieldBase):
+    type = 'boolean'
+
+    def serialise(self, value: bool | None) -> bool | None:
+        """
+        Serialises a boolean value (type checker).
+
+        :arg value: Boolean value.
+        :return: Boolean value.
+        """
+        if isinstance(value, bool):
+            return value
+        return None
+
+    def deserialise(self, value: bool | None) -> bool | None:
+        """
+        Deserialises a boolean value (type checker).
+
+        :arg value: Boolean value.
+        :return: Boolean value.
+        """
+        if isinstance(value, bool):
+            return value
+        return None

nuql/fields/datetime.py

@@ -0,0 +1,49 @@
+__all__ = ['Datetime']
+
+from datetime import datetime, UTC
+
+import nuql
+from nuql.resources import FieldBase
+
+
+class Datetime(FieldBase):
+    type = 'datetime'
+    date_format = '%Y-%m-%dT%H:%M:%S%z'
+
+    def serialise(self, value: datetime | None) -> str | None:
+        """
+        Serialises a datetime value.
+
+        :arg value: datetime instance or None.
+        :return: String representation of the datetime instance.
+        """
+        if not isinstance(value, datetime):
+            return None
+
+        # Validate that the datetime is timezone-aware
+        if not value.tzinfo:
+            raise nuql.NuqlError(
+                code='SerialisationError',
+                message='Datetime value must be timezone-aware.'
+            )
+
+        return str(value.astimezone(UTC).strftime(self.date_format))
+
+    def deserialise(self, value: str | None) -> datetime | None:
+        """
+        Deserialises a datetime value.
+
+        :arg value: String representation of the datetime.
+        :return: datetime instance or None.
+        """
+        if value is None:
+            return None
+
+        # Parse the datetime string
+        try:
+            dt = datetime.strptime(value, self.date_format)
+            dt = dt.replace(tzinfo=UTC)
+            return dt
+
+        except (ValueError, TypeError):
+            return None

nuql/fields/datetime_timestamp.py

@@ -0,0 +1,45 @@
+__all__ = ['DatetimeTimestamp']
+
+from datetime import datetime, UTC
+from decimal import Decimal
+
+import nuql
+from nuql.resources import FieldBase
+
+
+class DatetimeTimestamp(FieldBase):
+    type = 'datetime_timestamp'
+
+    def serialise(self, value: datetime | None) -> int | None:
+        """
+        Serialises a datetime to a timestamp.
+
+        :arg value: datetime instance or None.
+        :return: int or None.
+        """
+        if not isinstance(value, datetime):
+            return None
+
+        # Validate timezone-awareness
+        if value.tzinfo is None:
+            raise nuql.NuqlError(
+                code='SerialisationError',
+                message='Datetime value must be timezone-aware.'
+            )
+
+        return int(value.astimezone(UTC).timestamp() * 1000)
+
+    def deserialise(self, value: Decimal | None) -> datetime | None:
+        """
+        Deserialises a timestamp to a datetime.
+
+        :arg value: Decimal instance or None.
+        :return: datetime instance or None.
+        """
+        if not isinstance(value, Decimal):
+            return None
+
+        try:
+            return datetime.fromtimestamp(int(value) / 1000, UTC)
+        except (ValueError, TypeError):
+            return None

nuql/fields/float.py

@@ -0,0 +1,40 @@
+__all__ = ['Float']
+
+from decimal import Decimal
+from typing import Any
+
+from nuql import resources, types
+from nuql.api import Incrementor
+
+
+class Float(resources.FieldBase):
+    type = 'float'
+
+    def serialise(self, value: float | Incrementor | None) -> Decimal | Incrementor | None:
+        """
+        Serialises a float value.
+
+        :arg value: Value as float, Incrementor or None.
+        :return: Value as Decimal, Incrementor or None.
+        """
+        if not isinstance(value, (float, Incrementor)):
+            return None
+        if isinstance(value, Incrementor):
+            return value
+        return Decimal(str(value))
+
+    def deserialise(self, value: Decimal | None) -> float | None:
+        """
+        Deserialises a float value.
+
+        :arg value: Value as Decimal or None.
+        :return: Value as float or None.
+        """
+        if not isinstance(value, Decimal):
+            return None
+        return float(value)
+
+    def internal_validation(self, value: Any, action: 'types.SerialisationType', validator: 'resources.Validator'):
+        """Validate the Incrementor type."""
+        if isinstance(value, Incrementor) and action != 'update':
+            validator.add(name=self.name, message='Incrementors can only be used for updates')

nuql/fields/integer.py

@@ -0,0 +1,40 @@
+__all__ = ['Integer']
+
+from decimal import Decimal
+from typing import Any
+
+from nuql.api import Incrementor
+from nuql import resources, types
+
+
+class Integer(resources.FieldBase):
+    type = 'int'
+
+    def serialise(self, value: int | Incrementor | None) -> Decimal | Incrementor | None:
+        """
+        Serialises an integer value.
+
+        :arg value: Value as int, Incrementor or None.
+        :return: Value as Decimal, Incrementor or None.
+        """
+        if not isinstance(value, (int, Incrementor)):
+            return None
+        if isinstance(value, Incrementor):
+            return value
+        return Decimal(str(value))
+
+    def deserialise(self, value: Decimal | None) -> int | None:
+        """
+        Deserialises an integer value.
+
+        :arg value: Value as Decimal or None.
+        :return: Value as int or None.
+        """
+        if not isinstance(value, Decimal):
+            return None
+        return int(value)
+
+    def internal_validation(self, value: Any, action: 'types.SerialisationType', validator: 'resources.Validator'):
+        """Validate the Incrementor type."""
+        if isinstance(value, Incrementor) and action != 'update':
+            validator.add(name=self.name, message='Incrementors can only be used for updates')

nuql/fields/key.py

@@ -0,0 +1,207 @@
+__all__ = ['Key']
+
+import re
+from typing import Dict, Any
+
+import nuql
+from nuql import resources, types
+
+
+class Key(resources.FieldBase):
+    type = 'key'
+
+    def __call__(self, value: Any, action: 'types.SerialisationType', validator: 'resources.Validator') -> Any:
+        """
+        Encapsulates the internal serialisation logic to prepare for
+        sending the record to DynamoDB.
+
+        :arg value: Deserialised value.
+        :arg action: SerialisationType (`create`, `update`, `write` or `query`).
+        :arg validator: Validator instance.
+        :return: Serialised value.
+        """
+        has_value = not isinstance(value, resources.EmptyValue)
+
+        # Apply generators if applicable to the field to overwrite the value
+        if action in ['create', 'update', 'write']:
+            if action == 'create' and self.on_create:
+                value = self.on_create()
+
+            if action == 'update' and self.on_update:
+                value = self.on_update()
+
+            if self.on_write:
+                value = self.on_write()
+
+        # Set default value if applicable
+        if not has_value and not value:
+            value = self.default
+
+        # Serialise the value
+        value = self.serialise_template(value, action, validator)
+
+        # Validate required field
+        if self.required and action == 'create' and value is None:
+            validator.add(name=self.name, message='Field is required')
+
+        # Validate against enum
+        if self.enum and has_value and action in ['create', 'update', 'write'] and value not in self.enum:
+            validator.add(name=self.name, message=f'Value must be one of: {", ".join(self.enum)}')
+
+        # Run internal validation
+        self.internal_validation(value, action, validator)
+
+        # Run custom validation logic
+        if self.validator and action in ['create', 'update', 'write']:
+            self.validator(value, validator)
+
+        return value
+
+    def on_init(self) -> None:
+        """Initialises the key field."""
+        # Validate the field has a value
+        if self.value is None:
+            raise nuql.NuqlError(
+                code='KeySchemaError',
+                message='\'value\' must be defined for a key field'
+            )
+
+        # Callback fn handles configuring projected fields on the schema
+        def callback(field_map: dict) -> None:
+            """Callback fn to configure projected fields on the schema."""
+            for key, value in self.value.items():
+                projected_name = self.parse_projected_name(value)
+
+                # Skip fixed value fields
+                if not projected_name:
+                    continue
+
+                # Validate projected key exists on the table
+                if projected_name not in field_map:
+                    raise nuql.NuqlError(
+                        code='KeySchemaError',
+                        message=f'Field \'{projected_name}\' (projected on key '
+                                f'\'{self.name}\') is not defined in the schema'
+                    )
+
+                # Add reference to this field on the projected field
+                field_map[projected_name].projected_from.append(self.name)
+                self.projects_fields.append(projected_name)
+
+        if self.init_callback is not None:
+            self.init_callback(callback)
+
+    def serialise_template(
+            self,
+            key_dict: Dict[str, Any],
+            action: 'types.SerialisationType',
+            validator: 'resources.Validator'
+    ) -> str:
+        """
+        Serialises the key dict to a string.
+
+        :arg key_dict: Dict to serialise.
+        :arg action: Serialisation type.
+        :arg validator: Validator instance.
+        :return: Serialised representation.
+        """
+        output = ''
+        s = self.sanitise
+
+        for key, value in self.value.items():
+            projected_name = self.parse_projected_name(value)
+
+            if projected_name in self.projects_fields:
+                projected_field = self.parent.fields.get(projected_name)
+
+                if projected_field is None:
+                    raise nuql.NuqlError(
+                        code='KeySchemaError',
+                        message=f'Field \'{projected_name}\' (projected on key '
+                                f'\'{self.name}\') is not defined in the schema'
+                    )
+
+                projected_value = key_dict.get(projected_name)
+                serialised_value = projected_field(projected_value, action, validator)
+                used_value = s(serialised_value) if serialised_value else None
+            else:
+                used_value = s(value)
+
+            # A query might provide only a partial value
+            if projected_name is not None and projected_name not in value:
+                break
+
+            output += f'{s(key)}:{used_value if used_value else ""}|'
+
+        return output[:-1]
+
+    def deserialise(self, value: str) -> Dict[str, Any]:
+        """
+        Deserialises the key string to a dict.
+
+        :arg value: String key value.
+        :return: Key dict.
+        """
+        output = {}
+
+        if value is None:
+            return output
+
+        unmarshalled = {
+            key: serialised_value
+            if serialised_value else None
+            for key, serialised_value in [item.split(':') for item in value.split('|')]
+        }
+
+        for key, serialised_value in self.value.items():
+            provided_value = unmarshalled.get(key)
+            projected_name = self.parse_projected_name(serialised_value)
+
+            if projected_name in self.projects_fields:
+                projected_field = self.parent.fields.get(projected_name)
+
+                if projected_field is None:
+                    raise nuql.NuqlError(
+                        code='KeySchemaError',
+                        message=f'Field \'{projected_name}\' (projected on key '
+                                f'\'{self.name}\') is not defined in the schema'
+                    )
+
+                deserialised_value = projected_field.deserialise(provided_value)
+                output[projected_name] = deserialised_value
+            else:
+                output[key] = provided_value
+
+        return output
+
+    @staticmethod
+    def parse_projected_name(value: str) -> str | None:
+        """
+        Parses key name in the format '${field_name}'.
+
+        :arg value: Value to parse.
+        :return: Field name if it matches the format.
+        """
+        if not isinstance(value, str):
+            return None
+        match = re.search(r'\$\{([a-zA-Z0-9_]+)}', value)
+        if not match:
+            return None
+        else:
+            return match.group(1)
+
+    @staticmethod
+    def sanitise(value: str) -> str:
+        """
+        Sanitises the input to avoid conflict with serialisation/deserialisation.
+
+        :arg value: String value.
+        :return: Sanitised string value.
+        """
+        if not isinstance(value, str):
+            value = str(value)
+
+        for character in [':', '|']:
+            value = value.replace(character, '')
+
+        return value