Dynamojo 0.2.0__py3-none-any.whl

dynamojo/__init__.py

@@ -0,0 +1,30 @@
+from .base import DynamojoBase
+from .config import DynamojoConfig, JoinedAttribute
+from .index import (
+    get_indexes,
+    Gsi,
+    Index,
+    IndexList,
+    IndexMap,
+    Lsi,
+    Mutator,
+    TableIndex,
+)
+from .utils import Delta
+
+
+__all__ = [
+    "Delta",
+    "DynamojoBase",
+    "DynamojoConfig",
+    "get_indexes",
+    "Gsi",
+    "Index",
+    "IndexList",
+    "IndexMap",
+    "JoinedAttribute",
+    "Lsi",
+    "Mutator",
+    "TableIndex"
+]
+

dynamojo/base.py

@@ -0,0 +1,543 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+from collections import UserDict
+from copy import deepcopy
+from dataclasses import dataclass
+from logging import getLogger
+from typing import Any, Dict, List, TypeVar, Union
+
+from boto3.dynamodb.conditions import (
+    AttributeBase,
+    ConditionBase,
+    ConditionExpressionBuilder,
+    Attr,
+    Key
+)
+from pydantic import BaseModel, PrivateAttr
+
+from .boto import DYNAMOCLIENT
+from .index import Index, Lsi
+from .config import DynamojoConfig
+from .exceptions import StaticAttributeError, IndexNotFoundError
+from .utils import Delta, TYPE_SERIALIZER, TYPE_DESERIALIZER
+
+
+class DynamojoBase(BaseModel):
+    """A class to use as a base for modeling objects to store in Dynamodb. This class
+    is intended to be inherited by another class, which actually defines the model.
+    """    
+
+    #: All subclasses should override with their own config of the type `:class:dynamojo.config.DynamojoConfig`
+    _config: DynamojoConfig = PrivateAttr()
+    #: Original object
+    _original: DynamojoBase = PrivateAttr()
+
+    def __new__(cls: DynamojoModel, *_: List[Any], **__: Dict[Any, Any]) -> DynamojoModel:
+        if cls is DynamojoBase:
+            raise TypeError(f"{cls} must be subclassed")
+        return super().__new__(cls)
+
+    def __init__(self: DynamojoModel, **kwargs: Dict[str, Any]) -> None:
+
+        """Initialize a new object with any required or optional attributes"""        
+        super().__init__(**kwargs)
+
+        for attr in self._config.joined_attributes:
+            if attr.attribute in self.dict():
+                raise AttributeError(
+                    f"Attribute '{attr}' cannot be declared as a member and a joined field"
+                )
+        for attr in self._config.__index_keys__:
+            if attr in self.dict():
+                raise AttributeError(
+                    f"Attribute {attr} is part of an index and cannot be declared directly. Use IndexMap() and an alias instead"
+                )
+
+        # TODO: Flush out these mutators.
+        for k, v in kwargs.items():
+            if k in self._config.mutators:
+                kwargs[k] = self._mutate_attribute(k, v)
+
+        self._original = deepcopy(self)
+
+    @property
+    def _deepdiff(self):
+        return Delta(new=self, old=self._original, deep=True)
+
+    @property
+    def _diff(self):
+        return Delta(new=self, old=self._original)
+
+    def __getattribute__(self: DynamojoModel, name: str) -> Any:
+        if super().__getattribute__("_config").__joined_attributes__.get(name):
+            return self._generate_joined_attribute(name)
+
+        return super().__getattribute__(name)
+
+    @property
+    def _has_changed(self):
+        return self._deepdiff.hasChanged
+
+    def __setattr__(self: DynamojoModel, field: str, val: Any) -> None:
+        # Mutations should happen first to allow for other dynamic fields to get their updated value
+        if field in self._config.mutators:
+            val = self._mutate_attribute(field, val)
+
+        if field in self._config.__joined_attributes__:
+            raise AttributeError(
+                f"Attribute '{field}' is a joined field and cannot be set directly"
+            )
+
+        if field in self._config.__index_keys__:
+            raise AttributeError(
+                f"Attribute '{field}' is an index key and cannot be set directly. Use IndexMap() to create an alias"
+            )
+
+        # Static fields can only be set once
+        if (
+            field in self._config.static_attributes
+            and hasattr(self, field)
+            and self.__getattribute__(field) != val
+        ):
+            raise StaticAttributeError(f"Attribute '{field}' is immutable.")
+
+        return super().__setattr__(field, val)
+
+    def _db_item(self) -> Dict[str, Any]:
+        """
+        Returns the item exactly as it is in the database. If self._config.store_aliases is False
+        then those aliases will be omitted.
+        """
+        item = {**self.dict(), **self.joined_attributes(), **self.index_attributes()}
+        if not self._config.store_aliases:
+            for attr in self._config.__index_aliases__.values():
+                if attr in item:
+                    del item[attr]
+        return item
+
+    def _generate_joined_attribute(self: DynamojoModel, name: str) -> str:
+        """
+        Takes attribute names defined in self._config.joined_attributes and stores them with the values
+        of the corresponding attributes concatenated by JoinedAttribute.separator.
+        """
+        item = super().__getattribute__("dict")()
+        joiner = super().__getattribute__("_config").__joined_attributes__[name]
+        sources = joiner.fields
+        separator = joiner.separator
+        new_val = [item.get(source, "") for source in sources]
+        return separator.join(new_val)
+
+    @classmethod
+    def _get_index_from_attributes(
+        cls, partitionkey: str = None, sortkey: str = None
+    ) -> Index:
+        """
+        Returns an Index() object based on attributes being passed as arguments.
+        If multiple indexes match then the table index, if matched is returned first. If
+        not the table index then the first match in the list.
+        """
+        for x in cls._config.index_maps:
+            if x.index.name == "table":
+                table_index_map = x
+                break
+        matches = {}
+
+        for mapping in cls._config.index_maps:
+
+            if isinstance(mapping.index, Lsi):
+                pk = table_index_map.partitionkey
+            else:
+                pk = mapping.partitionkey
+
+            if hasattr(mapping, "sortkey"):
+                sk = mapping.sortkey
+            else:
+                sk = None
+
+            if (
+                # If we only had one key specified it HAS to be the partition
+                sortkey is None
+                and partitionkey == pk
+            ) or (
+                partitionkey is not None
+                and sortkey is not None
+                and (
+                    pk == partitionkey
+                    # Catch cases where our key is not composite (yuck!)
+                    and (sk == sortkey or sk is None)
+                )
+            ):
+                matches[mapping.index.name] = mapping.index
+
+        if not matches:
+            raise IndexNotFoundError(
+                "Could not find a suitable index. Either specify a valid index or change the Condition statement"
+            )
+
+        return matches.get("table", list(matches.values())[0])
+
+    @classmethod
+    def _get_raw_condition_expression(
+        self,
+        exp: ConditionBase,
+        index: Union[Index, str] = None,
+        expression_type="KeyConditionExpression",
+    ):
+        """
+        Take a boto3.dynamodb.conditions.ConditionBase object and convert it to a dictionary suitable as the condition expression,
+        expression attribute names, and expression attribute values for an operation using the low-level dynamodb client.
+        This allows usage of boto3.dynamodb.conditions.Condition deconstruction to be used for the sake of automatically selecting
+        indexes.  Placeholder prefixes are replaced so that attribute names and attribute values dicts can be merged together in queries
+        where multiple types of condition expressions are passed.
+        """
+        is_key_condition = expression_type == "KeyConditionExpression"
+        raw_exp = ConditionExpressionBuilder().build_expression(
+            exp, is_key_condition=is_key_condition
+        )
+
+        if is_key_condition:
+            attribute_names = list(raw_exp.attribute_name_placeholders.values())
+            if len(attribute_names) == 1:
+                attribute_names.append(None)
+
+            if isinstance(index, str):
+                index = self.get_index_by_name(index)
+
+            if index is None:
+                index = self._get_index_from_attributes(*attribute_names)
+
+            for placeholder, attr in raw_exp.attribute_name_placeholders.items():
+                if attr == attribute_names[0]:
+                    raw_exp.attribute_name_placeholders[
+                        placeholder
+                    ] = index.partitionkey
+                if len(attribute_names) == 2 and attr == attribute_names[1]:
+                    raw_exp.attribute_name_placeholders[placeholder] = index.sortkey
+
+        for k, v in raw_exp.attribute_value_placeholders.items():
+            raw_exp.attribute_value_placeholders[k] = TYPE_SERIALIZER.serialize(v)
+
+        opts = {
+            "ExpressionAttributeNames": {},
+            "ExpressionAttributeValues": {},
+            expression_type: raw_exp.condition_expression,
+        }
+
+        # We have to do the dance below to keep queries that use KeyConditionExpression
+        # and FilterExpressionfrom having their name/value placeholders clobber each other
+        # when the dicts are merged to for the full query args
+        original_name_prefix = "#n"
+        original_value_prefix = ":v"
+
+        if expression_type == "KeyConditionExpression":
+            new_name_prefix = "#key_name"
+            new_value_prefix = ":key_value"
+            if index.name != "table":
+                opts["IndexName"] = index.name
+
+        elif expression_type == "FilterExpression":
+            new_name_prefix = "#attribute_name"
+            new_value_prefix = ":attribute_value"
+
+        elif expression_type == "ConditionExpression":
+            new_name_prefix = "#condition_attribute_name"
+            new_value_prefix = ":condition_attribute_value"
+
+        else:
+            raise TypeError(
+                "Invalid Condition type. Must be one of KeyConditionExpression, ConditionExpression, or FilterExpression"
+            )
+
+        for key, val in raw_exp.attribute_name_placeholders.items():
+            new_key = key.replace(original_name_prefix, new_name_prefix)
+            opts["ExpressionAttributeNames"][new_key] = val
+            opts[expression_type] = opts[expression_type].replace(key, new_key)
+
+        for key, val in raw_exp.attribute_value_placeholders.items():
+            new_key = key.replace(original_value_prefix, new_value_prefix)
+            opts["ExpressionAttributeValues"][new_key] = val
+            opts[expression_type] = opts[expression_type].replace(key, new_key)
+
+        opts["TableName"] = self._config.table
+        return opts
+
+    @classmethod
+    def _construct_from_db(cls, item: Dict) -> DynamojoModel:
+        """
+        Rehydrates an object from an item out of the DB.
+        """
+        item = cls._deserialize_dynamo(item)
+        res = {}
+
+        for attr, val in item.items():
+            if not (
+                attr in cls._config.__index_keys__
+                or attr in cls._config.__joined_attributes__
+            ):
+                res[attr] = val
+
+        if not cls._config.store_aliases:
+            for index, alias in cls._config.__index_aliases__.items():
+                res[alias] = item[index]
+
+        return cls.construct(**(res))
+
+    def delete(self) -> None:
+        """
+        Deletes an item from the table
+        """
+        key = {
+            self._config.indexes.table.partitionkey: self.__index_values__[
+                self._config.indexes.table.partitionkey
+            ]
+        }
+
+        if self._config.indexes.table.is_composite:
+            key[self._config.indexes.table.sortkey] = self.__index_values__[
+                self._config.indexes.table.sortkey
+            ]
+
+        res = self._config.table.delete_item(Key=key)
+
+        return res
+
+    @staticmethod
+    def _deserialize_dynamo(data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Deserializes the results from a low-level boto3 Dynamodb client query/get_item
+        into a standard dictionary.
+        """
+        return {k: TYPE_DESERIALIZER.deserialize(v) for k, v in data.items()}
+
+    @classmethod
+    def fetch(cls, pk: str, sk: str = None, **kwargs: Dict[str, Any]) -> DynamojoModel:
+        """
+        Returns a rehydrated object from the database
+        """
+
+        key = {cls._config.indexes.table.partitionkey: pk}
+
+        if cls._config.indexes.table.sortkey:
+            key[cls._config.indexes.table.sortkey] = sk
+
+        serialized_key = {k: TYPE_SERIALIZER.serialize(v) for k, v in key.items()}
+
+        opts = {"Key": serialized_key, "TableName": cls._config.table, **kwargs}
+
+        res = DYNAMOCLIENT.get_item(**opts)
+
+        if item := res.get("Item"):
+            return cls._construct_from_db(item)
+
+    @classmethod
+    def get_index_by_name(cls, name: str) -> Index:
+        """
+        Accepts a string as a name and returns an Index() object
+        """
+        try:
+            return cls._config.indexes[name]
+        except KeyError:
+            raise IndexNotFoundError(f"Index {name} does not exist")
+
+    def index_attributes(self) -> Dict[str, Any]:
+        """
+        Returns a dict containing index attributes as keys along with their set values
+        """
+        indexes = {}
+        for mapping in self._config.index_maps:
+            if hasattr(mapping, "partitionkey"):
+                indexes[mapping.index.partitionkey] = self.__getattribute__(
+                    mapping.partitionkey
+                )
+            if hasattr(mapping, "sortkey"):
+                indexes[mapping.index.sortkey] = self.__getattribute__(mapping.sortkey)
+        return indexes
+
+    def item(self) -> Dict[str, Any]:
+        """
+        Returns a dict that contains declared attributes and attributes dynamically generated
+        by self._config.joined_attributes
+        """
+        return {**self.dict(), **self.joined_attributes()}
+
+    def joined_attributes(self) -> Dict[str, str]:
+        """
+        Returns a dict of attributes created dynamically by self._config.joined_attributes
+        """
+        return {
+            attr: self.__getattribute__(attr) for attr in self._config.__joined_attributes__
+        }
+
+    @classmethod
+    def _mutate_attribute(cls, field: str, val: Any) -> Any:
+        """
+        Returns the mutated value using the callable specified in cls._config.mutators for
+        an attribute.
+        """
+        return super().__setattr__(
+            field, cls._config.mutators[field].callable(field, val, cls)
+        )
+
+    def _prepare_db_item(self):
+        """
+        Serializes self.item() for storage in the database using the low-level dynamodb client.
+        """
+        item = {
+            k: TYPE_SERIALIZER.serialize(v)
+            for k, v in self._db_item().items()
+        }
+
+        if not self._config.store_aliases:
+            for alias in self._config.__index_aliases__.values():
+                if alias in item:
+                    del item[alias]
+
+        return  item
+
+    @classmethod
+    def query(
+        cls,
+        KeyConditionExpression: ConditionBase,
+        Index: Union[Index, str] = None,
+        FilterExpression: AttributeBase = None,
+        Limit: int = 1000,
+        ExclusiveStartKey: dict = None,
+        result_type: str = "standard",
+        **kwargs: Dict[str, Any],
+    ) -> QueryResults:
+        """
+        Runs a Dynamodb query using a condition from db.Index. The kwargs argument can be any
+        boto3.client("dynamodb").query() argument that is not explicitely defined in the signature.
+        """
+
+        if result_type not in ("standard", "deserialized", "raw"):
+            raise ValueError("Argument 'result_type' must be one of standard, raw, or deserialized")
+
+        opts = {**kwargs, "Limit": Limit}
+
+        opts.update(
+            cls._get_raw_condition_expression(exp=KeyConditionExpression, index=Index)
+        )
+
+        if FilterExpression is not None:
+            filter_opts = cls._get_raw_condition_expression(
+                exp=FilterExpression, expression_type="FilterExpression"
+            )
+            opts["ExpressionAttributeNames"].update(
+                filter_opts.pop("ExpressionAttributeNames")
+            )
+            opts["ExpressionAttributeValues"].update(
+                filter_opts.pop("ExpressionAttributeValues")
+            )
+            opts.update(filter_opts)
+
+        if ExclusiveStartKey is not None:
+            opts["ExclusiveStartKey"] = ExclusiveStartKey
+
+        msg = (
+            f"Querying with index `{opts['IndexName']}`"
+            if opts.get("IndexName")
+            else "Querying with table index"
+        )
+
+        getLogger().info(msg)
+
+        res = DYNAMOCLIENT.query(**opts)
+        
+        res["Items"] = [cls._construct_from_db(item) for item in res["Items"]]
+        return QueryResults(**res)
+
+    def save(
+        self, ConditionExpression: ConditionBase = None, fail_on_exists: bool = True, **kwargs: Dict[str, Any]
+    ) -> None:
+        """
+        Stores our item in Dynamodb
+        """
+
+        table_pk = self._config.indexes.table.partitionkey
+        table_sk = self._config.indexes.table.sortkey
+
+
+        item = self._prepare_db_item()
+
+        opts = {"TableName": self._config.table, "Item": item, **kwargs}
+
+        if ConditionExpression:
+            exp = self._get_raw_condition_expression(
+                ConditionExpression, expression_type="ConditionExpression"
+            )
+            opts.update(exp)
+
+        if fail_on_exists:
+            sk_expression = f"attribute_not_exists({table_sk})"
+            pk_expression = f"attribute_not_exists({table_pk})"
+            fail_expression = f"({pk_expression} AND {sk_expression}) " if table_sk is not None else pk_expression
+            if ConditionExpression:
+                opts["ConditionExpression"] = f"{fail_expression} AND {opts['ConditionExpression']}"
+            else:
+                opts["ConditionExpression"] = fail_expression
+
+        return DYNAMOCLIENT.put_item(**opts)
+
+    def update(self, **opts):
+        diff = self._deepdiff
+
+        if not diff.hasChanged:
+            return None
+
+        pk_name = self._config.indexes.table.partitionkey
+        sk_name = self._config.indexes.table.sortkey
+        if (
+            pk_name in diff.keys
+            or sk_name in diff.keys
+        ):
+            raise AttributeError("Cannot update table key attributes. Use `self.save()` instead.")
+
+        attribute_names = {}
+        attribute_values = {}
+        set_statement_items = []
+        del_statement_items = []
+        set_items = {**diff.added, **diff.changed}
+        key = {
+            pk_name: TYPE_SERIALIZER.serialize(self._db_item()[pk_name])
+        }
+        if sk_name is not None:
+            key[sk_name] = TYPE_SERIALIZER.serialize(self._db_item()[sk_name])
+
+        for attr, val in self._db_item().items():
+            if attr in diff.keys:
+                attribute_names[f"#{attr}"] = attr
+                attribute_values[f":{attr}"] = val
+                if attr in set_items.keys():
+                    statement = f"#{attr} = :{attr}"
+                    set_statement_items.append(statement)
+                else:
+                    del_statement_items.append(statement)
+
+        set_statement = f"SET {', '.join(set_statement_items)}" if set_statement_items else ""
+        del_statement = f"REMOVE {', '.join(del_statement_items)}" if del_statement_items else ""
+
+        opts["TableName"] = self._config.table
+        opts["Key"] = key
+        opts["ExpressionAttributeNames"] = attribute_names
+        opts["ExpressionAttributeValues"] = {
+            k: TYPE_SERIALIZER.serialize(v)
+            for k, v in attribute_values.items()
+        }
+
+        opts["UpdateExpression"] = f"{set_statement} {del_statement}"
+        DYNAMOCLIENT.update_item(**opts)
+        return self
+
+@dataclass
+class QueryResults(UserDict):
+    Items: List[DynamojoModel]
+    Count: int
+    ResponseMetadata: Dict[str, Any]
+    ScannedCount: int
+    LastEvaluatedKey: Dict[str, Dict[str, Any]] = None
+    ConsumedCapacity: Dict[str, Any] = None
+
+
+DynamojoModel = TypeVar("DynamojoModel", bound=DynamojoBase)
+

dynamojo/boto.py

@@ -0,0 +1,4 @@
+from boto3 import Session
+
+Session = Session()
+DYNAMOCLIENT = Session.client("dynamodb")

dynamojo/config.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+from typing import Union, Callable, List, Dict
+
+from pydantic import BaseModel, PrivateAttr
+
+from .index import IndexList, IndexMap, Mutator
+
+class JoinedAttribute(BaseModel):
+    attribute: str
+    fields: List[str]
+    separator: str = "~"
+
+
+class DynamojoConfig(BaseModel):
+    # A dictionary in the form of {"<target attribute>": ["source_att_one", "source_att_two"]} where <target_attribute> will
+    # automatically be overwritten by the attributes of it's corresponding list being joined with '~'. This is useful for creating
+    # keys that can be queried over using Key().begins_with() or Key().between() by creating a means to filter based on the compounded
+    # attributes.
+    joined_attributes: List[JoinedAttribute]
+    __joined_attributes__: Dict = {}
+
+    # A list of database `Index` objects from `dynamojo.indexes.get_indexes()``
+    indexes: IndexList
+
+    # A list of `IndexMap` objects used to map arbitrary fields into index attributes
+    index_maps: List[IndexMap] = []
+
+    static_attributes: List[str] = []
+
+    # A Dynamodb table name
+    table: str
+
+    mutators: List[Mutator] = []
+
+    # If set to False then attributes that are aliases of indexes will be stripped
+    # out before storing in the db
+    store_aliases: bool = True
+
+    underscore_attrs_are_private: bool = True
+
+    # Dict of `index key: alias name`
+    __index_aliases__: dict = PrivateAttr(default={})
+
+    __index_keys__: List[str] = PrivateAttr(default={})
+
+    class Config:
+        underscore_attrs_are_private: bool = True
+        arbitrary_types_allowed = True
+        extra = "allow"
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+
+        for attr in self.joined_attributes:
+            self.__joined_attributes__[attr.attribute] = attr
+
+        for index_map in self.index_maps:
+            if sk_att := index_map.sortkey:
+                self.__index_aliases__[index_map.index.sortkey] = sk_att
+            if getattr(index_map, "partitionkey", None):
+                self.__index_aliases__[
+                    index_map.index.partitionkey
+                ] = index_map.partitionkey
+
+        self.__index_keys__ = list(set(self.__index_aliases__.keys()))

dynamojo/exceptions.py

@@ -0,0 +1,30 @@
+class DynamodbException(Exception):
+    pass
+
+
+class RequiredAttributeError(DynamodbException):
+    pass
+
+
+class StaticAttributeError(DynamodbException):
+    pass
+
+
+class UnknownAttributeError(DynamodbException):
+    pass
+
+
+class ProtectedAttributeError(DynamodbException):
+    pass
+
+
+class ItemNotFoundError(DynamodbException):
+    pass
+
+
+class NotAuthorized(DynamodbException):
+    pass
+
+
+class IndexNotFoundError(DynamodbException):
+    pass

dynamojo/index.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3.8
+from collections import UserDict
+from typing import List, Callable, Any
+
+from pydantic import BaseModel
+
+from .boto import DYNAMOCLIENT
+
+
+class Mutator(BaseModel):
+    source: str
+    callable: Callable[[str, Any, object], Any]
+
+    class Config:
+        frozen = True
+        arbitrary_types_allowed: True
+
+
+class Index:
+    """
+    Used as a factory for creating objects that can generate KeyConditionExpressions and abstract the
+    partion/sort key names from the developer using them.
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        sortkey: str,
+        partitionkey: str = None,
+    ) -> None:
+
+        self.__partitionkey = partitionkey if partitionkey else None
+        self.__sortkey = sortkey if sortkey else None
+        self.__name = name
+        self.is_composite = partitionkey and sortkey
+
+    @property
+    def partitionkey(self) -> str:
+        """The partition key of the index as Key(partition key name)"""
+        return self.__partitionkey
+
+    @property
+    def sortkey(self) -> str:
+        """The sort key of the index as Key(sort key name)"""
+        return self.__sortkey
+
+    @property
+    def table_index(self) -> bool:
+        """Whether or not this index is the table index"""
+        return isinstance(self, TableIndex)
+
+    @property
+    def name(self) -> str:
+        """Name of the index"""
+        return self.__name
+
+
+class Gsi(Index):
+    def __init__(self, name: str, partitionkey: str, sortkey: str = None) -> None:
+        super().__init__(name=name, sortkey=sortkey, partitionkey=partitionkey)
+
+
+class Lsi(Index):
+    def __init__(self, name: str, sortkey: str) -> None:
+        super().__init__(name=name, sortkey=sortkey)
+
+
+class TableIndex(Index):
+    def __init__(self, name: str, partitionkey: str, sortkey: str = None) -> None:
+        super().__init__(name=name, partitionkey=partitionkey, sortkey=sortkey)
+
+
+class IndexList(UserDict):
+    def __init__(self, *args: List[Index]) -> None:
+        super().__init__()
+        has_table = False
+        for index in args:
+            if not isinstance(index, Index):
+                raise TypeError("Invalid type for Index")
+            if isinstance(index, TableIndex):
+                if has_table:
+                    raise ValueError("An IndexList object can only have one TableIndex")
+                has_table = True
+
+            super().__setattr__(index.name, index)
+            self.data[index.name] = index
+
+
+def get_indexes(table_name: str) -> IndexList:
+
+    desc = DYNAMOCLIENT.describe_table(TableName=table_name)["Table"]
+    gsi_list = desc.get("GlobalSecondaryIndexes", [])
+    lsi_list = desc.get("LocalSecondaryIndexes", [])
+
+    table_list = [{"IndexName": "table", "KeySchema": desc["KeySchema"]}]
+
+    def build_indexes(index_type, index_list):
+        index_objects = []
+        for index in index_list:
+            args = {}
+            args["name"] = index["IndexName"]
+
+            for attr in index["KeySchema"]:
+                if attr["KeyType"] == "HASH" and index_type != Lsi:
+                    args["partitionkey"] = attr["AttributeName"]
+                elif attr["KeyType"] == "RANGE":
+                    args["sortkey"] = attr["AttributeName"]
+
+            index_objects.append(index_type(**args))
+
+        return index_objects
+
+    indexes = IndexList(
+        *[
+            *build_indexes(Gsi, gsi_list),
+            *build_indexes(Lsi, lsi_list),
+            *build_indexes(TableIndex, table_list),
+        ]
+    )
+    return indexes
+
+
+class IndexMap:
+    index: Index
+    pk: str
+    sk: str = None
+
+    def __init__(
+        self, index: Index, partitionkey: str = None, sortkey: str = None
+    ) -> None:
+        if isinstance(index, Lsi) and partitionkey:
+            raise ValueError(
+                "Lsi indexes only specify a sort key and use the table's partition key"
+            )
+
+        elif index.partitionkey and not partitionkey:
+            raise ValueError(f"Partition key required for index {index.name}")
+
+        if index.sortkey and not sortkey:
+            raise ValueError(f"Sort key required for index {index.name}")
+
+        if sortkey and not index.sortkey:
+            raise ValueError(f"Index {index.name} requires a sort key")
+
+        if partitionkey:
+            self.partitionkey = partitionkey
+
+        if sortkey:
+            self.sortkey = sortkey
+
+        self.index = index

