[draft] Add with_replace_method= to namedtuple to allow .replace as an alternate to ._replace

Inspired by python#136083 because one offs for this kind of thing feel like they'd
create more of a mess than allowing it for anyone?

Signifiantly written by Claude Sonnet 4 in Claude Code.

Author: gpshead

Doc/library/collections.rst

@@ -844,7 +844,7 @@ Named tuples assign meaning to each position in a tuple and allow for more reada
 self-documenting code.  They can be used wherever regular tuples are used, and
 they add the ability to access fields by name instead of position index.
 
-.. function:: namedtuple(typename, field_names, *, rename=False, defaults=None, module=None)
+.. function:: namedtuple(typename, field_names, *, rename=False, defaults=None, module=None, with_replace_method=False)
 
     Returns a new tuple subclass named *typename*.  The new subclass is used to
     create tuple-like objects that have fields accessible by attribute lookup as
@@ -878,6 +878,12 @@ they add the ability to access fields by name instead of position index.
     If *module* is defined, the :attr:`~type.__module__` attribute of the
     named tuple is set to that value.
 
+    If *with_replace_method* is true, the named tuple will have a public
+    :meth:`replace` method as an alias to the private :meth:`_replace` method.
+    This provides a :pep:`8` friendly API for creating modified copies of named
+    tuple instances. This is useful for namedtuples that do not have a field
+    named ``replace`` and are never expected to gain one in the future.
+
     Named tuple instances do not have per-instance dictionaries, so they are
     lightweight and require no more memory than regular tuples.
 
@@ -901,6 +907,9 @@ they add the ability to access fields by name instead of position index.
        Added the *defaults* parameter and the :attr:`~somenamedtuple._field_defaults`
        attribute.
 
+    .. versionadded:: next
+       Added the *with_replace_method* parameter.
+
 .. doctest::
     :options: +NORMALIZE_WHITESPACE
 
@@ -917,6 +926,12 @@ they add the ability to access fields by name instead of position index.
     >>> p                       # readable __repr__ with a name=value style
     Point(x=11, y=22)
 
+    >>> # Example with public replace method
+    >>> Point = namedtuple('Point', ['x', 'y'], with_replace_method=True)
+    >>> p = Point(11, 22)
+    >>> p.replace(x=100)        # public replace method when enabled
+    Point(x=100, y=22)
+
 Named tuples are especially useful for assigning field names to result tuples returned
 by the :mod:`csv` or :mod:`sqlite3` modules::
 

Lib/collections/__init__.py

@@ -358,7 +358,7 @@ def __ror__(self, other):
 except ImportError:
     _tuplegetter = lambda index, doc: property(_itemgetter(index), doc=doc)
 
-def namedtuple(typename, field_names, *, rename=False, defaults=None, module=None):
+def namedtuple(typename, field_names, *, rename=False, defaults=None, module=None, with_replace_method=False):
     """Returns a new subclass of tuple with named fields.
 
     >>> Point = namedtuple('Point', ['x', 'y'])
@@ -380,6 +380,13 @@ def namedtuple(typename, field_names, *, rename=False, defaults=None, module=Non
     >>> p._replace(x=100)               # _replace() is like str.replace() but targets named fields
     Point(x=100, y=22)
 
+    The 'with_replace_method' parameter adds a public 'replace' method as an alias to '_replace':
+
+    >>> Point = namedtuple('Point', ['x', 'y'], with_replace_method=True)
+    >>> p = Point(11, 22)
+    >>> p.replace(x=100)                # public replace method when enabled
+    Point(x=100, y=22)
+
     """
 
     # Validate the field names.  At the user's option, either generate an error
@@ -426,6 +433,11 @@ def namedtuple(typename, field_names, *, rename=False, defaults=None, module=Non
         field_defaults = dict(reversed(list(zip(reversed(field_names),
                                                 reversed(defaults)))))
 
+    # Check for conflicting field names when with_replace_method is enabled
+    if with_replace_method and 'replace' in field_names:
+        raise ValueError('Cannot use with_replace_method=True when '
+                         f'a field named "replace" exists: {field_names!r}')
+
     # Variables used in the methods and docstrings
     field_names = tuple(map(_sys.intern, field_names))
     num_fields = len(field_names)
@@ -508,6 +520,8 @@ def __getnewargs__(self):
         '__getnewargs__': __getnewargs__,
         '__match_args__': field_names,
     }
+    if with_replace_method:
+        class_namespace['replace'] = _replace
     for index, name in enumerate(field_names):
         doc = _sys.intern(f'Alias for field number {index}')
         class_namespace[name] = _tuplegetter(index, doc)

Lib/test/test_collections.py

@@ -717,6 +717,44 @@ def test_non_generic_subscript(self):
         self.assertIs(type(a), Group)
         self.assertEqual(a, (1, [2]))
 
+    def test_replace_method_opt_in(self):
+        # Test that replace method is NOT available by default
+        Point = namedtuple('Point', 'x y')
+        p = Point(11, 22)
+        self.assertFalse(hasattr(p, 'replace'))
+        self.assertTrue(hasattr(p, '_replace'))
+
+        # Test that replace method IS available when with_replace_method=True
+        PointWithReplace = namedtuple('PointWithReplace', 'x y', with_replace_method=True)
+        pr = PointWithReplace(11, 22)
+        self.assertTrue(hasattr(pr, 'replace'))
+        self.assertTrue(hasattr(pr, '_replace'))
+
+        # Test that both methods work identically
+        self.assertEqual(pr.replace(x=100), (100, 22))
+        self.assertEqual(pr._replace(x=100), (100, 22))
+        self.assertEqual(pr.replace(x=100), pr._replace(x=100))
+
+        # Test that replace method works with keyword arguments
+        self.assertEqual(pr.replace(x=5, y=10), (5, 10))
+        self.assertEqual(pr.replace(y=99), (11, 99))
+
+        # Test error handling - invalid field name
+        with self.assertRaises(TypeError):
+            pr.replace(invalid_field=123)
+
+        # Test validation - cannot have field named "replace" with with_replace_method=True
+        with self.assertRaises(ValueError) as cm:
+            namedtuple('BadTuple', ['x', 'replace', 'y'], with_replace_method=True)
+        self.assertIn('Cannot use with_replace_method=True', str(cm.exception))
+        self.assertIn('field named "replace"', str(cm.exception))
+
+        # Test that field named "replace" works fine without with_replace_method
+        GoodTuple = namedtuple('GoodTuple', ['x', 'replace', 'y'])
+        gt = GoodTuple(1, 2, 3)
+        self.assertEqual(gt.replace, 2)  # Field access works
+        self.assertTrue(hasattr(gt, '_replace'))  # _replace method still exists
+
 
 ################################################################################
 ### Abstract Base Classes