feat: Add __replace__ magic method to BaseContainer for Python 3.13 support

- Implemented __replace__ method in BaseContainer to support the copy.replace() function.
- Updated CHANGELOG to reflect this new feature.
- Enhanced test cases to ensure __replace__ works as expected, including handling of invalid attributes.

Author: Adrian Acala

CHANGELOG.md

@@ -10,7 +10,7 @@ See [0Ver](https://0ver.org/).
 
 ### Features
 
-- Add `__replace__` protocol support for Python 3.13's `copy.replace()`
+- Add `__replace__` magic method to `BaseContainer` to support `copy.replace()` function from Python 3.13
 
 ## 0.25.0
 

returns/primitives/container.py

@@ -69,7 +69,14 @@ def __setstate__(self, state: _PickleState | Any) -> None:
             object.__setattr__(self, '_inner_value', state)
 
     def __replace__(self, /, **changes) -> 'BaseContainer':
-        """Protocol for copy.replace() function (Python 3.13+)."""
+        """
+        Creates a new container with replaced attribute values.
+
+        Implements the protocol for the `copy.replace()` function
+        introduced in Python 3.13.
+
+        The only supported attribute is '_inner_value'.
+        """
         if not changes:
             return self
 

tests/test_primitives/test_container/test_base_container/test_replace.py

@@ -10,32 +10,39 @@
 
 # For Python < 3.13 compatibility: copy.replace doesn't exist in older Python
 if TYPE_CHECKING:  # pragma: no cover
-
+    # Defining a dummy replace function for type checking
     def _replace(container_instance: Any, /, **changes: Any) -> Any:
         """Dummy replace function for type checking."""
         return container_instance
 
+    # Assigning it to copy.replace for type checking
     if not hasattr(copy, 'replace'):
         copy.replace = _replace  # type: ignore
 
 
 class _CustomClass:
+    """A custom class for replace testing."""
+
     __slots__ = ('inner_value',)
 
     def __init__(self, inner_value: str) -> None:
+        """Initialize instance."""
         self.inner_value = inner_value
 
     def __eq__(self, other: object) -> bool:
+        """Compare with other."""
         if isinstance(other, _CustomClass):
             return self.inner_value == other.inner_value
         return NotImplemented
 
     def __ne__(self, other: object) -> bool:
+        """Not equal to other."""
         if isinstance(other, _CustomClass):
             return self.inner_value != other.inner_value
         return NotImplemented
 
     def __hash__(self) -> int:
+        """Return hash of the inner value."""
         return hash(self.inner_value)
 
 
@@ -52,9 +59,10 @@ def __hash__(self) -> int:
 )
 @example(None)
 def test_replace(container_value: Any) -> None:
-    """Test __replace__ magic method."""
+    """Ensures __replace__ magic method works as expected."""
     container = BaseContainer(container_value)
 
+    # Test with new inner_value returns a new container
     new_value = 'new_value'
     new_container = container.__replace__(_inner_value=new_value)
 
@@ -65,14 +73,15 @@ def test_replace(container_value: Any) -> None:
 
 
 def test_replace_no_changes() -> None:
-    """Test __replace__ with no changes."""
+    """Ensures __replace__ with no changes returns the same container."""
     container = BaseContainer('test')
+    # We need to call the method directly to test this functionality
     result = container.__replace__()  # noqa: PLC2801
     assert result is container
 
 
 def test_replace_invalid_attributes() -> None:
-    """Test __replace__ with invalid attributes."""
+    """Ensures __replace__ raises ValueError for invalid attributes."""
     container = BaseContainer('test')
 
     with pytest.raises(ValueError, match='Only _inner_value can be replaced'):
@@ -99,11 +108,13 @@ def test_replace_invalid_attributes() -> None:
 )
 @example(None)
 def test_copy_replace(container_value: Any) -> None:
-    """Test copy.replace with BaseContainer."""
+    """Ensures copy.replace works with BaseContainer."""
     container = BaseContainer(container_value)
 
+    # Test with no changes returns the same container
     assert copy.replace(container) is container  # type: ignore[attr-defined]
 
+    # Test with new inner_value returns a new container
     new_value = 'new_value'
     new_container = copy.replace(container, _inner_value=new_value)  # type: ignore[attr-defined]
 
@@ -118,7 +129,7 @@ def test_copy_replace(container_value: Any) -> None:
     reason='copy.replace requires Python 3.13+',
 )
 def test_copy_replace_invalid_attributes() -> None:
-    """Test copy.replace with invalid attributes."""
+    """Ensures copy.replace raises ValueError for invalid attributes."""
     container = BaseContainer('test')
 
     with pytest.raises(ValueError, match='Only _inner_value can be replaced'):