boto3-assist 0.32.0__tar.gz → 0.33.0__tar.gz

{boto3_assist-0.32.0 → boto3_assist-0.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boto3_assist
-Version: 0.32.0
+Version: 0.33.0
 Summary: Additional boto3 wrappers to make your life a little easier
 Author-email: Eric Wilson <boto3-assist@geekcafe.com>
 License-File: LICENSE-EXPLAINED.txt

{boto3_assist-0.32.0 → boto3_assist-0.33.0}/pyproject.toml

@@ -15,7 +15,7 @@ addopts = "-m 'not integration'"
 
 [project]
 name = "boto3_assist"
-version = "0.32.0"
+version = "0.33.0"
 
 authors = [
   { name="Eric Wilson", email="boto3-assist@geekcafe.com" }

{boto3_assist-0.32.0 → boto3_assist-0.33.0}/src/boto3_assist/dynamodb/dynamodb_model_base.py

@@ -6,11 +6,12 @@ MIT License.  See Project Root for the license information.
 
 from __future__ import annotations
 import datetime as dt
+from enum import Enum
 
 # import decimal
 # import inspect
 # import uuid
-from typing import TypeVar, List, Dict, Any
+from typing import TypeVar, List, Dict, Any, Set
 from boto3.dynamodb.types import TypeSerializer, TypeDeserializer
 from boto3_assist.utilities.serialization_utility import Serialization
 from boto3_assist.utilities.decimal_conversion_utility import DecimalConversionUtility
@@ -25,6 +26,37 @@ from boto3_assist.models.serializable_model import SerializableModel
 from boto3_assist.utilities.string_utility import StringUtility
 
 
+class MergeStrategy(Enum):
+    """Strategy for merging updates into an existing model."""
+
+    NON_NULL_WINS = "non_null_wins"
+    """Only overwrite if the update value is not None (default, most common)."""
+
+    UPDATES_WIN = "updates_win"
+    """Update values always win, even if None."""
+
+    EXISTING_WINS = "existing_wins"
+    """Only fill in fields that are currently None in the existing model."""
+
+
+class _ClearFieldSentinel:
+    """Sentinel class to explicitly mark a field for clearing to None."""
+
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "CLEAR_FIELD"
+
+
+# Singleton sentinel value - use this to explicitly clear a field to None
+CLEAR_FIELD = _ClearFieldSentinel()
+
+
 def exclude_from_serialization(method):
     """
     Decorator to mark methods or properties to be excluded from serialization.
@@ -179,6 +211,80 @@ class DynamoDBModelBase(SerializableModel):
         # attempt to map it
         return DynamoDBSerializer.map(source=item, target=self)
 
+    def merge(
+        self: T,
+        updates: Dict[str, Any] | DynamoDBModelBase | None,
+        strategy: MergeStrategy = MergeStrategy.NON_NULL_WINS,
+        include_fields: Set[str] | List[str] | None = None,
+        exclude_fields: Set[str] | List[str] | None = None,
+    ) -> T:
+        """
+        Merge updates into this instance based on the specified strategy.
+
+        Unlike map() which overwrites all fields, merge() selectively updates
+        fields based on the strategy and handles the common case where you want
+        to apply partial updates from an API request.
+
+        Args:
+            updates: The source of updates - can be a dict or another model instance.
+            strategy: How to handle the merge:
+                - NON_NULL_WINS (default): Only overwrite if update value is not None.
+                  Use CLEAR_FIELD sentinel to explicitly set a field to None.
+                - UPDATES_WIN: Update values always win, even if None.
+                - EXISTING_WINS: Only fill in fields that are currently None.
+            include_fields: If provided, only these fields will be considered for merge.
+            exclude_fields: Fields to exclude from the merge (e.g., 'id', 'created_at').
+
+        Returns:
+            Self with merged updates applied.
+
+        Example:
+            # Load existing from DB
+            existing = Product().map(db_response)
+
+            # Merge partial updates (only non-null fields applied)
+            existing.merge({"name": "New Name", "price": None})  # price unchanged
+
+            # Explicitly clear a field
+            from boto3_assist.dynamodb import CLEAR_FIELD
+            existing.merge({"description": CLEAR_FIELD})  # description set to None
+
+            # Fill gaps only (useful for defaults)
+            existing.merge(defaults, strategy=MergeStrategy.EXISTING_WINS)
+        """
+        if updates is None:
+            return self
+
+        # Convert to dict if needed
+        updates_dict: Dict[str, Any]
+        if isinstance(updates, DynamoDBModelBase):
+            updates_dict = updates.to_resource_dictionary(include_indexes=False)
+        elif isinstance(updates, dict):
+            updates_dict = updates.copy()
+        else:
+            raise ValueError("Updates must be a dictionary or DynamoDBModelBase")
+
+        # Convert decimals if present
+        updates_dict = DecimalConversionUtility.convert_decimals_to_native_types(
+            updates_dict
+        )
+
+        # Apply field filters
+        if include_fields is not None:
+            include_set = set(include_fields)
+            updates_dict = {k: v for k, v in updates_dict.items() if k in include_set}
+
+        if exclude_fields is not None:
+            exclude_set = set(exclude_fields)
+            updates_dict = {
+                k: v for k, v in updates_dict.items() if k not in exclude_set
+            }
+
+        # Apply merge based on strategy
+        return DynamoDBSerializer.merge(
+            updates=updates_dict, target=self, strategy=strategy
+        )
+
     def to_client_dictionary(self, include_indexes: bool = True):
         """
         Convert the instance to a dictionary suitable for DynamoDB client.
@@ -380,3 +486,116 @@ class DynamoDBSerializer:
                 instance_dict[key.sort_key.attribute_name] = key.sort_key.value
 
         return instance_dict
+
+    @staticmethod
+    def merge(updates: Dict[str, Any], target: T, strategy: MergeStrategy) -> T:
+        """
+        Merge updates into the target object based on the specified strategy.
+
+        Args:
+            updates: Dictionary of field updates to apply.
+            target: The target object to merge into.
+            strategy: The merge strategy to use.
+
+        Returns:
+            The target object with updates merged.
+        """
+        for key, update_value in updates.items():
+            if not Serialization.has_attribute(target, key):
+                continue
+
+            current_value = getattr(target, key, None)
+
+            # Handle CLEAR_FIELD sentinel - always clears to None
+            if isinstance(update_value, _ClearFieldSentinel):
+                try:
+                    setattr(target, key, None)
+                except (AttributeError, TypeError):
+                    pass  # Property without setter or type issue
+                continue
+
+            # Apply strategy
+            should_update = False
+
+            if strategy == MergeStrategy.UPDATES_WIN:
+                # Updates always win
+                should_update = True
+
+            elif strategy == MergeStrategy.NON_NULL_WINS:
+                # Only update if the new value is not None
+                should_update = update_value is not None
+
+            elif strategy == MergeStrategy.EXISTING_WINS:
+                # Only update if current value is None
+                should_update = current_value is None
+
+            if should_update:
+                try:
+                    # Handle nested objects/dicts
+                    if (
+                        isinstance(current_value, dict)
+                        and isinstance(update_value, dict)
+                        and strategy != MergeStrategy.UPDATES_WIN
+                    ):
+                        # Recursively merge dicts
+                        DynamoDBSerializer._merge_dict(
+                            current_value, update_value, strategy
+                        )
+                    elif hasattr(current_value, "__dict__") and isinstance(
+                        update_value, dict
+                    ):
+                        # Nested object - recursively merge
+                        DynamoDBSerializer.merge(
+                            updates=update_value,
+                            target=current_value,
+                            strategy=strategy,
+                        )
+                    else:
+                        setattr(target, key, update_value)
+                except (AttributeError, TypeError):
+                    pass  # Property without setter or type issue
+
+        return target
+
+    @staticmethod
+    def _merge_dict(
+        target_dict: Dict[str, Any],
+        updates_dict: Dict[str, Any],
+        strategy: MergeStrategy,
+    ) -> None:
+        """
+        Merge updates into a target dictionary based on strategy.
+
+        Args:
+            target_dict: The dictionary to merge into (modified in place).
+            updates_dict: The dictionary of updates.
+            strategy: The merge strategy to use.
+        """
+        for key, update_value in updates_dict.items():
+            current_value = target_dict.get(key)
+
+            # Handle CLEAR_FIELD sentinel
+            if isinstance(update_value, _ClearFieldSentinel):
+                target_dict[key] = None
+                continue
+
+            should_update = False
+
+            if strategy == MergeStrategy.UPDATES_WIN:
+                should_update = True
+            elif strategy == MergeStrategy.NON_NULL_WINS:
+                should_update = update_value is not None
+            elif strategy == MergeStrategy.EXISTING_WINS:
+                should_update = current_value is None
+
+            if should_update:
+                if (
+                    isinstance(current_value, dict)
+                    and isinstance(update_value, dict)
+                    and strategy != MergeStrategy.UPDATES_WIN
+                ):
+                    DynamoDBSerializer._merge_dict(
+                        current_value, update_value, strategy
+                    )
+                else:
+                    target_dict[key] = update_value

boto3_assist-0.33.0/src/boto3_assist/version.py

@@ -0,0 +1 @@
+__version__ = "0.33.0"

boto3_assist-0.33.0/tests/unit/dynamodb_tests/dynamodb_model_merge_test.py

@@ -0,0 +1,427 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License.  See Project Root for the license information.
+"""
+
+import unittest
+from typing import Optional, Dict, Any
+
+from boto3_assist.dynamodb.dynamodb_model_base import (
+    DynamoDBModelBase,
+    MergeStrategy,
+    CLEAR_FIELD,
+)
+
+
+class SimpleModel(DynamoDBModelBase):
+    """Simple test model for merge testing."""
+
+    def __init__(self):
+        super().__init__()
+        self.id: Optional[str] = None
+        self.name: Optional[str] = None
+        self.description: Optional[str] = None
+        self.price: Optional[float] = None
+        self.quantity: Optional[int] = None
+        self.is_active: Optional[bool] = None
+        self.metadata: Optional[Dict[str, Any]] = None
+
+
+class NestedModel(DynamoDBModelBase):
+    """Model with nested objects for testing deep merge."""
+
+    def __init__(self):
+        super().__init__()
+        self.id: Optional[str] = None
+        self.name: Optional[str] = None
+        self.settings: Dict[str, Any] = {}
+        self.address: Optional[Dict[str, str]] = None
+
+
+class DynamoDBModelMergeTest(unittest.TestCase):
+    """Tests for the merge() method on DynamoDBModelBase."""
+
+    # =========================================================================
+    # NON_NULL_WINS Strategy Tests (Default)
+    # =========================================================================
+
+    def test_merge_non_null_wins_updates_non_null_fields(self):
+        """Non-null values in updates should overwrite existing values."""
+        # Arrange
+        existing = SimpleModel()
+        existing.id = "123"
+        existing.name = "Original Name"
+        existing.description = "Original Description"
+        existing.price = 10.0
+
+        updates = {"name": "Updated Name", "price": 25.0}
+
+        # Act
+        existing.merge(updates)
+
+        # Assert
+        self.assertEqual(existing.name, "Updated Name")
+        self.assertEqual(existing.price, 25.0)
+        self.assertEqual(existing.description, "Original Description")  # unchanged
+        self.assertEqual(existing.id, "123")  # unchanged
+
+    def test_merge_non_null_wins_ignores_none_values(self):
+        """None values in updates should NOT overwrite existing values."""
+        # Arrange
+        existing = SimpleModel()
+        existing.id = "123"
+        existing.name = "Original Name"
+        existing.price = 10.0
+
+        updates = {"name": None, "price": None, "description": "New Description"}
+
+        # Act
+        existing.merge(updates)
+
+        # Assert
+        self.assertEqual(existing.name, "Original Name")  # unchanged
+        self.assertEqual(existing.price, 10.0)  # unchanged
+        self.assertEqual(existing.description, "New Description")  # updated
+
+    def test_merge_non_null_wins_with_clear_field_sentinel(self):
+        """CLEAR_FIELD sentinel should explicitly set field to None."""
+        # Arrange
+        existing = SimpleModel()
+        existing.id = "123"
+        existing.name = "Original Name"
+        existing.description = "Original Description"
+
+        updates = {"description": CLEAR_FIELD}
+
+        # Act
+        existing.merge(updates)
+
+        # Assert
+        self.assertEqual(existing.name, "Original Name")  # unchanged
+        self.assertIsNone(existing.description)  # explicitly cleared
+
+    def test_merge_non_null_wins_fills_none_fields(self):
+        """Updates should fill in fields that are currently None."""
+        # Arrange
+        existing = SimpleModel()
+        existing.id = "123"
+        existing.name = None
+        existing.price = None
+
+        updates = {"name": "New Name", "price": 15.0}
+
+        # Act
+        existing.merge(updates)
+
+        # Assert
+        self.assertEqual(existing.name, "New Name")
+        self.assertEqual(existing.price, 15.0)
+
+    # =========================================================================
+    # UPDATES_WIN Strategy Tests
+    # =========================================================================
+
+    def test_merge_updates_win_overwrites_everything(self):
+        """UPDATES_WIN should overwrite all fields, including with None."""
+        # Arrange
+        existing = SimpleModel()
+        existing.id = "123"
+        existing.name = "Original Name"
+        existing.description = "Original Description"
+        existing.price = 10.0
+
+        updates = {"name": "Updated Name", "description": None, "price": 25.0}
+
+        # Act
+        existing.merge(updates, strategy=MergeStrategy.UPDATES_WIN)
+
+        # Assert
+        self.assertEqual(existing.name, "Updated Name")
+        self.assertIsNone(existing.description)  # overwritten with None
+        self.assertEqual(existing.price, 25.0)
+        self.assertEqual(existing.id, "123")  # not in updates, unchanged
+
+    def test_merge_updates_win_with_all_none(self):
+        """UPDATES_WIN with all None values should clear those fields."""
+        # Arrange
+        existing = SimpleModel()
+        existing.name = "Original"
+        existing.description = "Description"
+
+        updates = {"name": None, "description": None}
+
+        # Act
+        existing.merge(updates, strategy=MergeStrategy.UPDATES_WIN)
+
+        # Assert
+        self.assertIsNone(existing.name)
+        self.assertIsNone(existing.description)
+
+    # =========================================================================
+    # EXISTING_WINS Strategy Tests
+    # =========================================================================
+
+    def test_merge_existing_wins_only_fills_gaps(self):
+        """EXISTING_WINS should only update fields that are currently None."""
+        # Arrange
+        existing = SimpleModel()
+        existing.id = "123"
+        existing.name = "Original Name"
+        existing.description = None
+        existing.price = None
+
+        updates = {
+            "name": "Should Not Change",
+            "description": "New Description",
+            "price": 20.0,
+        }
+
+        # Act
+        existing.merge(updates, strategy=MergeStrategy.EXISTING_WINS)
+
+        # Assert
+        self.assertEqual(existing.name, "Original Name")  # unchanged
+        self.assertEqual(existing.description, "New Description")  # filled
+        self.assertEqual(existing.price, 20.0)  # filled
+
+    def test_merge_existing_wins_ignores_all_when_populated(self):
+        """EXISTING_WINS should not change anything if all fields are populated."""
+        # Arrange
+        existing = SimpleModel()
+        existing.id = "123"
+        existing.name = "Original"
+        existing.description = "Original Desc"
+        existing.price = 10.0
+
+        updates = {"name": "New", "description": "New Desc", "price": 99.0}
+
+        # Act
+        existing.merge(updates, strategy=MergeStrategy.EXISTING_WINS)
+
+        # Assert
+        self.assertEqual(existing.name, "Original")
+        self.assertEqual(existing.description, "Original Desc")
+        self.assertEqual(existing.price, 10.0)
+
+    def test_merge_existing_wins_with_clear_field(self):
+        """CLEAR_FIELD should still work with EXISTING_WINS strategy."""
+        # Arrange
+        existing = SimpleModel()
+        existing.name = "Original"
+        existing.description = "Original Desc"
+
+        updates = {"description": CLEAR_FIELD}
+
+        # Act
+        existing.merge(updates, strategy=MergeStrategy.EXISTING_WINS)
+
+        # Assert
+        self.assertIsNone(existing.description)  # CLEAR_FIELD always works
+
+    # =========================================================================
+    # Field Filtering Tests
+    # =========================================================================
+
+    def test_merge_with_include_fields(self):
+        """Only specified include_fields should be considered for merge."""
+        # Arrange
+        existing = SimpleModel()
+        existing.name = "Original"
+        existing.description = "Original Desc"
+        existing.price = 10.0
+
+        updates = {"name": "New Name", "description": "New Desc", "price": 99.0}
+
+        # Act
+        existing.merge(updates, include_fields=["name", "price"])
+
+        # Assert
+        self.assertEqual(existing.name, "New Name")  # included
+        self.assertEqual(existing.description, "Original Desc")  # not included
+        self.assertEqual(existing.price, 99.0)  # included
+
+    def test_merge_with_exclude_fields(self):
+        """Specified exclude_fields should be skipped during merge."""
+        # Arrange
+        existing = SimpleModel()
+        existing.id = "123"
+        existing.name = "Original"
+        existing.description = "Original Desc"
+        existing.price = 10.0
+
+        updates = {
+            "id": "999",
+            "name": "New Name",
+            "description": "New Desc",
+            "price": 99.0,
+        }
+
+        # Act
+        existing.merge(updates, exclude_fields=["id", "price"])
+
+        # Assert
+        self.assertEqual(existing.id, "123")  # excluded
+        self.assertEqual(existing.name, "New Name")  # updated
+        self.assertEqual(existing.description, "New Desc")  # updated
+        self.assertEqual(existing.price, 10.0)  # excluded
+
+    def test_merge_with_both_include_and_exclude(self):
+        """Both include and exclude can be used together."""
+        # Arrange
+        existing = SimpleModel()
+        existing.name = "Original"
+        existing.description = "Original Desc"
+        existing.price = 10.0
+        existing.quantity = 5
+
+        updates = {
+            "name": "New",
+            "description": "New Desc",
+            "price": 99.0,
+            "quantity": 100,
+        }
+
+        # Act - include name, description, price but exclude price
+        existing.merge(
+            updates,
+            include_fields=["name", "description", "price"],
+            exclude_fields=["price"],
+        )
+
+        # Assert
+        self.assertEqual(existing.name, "New")  # included, not excluded
+        self.assertEqual(existing.description, "New Desc")  # included, not excluded
+        self.assertEqual(existing.price, 10.0)  # included but also excluded
+        self.assertEqual(existing.quantity, 5)  # not included
+
+    # =========================================================================
+    # Nested Object/Dict Tests
+    # =========================================================================
+
+    def test_merge_nested_dict_non_null_wins(self):
+        """Nested dicts should be recursively merged with NON_NULL_WINS."""
+        # Arrange
+        existing = NestedModel()
+        existing.settings = {"theme": "dark", "language": "en", "notifications": True}
+
+        updates = {"settings": {"theme": "light", "language": None}}
+
+        # Act
+        existing.merge(updates)
+
+        # Assert
+        self.assertEqual(existing.settings["theme"], "light")  # updated
+        self.assertEqual(existing.settings["language"], "en")  # None ignored
+        self.assertEqual(existing.settings["notifications"], True)  # unchanged
+
+    def test_merge_nested_dict_updates_win(self):
+        """UPDATES_WIN should replace entire nested dict."""
+        # Arrange
+        existing = NestedModel()
+        existing.settings = {"theme": "dark", "language": "en"}
+
+        updates = {"settings": {"theme": "light"}}
+
+        # Act
+        existing.merge(updates, strategy=MergeStrategy.UPDATES_WIN)
+
+        # Assert
+        self.assertEqual(existing.settings, {"theme": "light"})
+
+    def test_merge_with_none_updates(self):
+        """Passing None as updates should return self unchanged."""
+        # Arrange
+        existing = SimpleModel()
+        existing.name = "Original"
+
+        # Act
+        result = existing.merge(None)
+
+        # Assert
+        self.assertEqual(result.name, "Original")
+        self.assertIs(result, existing)
+
+    # =========================================================================
+    # Model-to-Model Merge Tests
+    # =========================================================================
+
+    def test_merge_from_another_model(self):
+        """Should be able to merge from another DynamoDBModelBase instance."""
+        # Arrange
+        existing = SimpleModel()
+        existing.id = "123"
+        existing.name = "Original"
+        existing.description = "Original Desc"
+
+        updates_model = SimpleModel()
+        updates_model.name = "Updated Name"
+        updates_model.price = 50.0
+
+        # Act
+        existing.merge(updates_model)
+
+        # Assert
+        self.assertEqual(existing.name, "Updated Name")
+        self.assertEqual(existing.description, "Original Desc")  # unchanged
+        self.assertEqual(existing.price, 50.0)
+
+    # =========================================================================
+    # Edge Cases
+    # =========================================================================
+
+    def test_merge_ignores_unknown_fields(self):
+        """Fields not on the model should be ignored."""
+        # Arrange
+        existing = SimpleModel()
+        existing.name = "Original"
+
+        updates = {"name": "Updated", "unknown_field": "value", "another_unknown": 123}
+
+        # Act
+        existing.merge(updates)
+
+        # Assert
+        self.assertEqual(existing.name, "Updated")
+        self.assertFalse(hasattr(existing, "unknown_field"))
+        self.assertFalse(hasattr(existing, "another_unknown"))
+
+    def test_merge_returns_self(self):
+        """Merge should return self for method chaining."""
+        # Arrange
+        existing = SimpleModel()
+
+        # Act
+        result = existing.merge({"name": "Test"})
+
+        # Assert
+        self.assertIs(result, existing)
+
+    def test_merge_with_empty_dict(self):
+        """Merging empty dict should not change anything."""
+        # Arrange
+        existing = SimpleModel()
+        existing.name = "Original"
+        existing.price = 10.0
+
+        # Act
+        existing.merge({})
+
+        # Assert
+        self.assertEqual(existing.name, "Original")
+        self.assertEqual(existing.price, 10.0)
+
+    def test_clear_field_repr(self):
+        """CLEAR_FIELD should have a readable repr."""
+        self.assertEqual(repr(CLEAR_FIELD), "CLEAR_FIELD")
+
+    def test_clear_field_is_singleton(self):
+        """CLEAR_FIELD should be a singleton."""
+        from boto3_assist.dynamodb.dynamodb_model_base import _ClearFieldSentinel
+
+        another = _ClearFieldSentinel()
+        self.assertIs(CLEAR_FIELD, another)
+
+
+if __name__ == "__main__":
+    unittest.main()

boto3_assist-0.32.0/src/boto3_assist/version.py

@@ -1 +0,0 @@
-__version__ = "0.32.0"