nuql 0.0.1__py3-none-any.whl

nuql/resources/fields/field_map.py

@@ -0,0 +1,85 @@
+__all__ = ['create_field_map', 'get_field_types']
+
+import inspect
+from typing import Dict, List, Type, Any, Callable
+
+import nuql
+from nuql import resources, types
+
+
+def create_field_map(
+        fields: Dict[str, 'types.FieldConfig'],
+        parent: 'resources.Table',
+        field_types: List[Type['types.FieldType']] | None = None
+) -> Dict[str, 'types.FieldType']:
+    """
+    Generates a dict of table field instances for the serialisation process.
+
+    :arg fields: Dict of field configurations.
+    :arg parent: Parent Table instance.
+    :param field_types: Additional field types that are defined outside the library.
+    :return: Field map dict.
+    """
+    all_field_types = get_field_types(field_types)
+
+    output = {}
+    callbacks = []
+
+    def init_callback(fn: Callable[[Dict[str, Any]], None]) -> None:
+        callbacks.append(fn)
+
+    for key, config in fields.items():
+        if config['type'] not in all_field_types:
+            raise nuql.NuqlError(
+                code='InvalidFieldType',
+                message=f'Field type \'{config["type"]}\' is not defined.'
+            )
+
+        field_type = all_field_types[config['type']]
+
+        output[key] = field_type(key, config, parent, init_callback=init_callback)
+
+    # Run any applicable callbacks on the output
+    for callback in callbacks:
+        callback(output)
+
+    return output
+
+
+def get_field_types(field_types: List[Type['types.FieldType']] | None = None) -> Dict[str, Type['types.FieldType']]:
+    """
+    Dynamically generates a dict of all available field types.
+
+    :param field_types: Additional field types that are defined outside the library.
+    :return: Field type dict.
+    """
+    from nuql import fields as builtin_fields
+
+    if not isinstance(field_types, list):
+        field_types = []
+
+    output = {}
+
+    def is_valid(_obj: Any) -> bool:
+        """Check the provided object is a valid field type."""
+        if not inspect.isclass(obj):
+            return False
+
+        if not issubclass(obj, resources.FieldBase):
+            return False
+
+        return True
+
+    # Import built-in field types
+    for name in dir(builtin_fields):
+        obj = getattr(builtin_fields, name)
+
+        if is_valid(obj):
+            output[obj.type] = obj
+
+    # Import custom-defined field types
+    for field_type in field_types:
+        if is_valid(field_type):
+            output[field_type.type] = field_type
+
+    return output

nuql/resources/fields/value.py

@@ -0,0 +1,5 @@
+__all__ = ['EmptyValue']
+
+
+class EmptyValue:
+    pass

nuql/resources/records/__init__.py

@@ -0,0 +1,3 @@
+from .validator import *
+from .serialiser import *
+from .projections import *

nuql/resources/records/projections.py

@@ -0,0 +1,49 @@
+from typing import Any, Dict
+
+from nuql import resources, types
+from nuql.fields import Key, String
+
+
+class Projections:
+    def __init__(self, parent: 'resources.Table', serialiser: 'resources.Serialiser') -> None:
+        """
+        Helper for handling projected fields.
+
+        :arg parent: Parent Table instance.
+        :arg serialiser: Serialiser instance.
+        """
+        self.parent = parent
+        self.serialiser = serialiser
+        self._store = {}
+
+    def add(self, name: str, value: Any) -> None:
+        """
+        Adds a projection to the store.
+
+        :arg name: Projected field name.
+        :arg value: Value to project.
+        """
+        field = self.serialiser.get_field(name)
+
+        for key in field.projected_from:
+            if key not in self._store:
+                self._store[key] = {}
+            self._store[key][name] = value
+
+    def merge(self, data: Dict[str, Any], action: 'types.SerialisationType', validator: 'resources.Validator') -> None:
+        """
+        Merges serialised projections into the record.
+
+        :arg data: Current serialised record.
+        :arg action: Serialisation type.
+        :arg validator: Validator instance.
+        """
+        key_fields = {
+            key: field
+            for key, field in self.parent.fields.items()
+            if isinstance(field, Key) or (isinstance(field, String) and field.is_template)
+        }
+
+        for key, field in key_fields.items():
+            projections = self._store.get(key, {})
+            data[key] = field(projections, action, validator)

nuql/resources/records/serialiser.py

