gh-108751: Add copy.replace() function (GH-108752)

It creates a modified copy of an object by calling the object's
__replace__() method.

It is a generalization of dataclasses.replace(), named tuple's _replace()
method and replace() methods in various classes, and supports all these
stdlib classes.

Author: serhiy-storchaka

Doc/library/collections.rst

@@ -979,6 +979,8 @@ field names, the method and attribute names start with an underscore.
         >>> for partnum, record in inventory.items():
         ...     inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())
 
+    Named tuples are also supported by generic function :func:`copy.replace`.
+
 .. attribute:: somenamedtuple._fields
 
     Tuple of strings listing the field names.  Useful for introspection

Doc/library/copy.rst

@@ -17,14 +17,22 @@ operations (explained below).
 
 Interface summary:
 
-.. function:: copy(x)
+.. function:: copy(obj)
 
-   Return a shallow copy of *x*.
+   Return a shallow copy of *obj*.
 
 
-.. function:: deepcopy(x[, memo])
+.. function:: deepcopy(obj[, memo])
 
-   Return a deep copy of *x*.
+   Return a deep copy of *obj*.
+
+
+.. function:: replace(obj, /, **changes)
+
+   Creates a new object of the same type as *obj*, replacing fields with values
+   from *changes*.
+
+   .. versionadded:: 3.13
 
 
 .. exception:: Error
@@ -89,6 +97,20 @@ with the component as first argument and the memo dictionary as second argument.
 The memo dictionary should be treated as an opaque object.
 
 
+.. index::
+   single: __replace__() (replace protocol)
+
+Function :func:`replace` is more limited than :func:`copy` and :func:`deepcopy`,
+and only supports named tuples created by :func:`~collections.namedtuple`,
+:mod:`dataclasses`, and other classes which define method :meth:`!__replace__`.
+
+   .. method:: __replace__(self, /, **changes)
+      :noindex:
+
+:meth:`!__replace__` should create a new object of the same type,
+replacing fields with values from *changes*.
+
+
 .. seealso::
 
    Module :mod:`pickle`

Doc/library/dataclasses.rst

@@ -456,6 +456,8 @@ Module contents
    ``replace()`` (or similarly named) method which handles instance
    copying.
 
+   Dataclass instances are also supported by generic function :func:`copy.replace`.
+
 .. function:: is_dataclass(obj)
 
    Return ``True`` if its parameter is a dataclass or an instance of one,

Doc/library/datetime.rst

@@ -652,6 +652,9 @@ Instance methods:
        >>> d.replace(day=26)
        datetime.date(2002, 12, 26)
 
+   :class:`date` objects are also supported by generic function
+   :func:`copy.replace`.
+
 
 .. method:: date.timetuple()
 
@@ -1251,6 +1254,9 @@ Instance methods:
    ``tzinfo=None`` can be specified to create a naive datetime from an aware
    datetime with no conversion of date and time data.
 
+   :class:`datetime` objects are also supported by generic function
+   :func:`copy.replace`.
+
    .. versionadded:: 3.6
       Added the ``fold`` argument.
 
@@ -1827,6 +1833,9 @@ Instance methods:
    ``tzinfo=None`` can be specified to create a naive :class:`.time` from an
    aware :class:`.time`, without conversion of the time data.
 
+   :class:`time` objects are also supported by generic function
+   :func:`copy.replace`.
+
    .. versionadded:: 3.6
       Added the ``fold`` argument.
 

Doc/library/inspect.rst

@@ -689,8 +689,8 @@ function.
    The optional *return_annotation* argument, can be an arbitrary Python object,
    is the "return" annotation of the callable.
 
-   Signature objects are *immutable*.  Use :meth:`Signature.replace` to make a
-   modified copy.
+   Signature objects are *immutable*.  Use :meth:`Signature.replace` or
+   :func:`copy.replace` to make a modified copy.
 
    .. versionchanged:: 3.5
       Signature objects are picklable and :term:`hashable`.
@@ -746,6 +746,9 @@ function.
          >>> str(new_sig)
          "(a, b) -> 'new return anno'"
 
+      Signature objects are also supported by generic function
+      :func:`copy.replace`.
+
    .. classmethod:: Signature.from_callable(obj, *, follow_wrapped=True, globalns=None, localns=None)
 
        Return a :class:`Signature` (or its subclass) object for a given callable
@@ -769,7 +772,7 @@ function.
 .. class:: Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)
 
    Parameter objects are *immutable*.  Instead of modifying a Parameter object,
-   you can use :meth:`Parameter.replace` to create a modified copy.
+   you can use :meth:`Parameter.replace` or :func:`copy.replace` to create a modified copy.
 
    .. versionchanged:: 3.5
       Parameter objects are picklable and :term:`hashable`.
@@ -892,6 +895,8 @@ function.
          >>> str(param.replace(default=Parameter.empty, annotation='spam'))
          "foo:'spam'"
 