dynamojo/utils.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+from pydantic import BaseModel, PrivateAttr
+from typing import (
+  TYPE_CHECKING,
+  Any,
+  Dict,
+  NamedTuple
+)
+
+
+if TYPE_CHECKING:
+  from .base import DynamojoBase
+else:
+  DynamojoBase = object
+
+from boto3.dynamodb.types import TypeSerializer, TypeDeserializer
+
+
+TYPE_SERIALIZER = TypeSerializer()
+TYPE_DESERIALIZER = TypeDeserializer()
+
+Change = NamedTuple("Change", [("old", Any), ("new", Any)])
+Diff = NamedTuple("Diff", (("added", Dict[str, Any]), ("removed", Dict[str, Any]), ("changed", Dict[str, Any])))
+
+
+class Delta(BaseModel):
+  old: DynamojoBase = None
+  new: DynamojoBase = None
+
+  _deep: bool = PrivateAttr()
+  _old: Dict[str, Any] = PrivateAttr()
+  _new: Dict[str, Any] = PrivateAttr()  
+
+  def __init__(self, deep=True, **kwargs):
+    self._deep = deep
+    super().__init__(**kwargs)
+
+    if deep:
+      self._old = self.old._db_item()
+      self._new = self.new._db_item()
+    else:
+      self._old = self.old.item()
+      self._new = self.new.item()
+
+
+  @property
+  def delta(self) -> Diff:
+    diff = Diff({}, {}, {})
+
+    for key, val in self._old.items():
+        if key not in self._new:
+          diff.removed[key] = val
+        if key in self._new and val != self._new[key]:
+          diff.changed[key] = Change(
+            self._old[key],
+            self._new[key]
+          )
+
+    for key, val in self._new.items():
+        if key not in self._old:
+          diff.added[key] = val
+
+    return diff
+
+  @property
+  def added(self) -> Dict[str, Any]:
+    return self.delta.added
+  
+  @property
+  def changed(self) -> Change:
+    return self.delta.changed
+
+  @property
+  def removed(self) -> Dict[str, Any]:
+    return self.delta.removed 
+
+  @property
+  def hasChanged(self):
+      return not self._old == self._new
+
+  @property
+  def keys(self):
+    return {
+      **self.added,
+      **self.removed,
+      **self.changed
+    }.keys()

