nuql 0.0.1__py3-none-any.whl

nuql/fields/list.py

@@ -0,0 +1,90 @@
+__all__ = ['List']
+
+from typing import List as _List, Any
+
+import nuql
+from nuql import resources, types
+from nuql.resources import FieldBase
+
+
+class List(FieldBase):
+    type = 'list'
+    of: FieldBase
+
+    def on_init(self) -> None:
+        """Defines the contents of the list."""
+        if 'of' not in self.config:
+            raise nuql.NuqlError(
+                code='SchemaError',
+                message='Config key \'of\' must be defined for the list field type'
+            )
+
+        # Initialise the configured 'of' field type
+        field_map = resources.create_field_map(
+            fields={'of': self.config['of']},
+            parent=self.parent,
+            field_types=self.parent.provider.fields
+        )
+        self.of = field_map['of']
+
+    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
+        if not isinstance(value, list):
+            value = None
+        else:
+            value = [self.of(item, action, validator) for item in value]
+
+        # 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 deserialise(self, value: _List[Any] | None) -> _List[Any] | None:
+        """
+        Deserialises a list of values.
+
+        :arg value: List or None.
+        :return: List or None.
+        """
+        if not isinstance(value, list):
+            return None
+
+        return [self.of.deserialise(item) for item in value]

nuql/fields/map.py

@@ -0,0 +1,67 @@
+__all__ = ['Map']
+
+from typing import Dict as _Dict, Any
+
+import nuql
+from nuql import resources, types
+
+
+class Map(resources.FieldBase):
+    type = 'map'
+    fields: _Dict[str, Any] = {}
+    serialiser: 'resources.Serialiser' = None
+
+    def on_init(self) -> None:
+        """Initialises the dict schema."""
+        if 'fields' not in self.config:
+            raise nuql.NuqlError(
+                code='SchemaError',
+                message='Config key \'fields\' must be defined for the dict field type'
+            )
+
+        self.fields = resources.create_field_map(self.config['fields'], self.parent, self.parent.provider.fields)
+        self.serialiser = resources.Serialiser(self)
+
+    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
+        if value:
+            value = self.serialiser.serialise(action, value, validator)
+
+        # Validate required field
+        if self.required and action == 'create' and value is None:
+            validator.add(name=self.name, message='Field is required')
+
+        # 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

nuql/fields/string.py

@@ -0,0 +1,184 @@
+__all__ = ['String']
+
+import re
+from string import Template
+from typing import List, Dict, Any
+
+import nuql
+from nuql import resources, types
+
+
+TEMPLATE_PATTERN = r'\$\{(\w+)}'
+
+
+class String(resources.FieldBase):
+    type = 'string'
+    is_template = False
+
+    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 and not self.value and not self.is_template:
+            value = self.default
+
+        if self.value and not self.is_template:
+            value = self.value
+
+        # Serialise the value
+        if self.is_template:
+            value = self.serialise_template(value, action, validator)
+        else:
+            value = self.serialise(value)
+
+        # Validate required field
+        if self.required and action == 'create' and value is None:
+            validator.add(name=self.name, message='Field is required')
+
+        # 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 string field when a template is defined."""
+        self.is_template = self.value is not None and bool(re.search(TEMPLATE_PATTERN, self.value))
+
+        def callback(field_map: dict) -> None:
+            """Callback fn to configure projected fields on the schema."""
+            for key in self.find_projections(self.value):
+                if key not in field_map:
+                    raise nuql.NuqlError(
+                        code='TemplateStringError',
+                        message=f'Field \'{key}\' (projected on string field '
+                                f'\'{self.name}\') is not defined in the schema'
+                    )
+
+                # Add reference to this field on the projected field
+                field_map[key].projected_from.append(self.name)
+                self.projects_fields.append(key)
+
+        if self.init_callback is not None and self.is_template:
+            self.init_callback(callback)
+
+    def serialise(self, value: str | None) -> str | None:
+        """
+        Serialises a string value.
+
+        :arg value: Value.
+        :return: Serialised value
+        """
+        return str(value) if value else None
+
+    def deserialise(self, value: str | None) -> str | None:
+        """
+        Deserialises a string value.
+
+        :arg value: String value.
+        :return: String value.
+        """
+        return str(value) if value else None
+
+    def serialise_template(
+            self,
+            value: Dict[str, Any],
+            action: 'types.SerialisationType',
+            validator: 'resources.Validator'
+    ) -> str | None:
+        """
+        Serialises a template string.
+
+        :arg value: Dict of projections.
+        :arg action: Serialisation type.
+        :arg validator: Validator instance.
+        :return: String value.
+        """
+        if not isinstance(value, dict):
+            value = {}
+
+        # Add not provided keys as empty strings
+        for key in self.find_projections(self.value):
+            if key not in value:
+                value[key] = None
+
+        serialised = {}
+
+        # Serialise values before substituting
+        for key, deserialised_value in value.items():
+            field = self.parent.fields.get(key)
+
+            if not field:
+                raise nuql.NuqlError(
+                    code='TemplateStringError',
+                    message=f'Field \'{key}\' (projected on string field '
+                            f'\'{self.name}\') is not defined in the schema'
+                )
+
+            serialised_value = field(deserialised_value, action, validator)
+            serialised[key] = serialised_value if serialised_value else ''
+
+        template = Template(self.value)
+        return template.substitute(serialised)
+
+    def deserialise_template(self, value: str | None) -> Dict[str, Any]:
+        """
+        Deserialises a string template.
+
+        :arg value: String value or None.
+        :return: Dict of projections.
+        """
+        if not value:
+            return {}
+
+        pattern = re.sub(TEMPLATE_PATTERN, r'(?P<\1>[^&#]+)', self.value)
+        match = re.fullmatch(pattern, value)
+        output = {}
+
+        for key, serialised_value in (match.groupdict() if match else {}).items():
+            field = self.parent.fields.get(key)
+
+            if not field:
+                raise nuql.NuqlError(
+                    code='TemplateStringError',
+                    message=f'Field \'{key}\' (projected on string field '
+                            f'\'{self.name}\') is not defined in the schema'
+                )
+
+            deserialised_value = field.deserialise(serialised_value)
+            output[key] = deserialised_value
+
+        return output
+
+    @staticmethod
+    def find_projections(value: str) -> List[str]:
+        """
+        Finds projections in the value provided as templates '${field_name}'.
+
+        :arg value: Value to parse.
+        :return: List of field names.
+        """
+        return re.findall(TEMPLATE_PATTERN, value)