@@ -0,0 +1,144 @@
+from typing import Dict, Any, Optional, Union
+
+import nuql
+from nuql import resources, types, fields
+
+
+class Serialiser:
+    def __init__(self, parent: Union['resources.Table', 'fields.Map']) -> None:
+        """
+        Helper object to serialise a record.
+
+        :arg parent: Parent Table or Map.
+        """
+        self.parent = parent
+
+    def get_field(self, key: str) -> 'resources.FieldBase':
+        """
+        Get a field instance from the schema.
+
+        :arg key: Field key.
+        :return: FieldBase instance.
+        """
+        if key not in self.parent.fields:
+            raise nuql.NuqlError(
+                code='FieldNotFound',
+                message=f'Field \'{key}\' is not defined in the schema.'
+            )
+        return self.parent.fields[key]
+
+    def serialise(
+            self,
+            action: 'types.SerialisationType',
+            data: Dict[str, Any] | None = None,
+            validator: Optional['resources.Validator'] = None
+    ):
+        """
+        Serialises/marshals a record based on the data provided.
+
+        :arg action: Serialisation type.
+        :param data: Data to serialise.
+        :param validator: Validator instance.
+        :return:
+        """
+        validator = resources.Validator() if validator is None else validator
+        projections = resources.Projections(self.parent, self)
+        output = {}
+
+        # Serialise provided fields
+        for key, deserialised_value in data.items():
+            field = self.get_field(key)
+
+            if not field:
+                raise nuql.NuqlError(
+                    code='SchemaError',
+                    message=f'Field \'{key}\' is not defined in the schema.'
+                )
+
+            # Skip serialisation for projected fields as this is to be handled at
+            # the end of the serialisation process
+            if field.projected_from:
+                projections.add(key, deserialised_value)
+            else:
+                serialised_value = field(deserialised_value, action, validator)
+                output[key] = serialised_value
+
+        # Serialise fields not provided (i.e. could have defaults)
+        untouched = {name: field for name, field in self.parent.fields.items() if name not in data}
+        for name, field in untouched.items():
+            if field.projects_fields:
+                continue
+
+            if field.projected_from:
+                continue
+
+            serialised_value = field(resources.EmptyValue(), action, validator)
+            output[name] = serialised_value
+
+        # Set projections
+        projections.merge(output, action, validator)
+
+        if action in ['create', 'update', 'write']:
+            validator.raise_for_validation_errors()
+
+        return output
+
+    def serialise_key(self, key: Dict[str, Any], index_name: str = 'primary') -> Dict[str, Any]:
+        """
+        Serialises the key for an item on a given index.
+
+        :arg key: Key to serialise.
+        :param index_name: Index name to serialise key for.
+        :return: Serialised key.
+        """
+        # Check parent is of a valid type
+        if not isinstance(self.parent, resources.Table):
+            raise nuql.NuqlError(
+                code='InvalidTable',
+                message='Serialisation of keys is only supported for Table resources.'
+            )
+
+        # Get applicable index
+        if index_name == 'primary':
+            index = self.parent.indexes.primary
+        else:
+            index = self.parent.indexes.get_index(index_name)
+
+        # Serialise provided data according the the schema
+        serialised_key = self.serialise('query', key)
+
+        # Produce a key from the serialised result and for the given index
+        return {
+            key: value
+            for key, value in serialised_key.items()
+            if key == index['hash'] or ('sort' not in index or key == index['sort'])
+        }
+
+    def deserialise(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Deserialises/unmarshalls data from DynamoDB.
+
+        :arg data: Data to deserialise.
+        :return: Deserialised data.
+        """
+        record = {}
+
+        for name, field in self.parent.fields.items():
+            # Special Case: string templates
+            if hasattr(field, 'deserialise_template') and getattr(field, 'is_template', True):
+                deserialised_value = field.deserialise_template(data.get(name))
+            else:
+                deserialised_value = field.deserialise(data.get(name))
+
+            if field.projected_from:
+                continue
+
+            # Directly set field
+            record[name] = deserialised_value
+
+            # Handle projected fields
+            if field.projects_fields:
+                for projected_key in field.projects_fields:
+                    record[projected_key] = deserialised_value.get(projected_key)
+
+        return record

nuql/resources/records/validator.py

@@ -0,0 +1,48 @@
+__all__ = ['Validator']
+
+import nuql
+
+
+class Validator:
+    def __init__(self, parent: 'Validator' = None, path: str | None = None) -> None:
+        """
+        Validation helper class to pick up serialisation errors.
+
+        :param parent: Parent Validator instance if applicable.
+        :param path: Path (where nested).
+        """
+        self.parent = parent
+        self.path = path
+        self.children = []
+        self._errors = []
+
+    @property
+    def errors(self):
+        """Recursively provide errors."""
+        return [*self._errors, *[x.errors for x in self.children]]
+
+    def spawn_new(self, path: str) -> 'Validator':
+        """
+        Spawns a new validator instance for nested validation.
+
+        :arg path: Path of new validator.
+        :return: Validator instance.
+        """
+        full_path = self.path + '.' + path if self.path else path
+        validator = Validator(parent=self, path=full_path)
+        self.children.append(validator)
+        return validator
+
+    def add(self, name: str, message: str) -> None:
+        """
+        Adds a validation error.
+
+        :arg name: Field name.
+        :arg message: Error message.
+        """
+        self._errors.append({'name': self.path + '.' + name if self.path else name, 'message': message})
+
+    def raise_for_validation_errors(self):
+        """Raises a ValidationError exception if there are any errors."""
+        if self._errors:
+            raise nuql.ValidationError(self.errors)

nuql/resources/tables/__init__.py

@@ -0,0 +1,2 @@
+from .indexes import *
+from .table import *

nuql/resources/tables/indexes.py

@@ -0,0 +1,140 @@
+__all__ = ['Indexes']
+
+from typing import Dict, Any, cast
+
+import nuql
+from nuql import types
+
+
+MAX_LSI = 5
+MAX_GSI = 20
+
+
+class Indexes:
+    def __init__(self, indexes: 'types.IndexesType') -> None:
+        """
+        Wrapper class to validate and use indexes for the overall table.
+
+        :arg indexes: List of indexes.
+        """
+        self.index_keys = set()
+        self._indexes = self.validate_indexes(indexes)
+
+    @property
+    def primary(self) -> 'types.PrimaryIndex':
+        """Retrieve the primary index for the table"""
+        return cast(types.PrimaryIndex, self._indexes['primary'])
+
+    def validate_indexes(self, indexes: 'types.IndexesType') -> Dict[str, Dict[str, Any]]:
+        """
+        Processes, validates and generates index dict for the table.
+
+        :arg indexes: List of indexes.
+        :return: Index dict.
+        """
+        index_dict = {}
+
+        local_count = 0
+        global_count = 0
+
+        if not isinstance(indexes, list):
+            raise nuql.NuqlError(code='IndexValidation', message='Indexes must be a list')
+
+        for index in indexes:
+            if not isinstance(index, dict):
+                raise nuql.NuqlError(code='IndexValidation', message='Indexes must be a list of dicts')
+
+            if 'hash' not in index:
+                raise nuql.NuqlError(code='IndexValidation', message='\'hash\' is required for all indexes')
+
+            index_name = index.get('name', 'primary')
+            self.index_keys.add(index['hash'])
+
+            if 'sort' in index:
+                self.index_keys.add(index['sort'])
+
+            # Validate only one primary index
+            if index_name == 'primary' and 'primary' in index_dict:
+                raise nuql.NuqlError(
+                    code='IndexValidation',
+                    message='More than one primary index cannot be defined. Did you mean to add \'name\' and \'type\'?'
+                )
+
+            # Validate index has a type set
+            if index_name != 'primary' and index.get('type') not in ['local', 'global']:
+                raise nuql.NuqlError(
+                    code='IndexValidation',
+                    message='Index type is required for all indexes except the primary index'
+                )
+
+            # Set index follow rule
+            if index_name != 'primary' and 'follow' in index and not isinstance(index['follow'], bool):
+                raise nuql.NuqlError(
+                    code='IndexValidation',
+                    message='Index \'follow\' must be a boolean value if provided.'
+                )
+
+            # Validate index projection
+            if index_name != 'primary' and 'projection' in index and index['projection'] not in ['all', 'keys']:
+                raise nuql.NuqlError(
+                    code='IndexValidation',
+                    message='Index \'projection\' must be \'all\' or \'keys\' if provided.'
+                )
+
+            # Count LSIs
+            if index.get('type') == 'local':
+                local_count += 1
+
+            # Count GSIs
+            if index.get('type') == 'global':
+                global_count += 1
+
+            accepted_keys = ['hash', 'sort', 'name', 'type', 'follow', 'projection']
+            extra_keys = [x for x in index.keys() if x not in accepted_keys]
+            if extra_keys:
+                raise nuql.NuqlError(
+                    code='IndexValidation',
+                    message=f'Index \'{index_name}\' contains invalid keys: {", ".join(extra_keys)}\n\n'
+                            f'Accepted index keys are: {", ".join(accepted_keys)}'
+                )
+
+            index_dict[index_name] = index
+
+        # Throw on more than 5 LSIs
+        if local_count >= MAX_LSI:
+            raise nuql.NuqlError(
+                code='IndexValidation',
+                message='More than 5 local indexes cannot be defined'
+            )
+
+        # Throw on more than 20 GSIs
+        if global_count >= MAX_GSI:
+            raise nuql.NuqlError(
+                code='IndexValidation',
+                message='More than 20 global indexes cannot be defined'
+            )
+
+        return index_dict
+
+    def get_index(self, name: str) -> 'types.SecondaryIndex':
+        """
+        Get a secondary index by name.
+
+        :arg name: Index name.
+        :return: SecondaryIndex dict.
+        """
+        # Throw on accessing primary to keep logical separation
+        if name == 'primary':
+            raise nuql.NuqlError(
+                code='InvalidIndex',
+                message='The primary index cannot be accessed using get_index, please use the primary attribute instead'
+            )
+
+        # Validate index exists
+        if name not in self._indexes:
+            raise nuql.NuqlError(
+                code='InvalidIndex',
+                message=f'Index \'{name}\' is not defined for this DynamoDB table'
+            )
+
+        return cast(types.SecondaryIndex, self._indexes[name])

nuql/resources/tables/table.py

@@ -0,0 +1,151 @@
+__all__ = ['Table']
+
+from typing import Dict, Any, List
+
+import nuql
+from nuql import resources, types, api
+
+
+class Table:
+    def __init__(
+            self,
+            provider: 'nuql.Nuql',
+            name: str,
+            schema: Dict[str, 'types.FieldConfig'],
+            indexes: 'resources.Indexes',
+    ) -> None:
+        """
+        Main Table API for performing actions against a single table.
+
+        :arg provider: Nuql instance.
+        :arg name: Table name.
+        :arg schema: Field schema.
+        :arg indexes: Table indexes.
+        """
+        self.name = name
+        self.provider = provider
+        self.indexes = indexes
+        self.fields = resources.create_field_map(schema, self, provider.fields)
+        self.serialiser = resources.Serialiser(self)
+
+    def query(
+            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.
+        """
+        query = api.Query(self.provider, self)
+        return query.invoke_sync(
+            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,
+        )
+
+    def get(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.
+        """
+        get = api.Get(self.provider, self)
+        return get.invoke_sync(key=key, consistent_read=consistent_read)
+
+    def create(self, data: Dict[str, Any], condition: Dict[str, Any] | None = None) -> Dict[str, Any]:
+        """
+        Create a new item on the table.
+
+        :arg data: Data to create.
+        :param condition: Optional condition expression dict.
+        :return: New item dict.
+        """
+        create = api.Create(self.provider, self)
+        return create.invoke_sync(data=data, condition=condition)
+
+    def delete(
+            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.
+        """
+        delete = api.Delete(self.provider, self)
+        return delete.invoke_sync(key=key, condition=condition)
+
+    def update(
+            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.
+        """
+        update = api.UpdateItem(self.provider, self)
+        return update.invoke_sync(data=data, condition=condition, shallow=shallow)
+
+    def put_item(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.
+        """
+        put = api.PutItem(self.provider, self)
+        return put.invoke_sync(data=data, condition=condition)
+
+    def upsert(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.
+        """
+        upsert = api.Upsert(self.provider, self)
+        return upsert.invoke_sync(data=data, shallow=shallow)
+
+    def batch_get(self, keys: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Performs a batch get operation against the table.
+
+        :arg keys: List of keys to get.
+        :return: Batch get result.
+        """
+        batch_get = api.BatchGet(self.provider, self)
+        return batch_get.invoke_sync(keys=keys)

nuql/resources/utils/__init__.py

@@ -0,0 +1,2 @@
+from .dict import *
+from .validators import *

nuql/resources/utils/dict.py

@@ -0,0 +1,21 @@
+__all__ = ['merge_dicts']
+
+from collections.abc import Mapping
+from typing import Dict, Any
+
+
+def merge_dicts(d1: Dict[str, Any], d2: Dict[str, Any] | Mapping):
+    """
+    Deeply merge two dicts.
+
+    :param d1: First dict.
+    :param d2: Second dict.
+    :return: Merged dict.
+    """
+    result = d1.copy()
+    for k, v in d2.items():
+        if k in result and isinstance(result[k], Mapping) and isinstance(v, Mapping):
+            result[k] = merge_dicts(result[k], v)
+        else:
+            result[k] = v
+    return result