Add __replace__ magic method to BaseContainer for copy.replace() support

- Implemented the __replace__ method in BaseContainer to allow for the creation of new container instances with modified internal values, in line with the copy.replace() function introduced in Python 3.13.
- Updated documentation to reflect this new feature and provided usage examples.
- Added tests to ensure the correct functionality of the __replace__ method and its integration with the copy module.

Author: Adrian Acala

CHANGELOG.md

@@ -6,6 +6,12 @@ incremental in minor, bugfixes only are patches.
 See [0Ver](https://0ver.org/).
 
 
+## UNRELEASED
+
+### Features
+
+- Add `__replace__` protocol support for Python 3.13's `copy.replace()`
+
 ## 0.25.0
 
 ### Features

docs/pages/container.rst

@@ -176,6 +176,29 @@ There are many other constructors!
 Check out concrete types and their interfaces.
 
 
+Replacing values in a container
+-------------------------------
+
+Starting from Python 3.13, the standard library provides
+a ``copy.replace()`` function that works with objects that implement
+the ``__replace__`` protocol. All containers in ``returns`` implement this protocol.
+
+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
+
+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``.
+
+
 Working with multiple containers
 --------------------------------
 

returns/primitives/container.py

@@ -68,6 +68,18 @@ 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',
+            )
+
+        return self.__class__(changes['_inner_value'])
+
 
 def container_equality(
     self: Kind1[_EqualType, Any],

tests/test_primitives/test_container/test_base_container/test_replace.py

@@ -0,0 +1,128 @@
+import copy
+import sys
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from hypothesis import example, given
+from hypothesis import strategies as st
+
+from returns.primitives.container import BaseContainer
+
+# 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:
+        """Dummy replace function for type checking."""
+        return container_instance
+
+    if not hasattr(copy, 'replace'):
+        copy.replace = _replace  # type: ignore
+
+
+class _CustomClass:
+    __slots__ = ('inner_value',)
+
+    def __init__(self, inner_value: str) -> None:
+        self.inner_value = inner_value
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, _CustomClass):
+            return self.inner_value == other.inner_value
+        return NotImplemented
+
+    def __ne__(self, other: object) -> bool:
+        if isinstance(other, _CustomClass):
+            return self.inner_value != other.inner_value
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self.inner_value)
+
+
+@given(
+    st.one_of(
+        st.integers(),
+        st.floats(allow_nan=False),
+        st.text(),
+        st.booleans(),
+        st.lists(st.text()),
+        st.dictionaries(st.text(), st.integers()),
+        st.builds(_CustomClass, st.text()),
+    ),
+)
+@example(None)
+def test_replace(container_value: Any) -> None:
+    """Test __replace__ magic method."""
+    container = BaseContainer(container_value)
+
+    new_value = 'new_value'
+    new_container = container.__replace__(_inner_value=new_value)
+
+    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_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')
+
+    with pytest.raises(ValueError, match='Only _inner_value can be replaced'):
+        container.__replace__(_inner_value='new', another_attr='value')
+
+
+@pytest.mark.skipif(
+    sys.version_info < (3, 13),
+    reason='copy.replace requires Python 3.13+',
+)
+@given(
+    st.one_of(
+        st.integers(),
+        st.floats(allow_nan=False),
+        st.text(),
+        st.booleans(),
+        st.lists(st.text()),
+        st.dictionaries(st.text(), st.integers()),
+        st.builds(_CustomClass, st.text()),
+    ),
+)
+@example(None)
+def test_copy_replace(container_value: Any) -> None:
+    """Test copy.replace with BaseContainer."""
+    container = BaseContainer(container_value)
+
+    assert copy.replace(container) is container  # type: ignore[attr-defined]
+
+    new_value = 'new_value'
+    new_container = copy.replace(container, _inner_value=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')
+
+    with pytest.raises(ValueError, match='Only _inner_value can be replaced'):
+        copy.replace(container, invalid_attr='value')  # 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]