nuql/fields/ulid.py

@@ -0,0 +1,39 @@
+__all__ = ['Ulid']
+
+from ulid import ULID
+
+from nuql import resources
+
+
+class Ulid(resources.FieldBase):
+    type = 'ulid'
+
+    def serialise(self, value: ULID | str | None) -> str | None:
+        """
+        Serialises a ULID value.
+
+        :arg value: ULID, str or None.
+        :return: str or None.
+        """
+        if isinstance(value, ULID):
+            return str(value)
+        if isinstance(value, str):
+            try:
+                return str(ULID.from_str(value))
+            except ValueError:
+                return None
+        return None
+
+    def deserialise(self, value: str | None) -> str | None:
+        """
+        Deserialises a ULID value.
+
+        :arg value: str or None.
+        :return: str or None.
+        """
+        if isinstance(value, str):
+            # try:
+                return str(ULID.from_str(value))
+            # except ValueError:
+            #     return None
+        return None

nuql/fields/uuid.py

@@ -0,0 +1,42 @@
+__all__ = ['Uuid']
+
+from uuid import UUID as NATIVE_UUID
+from uuid_utils import UUID
+
+from nuql import resources
+
+
+class Uuid(resources.FieldBase):
+    type = 'uuid'
+
+    def serialise(self, value: NATIVE_UUID | UUID | str | None) -> str | None:
+        """
+        Serialises a UUID value.
+
+        :arg value: UUID, str or None.
+        :return: str or None.
+        """
+        if isinstance(value, (NATIVE_UUID, UUID)):
+            return str(value)
+
+        if isinstance(value, str):
+            try:
+                return str(UUID(value))
+            except ValueError:
+                return None
+
+        return None
+
+    def deserialise(self, value: str | None) -> str | None:
+        """
+        Deserialises a UUID value (only to string).
+
+        :arg value: str or None.
+        :return: str or None.
+        """
+        if isinstance(value, str):
+            try:
+                return str(UUID(value))
+            except ValueError:
+                return None
+        return None

nuql/generators/__init__.py

@@ -0,0 +1,3 @@
+from .datetime import *
+from .uuid import *
+from .ulid import *

nuql/generators/datetime.py