dynamojo-0.2.0.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.1
+Name: Dynamojo
+Version: 0.2.0
+Summary: A cli client for accessing AWS secrets
+Home-page: https://github.com/mathewmoon/dynamojo
+Author: Mathew Moon
+Author-email: me@mathewmoon.net
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.4
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: boto3 (>=1.34.56,<2.0.0)
+Requires-Dist: pydantic (<2.0)
+Project-URL: Repository, https://github.com/mathewmoon/dynamojo
+Description-Content-Type: text/markdown
+
+# Dynamojo
+## Because one table is better than more
+
+Dynamojo takes the concept of Dynamodb Single Table design and creates a modeling framework for it. This library is opinionated in the following ways:
+- Indexes should be generic. They could mean different things for different types of items. **An index attribute shouldn't imply that it is always a date, color, etc**.
+- When using generic indexes the attributes should shadow a human readable attribute. For instance if you have a partition key named "pk" that for items that represent users stores their  userid, then there should also be an attribute named userid.
+- When creating models for item types that will be stored in the database the developer should only have to worry about their access patterns in terms of the human readable attributes, not be in the weeds of the index design of the table. Mapping items to indexes should happen in code, not in the table definition itself
+- Table and Global Secondary indexes should always define a sortkey. There is no reason not to. It's better to have it in cases where you don't need it than to need it and not have it.
+
+Dynamojo is built on top of Pydantic with some bells and whistles:
+- put, update, delete, and query db objects
+- Dynamically map attributes to the index of your choice. EG: attribute "userId" automatically populates the partition key named "pk"
+- Dynamically join attributes into another using a delimiter. For instance create a field that is `<userid>~<date>~<action>` to use as a sort key for fast queries
+- Mutate attributes when set
+- Create models that subclass other models. A common pattern is to define a base class for your project that has a baseline of methods that you will need other than db operations. Different item types would then be created as models that are subclasses from the base class. See test.py
+- Flag attributes as immutable so they can't be modified once set
+- Use all of the features of `put_item()`, `query()`, `delete()`, and `update()` that you normally could with `boto3.client("dynamodb")`
+
+### Limitations:
+- Dynamojo doesn't do scans because scans are dumb. I will die on the hill of defending that statement.
+- If you have so much data that replicating indexed data into human readable columns is too expensive then this library may not be for you. But if you have that much data you should have a staff of engineers that can write your own library.
+
+
+
+### See test.py for examples
+
+This library is very opinionated about how the table's indexes should be structured. Below is Terraform that shows the
+correct way to set up the table. Index keys are never referenced directly when using the table. Rely on IndexMap for that.
+Since LSI's can only be created at table creation time, and all indexes cost nothing if not used, we go ahead and create
+all of the indexes that AWS will allow us to when the table is created.
+
+```hcl
+resource "aws_dynamodb_table" "test_table" {
+  name         = "test-dynamojo"
+  hash_key     = "pk"
+  range_key    = "sk"
+  billing_mode = "PAY_PER_REQUEST"
+
+  # LSI attributes
+  dynamic "attribute" {
+    for_each = range(5)
+
+    content {
+      name = "lsi${attribute.value}_sk"
+      type = "S"
+    }
+  }
+
+  # GSI pk attributes
+  dynamic "attribute" {
+    for_each = range(20)
+
+    content {
+      name = "gsi${attribute.value}_pk"
+      type = "S"
+    }
+  }
+
+  # GSI sk attributes
+  dynamic "attribute" {
+    for_each = range(20)
+
+    content {
+      name = "gsi${attribute.value}_sk"
+      type = "S"
+    }
+  }
+
+  attribute {
+    name = "pk"
+    type = "S"
+  }
+
+  attribute {
+    name = "sk"
+    type = "S"
+  }
+
+  # GSI's
+  dynamic "global_secondary_index" {
+    for_each = range(20)
+
+    content {
+      name            = "gsi${global_secondary_index.value}"
+      hash_key        = "gsi${global_secondary_index.value}_pk"
+      range_key       = "gsi${global_secondary_index.value}_sk"
+      projection_type = "ALL"
+    }
+  }
+
+  # LSI's
+  dynamic "local_secondary_index" {
+    for_each = range(5)
+
+    content {
+      name            = "lsi${local_secondary_index.value}"
+      range_key       = "lsi${local_secondary_index.value}_sk"
+      projection_type = "ALL"
+    }
+  }
+}
+```

