Docs on named tuple's naming conventions and limits of subclassing

diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index be6c67f8828e09aff9da8ef48c677e781a50ae96..dde7f55d55794a53a0db9aa437c2f3a1154be16f 100644 (file)
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -446,7 +446,8 @@ by the :mod:`csv` or :mod:`sqlite3` modules::
        print emp.name, emp.title
 
 In addition to the methods inherited from tuples, named tuples support
-three additional methods and one attribute.
+three additional methods and one attribute.  To prevent conflicts with
+field names, the method and attribute names start with an underscore.
 
 .. method:: somenamedtuple._make(iterable)
 
@@ -533,6 +534,11 @@ faster versions that bypass error-checking and that localize variable access::
         def _replace(self, _map=map, **kwds):
             return self._make(_map(kwds.get, ('x', 'y'), self))
 
+Subclassing is not useful for adding new, stored fields.  Instead, simply
+create a new named tuple type from the :attr:`_fields` attribute::
+
+    >>> Pixel = namedtuple('Pixel', Point._fields + Color._fields)
+
 Default values can be implemented by using :meth:`_replace` to
 customize a prototype instance::