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
 

docs/pages/container.rst

@@ -187,13 +187,19 @@ This allows creating new container instances with modified internal values:
 
 .. code:: python
 
-  >>> from copy import replace  # Python 3.13+ only
-  >>> from returns.result import Success
-
-  >>> value = Success(1)
-  >>> new_value = replace(value, _inner_value=2)
-  >>> assert new_value == Success(2)
-  >>> assert value != new_value
+  >>> import sys
+  >>> # The following example requires Python 3.13+
+  >>> if sys.version_info >= (3, 13):
+  ...     from copy import replace
+  ...     from returns.result import Success
+  ...
+  ...     value = Success(1)
+  ...     new_value = replace(value, _inner_value=2)
+  ...     assert new_value == Success(2)
+  ...     assert value != new_value
+  ... else:
+  ...     # Skip this example for Python < 3.13
+  ...     pass
 
 This is particularly useful when you need to modify the inner value of a container
 without using the regular container methods like ``map`` or ``bind``.

returns/primitives/container.py

@@ -68,17 +68,16 @@ def __setstate__(self, state: _PickleState | Any) -> None:
             # backward compatibility with 0.19.0 and earlier
             object.__setattr__(self, '_inner_value', state)
 
-    def __replace__(self, /, **changes) -> 'BaseContainer':
-        """Protocol for copy.replace() function (Python 3.13+)."""
-        if not changes:
-            return self
-
-        if len(changes) > 1 or '_inner_value' not in changes:
-            raise ValueError(
-                'Only _inner_value can be replaced in a container',
-            )
+    def __replace__(self, /, inner_value: Any) -> 'BaseContainer':
+        """
+        Creates a new container with replaced inner_value.
 
-        return self.__class__(changes['_inner_value'])
+        Implements the protocol for the `copy.replace()` function
+        introduced in Python 3.13.
+
+        The only supported argument is 'inner_value'.
+        """
+        return self.__class__(inner_value)
 
 
 def container_equality(

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
-
-    def _replace(container_instance: Any, /, **changes: Any) -> Any:
+    # Defining a dummy replace function for type checking
+    def _replace(container_instance: Any, /, inner_value: 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)
 
 
@@ -51,35 +58,50 @@ def __hash__(self) -> int:
     ),
 )
 @example(None)
-def test_replace(container_value: Any) -> None:
-    """Test __replace__ magic method."""
+def test_replace_method(container_value: Any) -> None:
+    """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)
+    # Test direct call to __replace__
+    new_container = container.__replace__(new_value)  # noqa: PLC2801
 
     assert new_container is not container
     assert new_container._inner_value == new_value  # noqa: SLF001
     assert isinstance(new_container, BaseContainer)
     assert type(new_container) is type(container)  # noqa: WPS516
 
 
-def test_replace_no_changes() -> None:
-    """Test __replace__ with no changes."""
-    container = BaseContainer('test')
-    result = container.__replace__()  # noqa: PLC2801
-    assert result is container
+def test_base_container_replace_direct_call(container):
+    """Test direct call to the __replace__ method."""
+    new_value = 'new_value'
+    # Test direct call to __replace__
+    new_container = container.__replace__(new_value)  # noqa: PLC2801
 
+    assert new_container is not container
+    assert isinstance(new_container, BaseContainer)
 
-def test_replace_invalid_attributes() -> None:
-    """Test __replace__ with invalid attributes."""
-    container = BaseContainer('test')
 
-    with pytest.raises(ValueError, match='Only _inner_value can be replaced'):
-        container.__replace__(invalid_attr='value')
+def test_base_container_replace_direct_call_invalid_args(container):
+    """Test direct call with invalid arguments."""
+    # Direct call with no args should fail
+    with pytest.raises(TypeError):
+        container.__replace__()  # noqa: PLC2801
 
-    with pytest.raises(ValueError, match='Only _inner_value can be replaced'):
-        container.__replace__(_inner_value='new', another_attr='value')
+    # Direct call with keyword args matching the name is allowed by Python,
+    # even with /.
+    # If uncommented, it should pass as Python allows this.
+    # Removing commented test case for
+    # `container.__replace__(inner_value='new')`
+
+    # Direct call with extra positional args should fail
+    with pytest.raises(TypeError):
+        container.__replace__('new', 'extra')  # noqa: PLC2801
+
+    # Direct call with unexpected keyword args should fail
+    with pytest.raises(TypeError):
+        container.__replace__(other_kwarg='value')  # type: ignore[attr-defined]
 
 
 @pytest.mark.skipif(
@@ -99,30 +121,56 @@ 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)
 
-    assert copy.replace(container) is container  # type: ignore[attr-defined]
+    # Test with no changes is not directly possible via copy.replace with this
+    # __replace__ implementation.
+    # The copy.replace function itself handles the no-change case if the
+    # object supports it, but our __replace__ requires a value.
 
+    # Test with new inner_value returns a new container using copy.replace
     new_value = 'new_value'
-    new_container = copy.replace(container, _inner_value=new_value)  # type: ignore[attr-defined]
+    # copy.replace calls __replace__ with the new value as a positional arg
+    new_container = copy.replace(container, new_value)  # type: ignore[attr-defined]
 
     assert new_container is not container
     assert new_container._inner_value == new_value  # noqa: SLF001
     assert isinstance(new_container, BaseContainer)
     assert type(new_container) is type(container)  # noqa: WPS516
 
 
-@pytest.mark.skipif(
-    sys.version_info < (3, 13),
-    reason='copy.replace requires Python 3.13+',
-)
-def test_copy_replace_invalid_attributes() -> None:
-    """Test copy.replace with invalid attributes."""
-    container = BaseContainer('test')
+def test_base_container_replace_via_copy_no_changes(container_value):
+    """Test copy.replace with no actual change in value."""
+    container = BaseContainer(container_value)
+
+    # Test with no changes is not directly possible via copy.replace with this
+    # __replace__ implementation.
+    # The copy.replace function itself handles the no-change case if the
+    # object supports it, but our __replace__ requires a value.
+    # If copy.replace is called with the same value, it should work.
+    new_container = copy.replace(container, inner_value=container_value)
+
+    assert new_container is not container  # A new instance should be created
+
+
+def test_base_container_replace_via_copy_invalid_args(container):
+    """Test copy.replace with invalid arguments."""
+    # copy.replace converts the keyword 'inner_value' to a positional arg
+    # for __replace__(self, /, inner_value), so this is valid.
+    # Removing commented out test case for copy.replace with inner_value kwarg
+
+    # However, passing other keyword arguments will fail because __replace__
+    # doesn't accept them.
+    with pytest.raises(TypeError):
+        copy.replace(container, other_kwarg='value')  # type: ignore[attr-defined]
 
-    with pytest.raises(ValueError, match='Only _inner_value can be replaced'):
-        copy.replace(container, invalid_attr='value')  # type: ignore[attr-defined]
+    # copy.replace should raise TypeError if extra positional arguments
+    # are passed.
+    with pytest.raises(TypeError):
+        copy.replace(container, 'new', 'extra')  # type: ignore[attr-defined]
 
-    with pytest.raises(ValueError, match='Only _inner_value can be replaced'):
-        copy.replace(container, _inner_value='new', another_attr='value')  # type: ignore[attr-defined]
+    # copy.replace should raise TypeError if no value is passed
+    # (our __replace__ requires one).
+    with pytest.raises(TypeError):
+        copy.replace(container)  # type: ignore[attr-defined]