dynamojo-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+dynamojo/__init__.py,sha256=bILBw1CxIisxMiMPhNF_m6PxGA9hYwam7MKIed2Pljg,449
+dynamojo/base.py,sha256=ImPBdgcVIEojoJfvjgwnobn9rAtsNLmPa3CJ96oZnyM,19880
+dynamojo/boto.py,sha256=VtrXAHyts0y4nCI7fo8BuowQE9qCoVZ9KJ1ZHXvmysQ,89
+dynamojo/config.py,sha256=dFfMJpYUQ4gRPvsS_EVpgoEPmRz0UglO9wwTMlfx2aE,2212
+dynamojo/exceptions.py,sha256=PL9LkviDckaBZOQUq-2tYG4hPyfHr623eK9UjnICMM0,445
+dynamojo/index.py,sha256=lV8GIWyHBFQh6zMZZxVJPHOBRi_ue2XqqPwq97Wc_zo,4406
+dynamojo/utils.py,sha256=QzsNIdVzfOd-Y8Zn4Zti07a-i71WNOup-v_ZCNsJRwk,1882
+dynamojo-0.2.0.dist-info/METADATA,sha256=JhAXHv-lBAu8AdqJKQ08PY-amdBfSoMFXsJf2oqw700,5159
+dynamojo-0.2.0.dist-info/WHEEL,sha256=IrRNNNJ-uuL1ggO5qMvT1GGhQVdQU54d6ZpYqEZfEWo,92
+dynamojo-0.2.0.dist-info/RECORD,,

dynamojo-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py2.py3-none-any