@@ -0,0 +1,37 @@
+__all__ = ["Datetime"]
+
+from datetime import datetime, timedelta, UTC
+
+
+class Datetime:
+    @classmethod
+    def now(cls):
+        """Generates current UTC time"""
+        def generator():
+            return datetime.now(UTC)
+        return generator
+
+    @classmethod
+    def relative(
+            cls,
+            days: float = 0,
+            seconds: float = 0,
+            microseconds: float = 0,
+            milliseconds: float = 0,
+            minutes: float = 0,
+            hours: float = 0,
+            weeks: float = 0
+    ):
+        """Generates a UTC datetime relative to now."""
+        def generator():
+            return datetime.now(UTC) + timedelta(
+                days=days,
+                seconds=seconds,
+                microseconds=microseconds,
+                milliseconds=milliseconds,
+                minutes=minutes,
+                hours=hours,
+                weeks=weeks
+            )
+
+        return generator

nuql/generators/ulid.py

@@ -0,0 +1,10 @@
+from ulid import ULID
+
+
+class Ulid:
+    @classmethod
+    def now(cls):
+        """Generates current ULID"""
+        def generator():
+            return ULID()
+        return generator

nuql/generators/uuid.py

@@ -0,0 +1,19 @@
+__all__ = ['Uuid']
+
+from uuid_utils import uuid4, uuid7
+
+
+class Uuid:
+    @classmethod
+    def v4(cls):
+        """Generates a random UUID v4"""
+        def generator():
+            return uuid4()
+        return generator
+
+    @classmethod
+    def v7(cls):
+        """Generates a random UUID v7"""
+        def generator():
+            return uuid7()
+        return generator

nuql/resources/__init__.py

@@ -0,0 +1,4 @@
+from .fields import *
+from .tables import *
+from .records import *
+from .utils import *

nuql/resources/fields/__init__.py

@@ -0,0 +1,3 @@
+from .value import *
+from .field import *
+from .field_map import *

nuql/resources/fields/field.py

@@ -0,0 +1,153 @@
+__all__ = ['FieldBase']
+
+from typing import Any, List, Optional, Callable
+
+import nuql
+from nuql import resources, types
+
+
+class FieldBase:
+    type: str = None
+
+    def __init__(
+            self,
+            name: str,
+            config: 'types.FieldConfig',
+            parent: 'resources.Table',
+            init_callback: Callable[[Callable], None] | None = None
+    ) -> None:
+        """
+        Wrapper for the handling of field serialisation and deserialisation.
+
+        :arg name: Field name.
+        :arg config: Field config dict.
+        :arg parent: Parent instance.
+        :param init_callback: Optional init callback.
+        """
+        self.name = name
+        self.config = config
+        self.parent = parent
+        self.init_callback = init_callback
+
+        # Handle 'KEY' field type
+        self.projected_from = []
+        self.projects_fields = []
+
+        self.on_init()
+
+    @property
+    def required(self) -> bool:
+        return self.config.get('required', False)
+
+    @property
+    def default(self) -> Any:
+        return self.config.get('default', None)
+
+    @property
+    def value(self) -> Any:
+        return self.config.get('value', None)
+
+    @property
+    def on_create(self) -> Optional['types.GeneratorCallback']:
+        return self.config.get('on_create', None)
+
+    @property
+    def on_update(self) -> Optional['types.GeneratorCallback']:
+        return self.config.get('on_update', None)
+
+    @property
+    def on_write(self) -> Optional['types.GeneratorCallback']:
+        return self.config.get('on_write', None)
+
+    @property
+    def validator(self) -> Optional['types.ValidatorCallback']:
+        return self.config.get('validator', None)
+
+    @property
+    def enum(self) -> List[Any] | None:
+        return self.config.get('enum', None)
+
+    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(value)
+
+        # 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 serialise(self, value: Any) -> Any:
+        """
+        Serialise/marshal the field value into DynamoDB format.
+
+        :arg value: Deserialised value.
+        :return: Serialised value.
+        """
+        raise nuql.NuqlError(
+            code='NotImplementedError',
+            message='Serialisation has not been implemented for this field type.'
+        )
+
+    def deserialise(self, value: Any) -> Any:
+        """
+        Deserialise/unmarshal the field value from DynamoDB format.
+
+        :arg value: Serialised value.
+        :return: Deserialised value.
+        """
+        raise nuql.NuqlError(
+            code='NotImplementedError',
+            message='Deserialisation has not been implemented for this field type.'
+        )
+
+    def on_init(self) -> None:
+        """Custom initialisation logic for the field."""
+        pass
+
+    def internal_validation(self, value: Any, action: 'types.SerialisationType', validator: 'resources.Validator'):
+        """
+        Perform internal validation on the field.
+
+        :arg value: Value.
+        :arg action: Serialisation action.
+        :arg validator: Validator instance.
+        """
+        pass