+      Parameter objects are also supported by generic function :func:`copy.replace`.
+
    .. versionchanged:: 3.4
       In Python 3.3 Parameter objects were allowed to have ``name`` set
       to ``None`` if their ``kind`` was set to ``POSITIONAL_ONLY``.

Doc/library/types.rst

@@ -200,6 +200,8 @@ Standard names are defined for the following types:
 
      Return a copy of the code object with new values for the specified fields.
 
+     Code objects are also supported by generic function :func:`copy.replace`.
+
      .. versionadded:: 3.8
 
 .. data:: CellType

Doc/whatsnew/3.13.rst

@@ -115,6 +115,18 @@ array
   It can be used instead of ``'u'`` type code, which is deprecated.
   (Contributed by Inada Naoki in :gh:`80480`.)
 
+copy
+----
+
+* Add :func:`copy.replace` function which allows to create a modified copy of
+  an object, which is especially usefule for immutable objects.
+  It supports named tuples created with the factory function
+  :func:`collections.namedtuple`, :class:`~dataclasses.dataclass` instances,
+  various :mod:`datetime` objects, :class:`~inspect.Signature` objects,
+  :class:`~inspect.Parameter` objects, :ref:`code object <code-objects>`, and
+  any user classes which define the :meth:`!__replace__` method.
+  (Contributed by Serhiy Storchaka in :gh:`108751`.)
+
 dbm
 ---
 

Lib/_pydatetime.py

@@ -1112,6 +1112,8 @@ def replace(self, year=None, month=None, day=None):
             day = self._day
         return type(self)(year, month, day)
 
+    __replace__ = replace
+
     # Comparisons of date objects with other.
 
     def __eq__(self, other):
@@ -1637,6 +1639,8 @@ def replace(self, hour=None, minute=None, second=None, microsecond=None,
             fold = self._fold
         return type(self)(hour, minute, second, microsecond, tzinfo, fold=fold)
 
+    __replace__ = replace
+
     # Pickle support.
 
     def _getstate(self, protocol=3):
@@ -1983,6 +1987,8 @@ def replace(self, year=None, month=None, day=None, hour=None,
         return type(self)(year, month, day, hour, minute, second,
                           microsecond, tzinfo, fold=fold)
 
+    __replace__ = replace
+
     def _local_timezone(self):
         if self.tzinfo is None:
             ts = self._mktime()

Lib/collections/__init__.py

@@ -495,6 +495,7 @@ def __getnewargs__(self):
         '_field_defaults': field_defaults,
         '__new__': __new__,
         '_make': _make,
+        '__replace__': _replace,
         '_replace': _replace,
         '__repr__': __repr__,
         '_asdict': _asdict,

Lib/copy.py

@@ -290,3 +290,16 @@ def _reconstruct(x, memo, func, args,
     return y
 
 del types, weakref
+
+
+def replace(obj, /, **changes):
+    """Return a new object replacing specified fields with new values.
+
+    This is especially useful for immutable objects, like named tuples or
+    frozen dataclasses.
+    """
+    cls = obj.__class__
+    func = getattr(cls, '__replace__', None)
+    if func is None:
+        raise TypeError(f"replace() does not support {cls.__name__} objects")
+    return func(obj, **changes)

Lib/dataclasses.py

@@ -1073,6 +1073,7 @@ def _process_class(cls, init, repr, eq, order, unsafe_hash, frozen,
                                     globals,
                                     slots,
                           ))
+    _set_new_attribute(cls, '__replace__', _replace)
 
     # Get the fields as a list, and include only real fields.  This is
     # used in all of the following methods.
@@ -1546,13 +1547,15 @@ class C:
       c1 = replace(c, x=3)
       assert c1.x == 3 and c1.y == 2
     """
+    if not _is_dataclass_instance(obj):
+        raise TypeError("replace() should be called on dataclass instances")
+    return _replace(obj, **changes)
+
 
+def _replace(obj, /, **changes):
     # We're going to mutate 'changes', but that's okay because it's a
     # new dict, even if called with 'replace(obj, **my_changes)'.
 
-    if not _is_dataclass_instance(obj):
-        raise TypeError("replace() should be called on dataclass instances")
-
     # It's an error to have init=False fields in 'changes'.
     # If a field is not in 'changes', read its value from the provided obj.
 

Lib/inspect.py

@@ -2870,6 +2870,8 @@ def __str__(self):
 
         return formatted
 
+    __replace__ = replace
+
     def __repr__(self):
         return '<{} "{}">'.format(self.__class__.__name__, self)
 
@@ -3130,6 +3132,8 @@ def replace(self, *, parameters=_void, return_annotation=_void):
         return type(self)(parameters,
                           return_annotation=return_annotation)
 
+    __replace__ = replace
+
     def _hash_basis(self):
         params = tuple(param for param in self.parameters.values()
                              if param.kind != _KEYWORD_ONLY)