python
diff --git a/‎Doc/c-api/concrete.rst
Lines changed: 5 additions & 5 deletions b/‎Doc/c-api/concrete.rst
Lines changed: 5 additions & 5 deletions
diff --git a/‎Doc/library/collections.rst
Lines changed: 88 additions & 40 deletions b/‎Doc/library/collections.rst
Lines changed: 88 additions & 40 deletions
@@ -1953,12 +1953,12 @@ Tuple Objects
    ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
 
 
-.. cfunction:: int PyTuple_Size(PyObject *p)
+.. cfunction:: Py_ssize_t PyTuple_Size(PyObject *p)
 
    Take a pointer to a tuple object, and return the size of that tuple.
 
 
-.. cfunction:: int PyTuple_GET_SIZE(PyObject *p)
+.. cfunction:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
 
    Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
    no error checking is performed.
@@ -2458,7 +2458,7 @@ change in future releases of Python.
    immediately after file object creation.
 
 
-.. cfunction:: int PyFile_Encoding(PyFileObject *p, char *enc)
+.. cfunction:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)
 
    Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0
    on failure.
@@ -3371,7 +3371,7 @@ The following functions and macros are available for instances of :class:`set`
 or :class:`frozenset` or instances of their subtypes.
 
 
-.. cfunction:: int PySet_Size(PyObject *anyset)
+.. cfunction:: Py_ssize_t PySet_Size(PyObject *anyset)
 
    .. index:: builtin: len
 
@@ -3380,7 +3380,7 @@ or :class:`frozenset` or instances of their subtypes.
    :class:`set`, :class:`frozenset`, or an instance of a subtype.
 
 
-.. cfunction:: int PySet_GET_SIZE(PyObject *anyset)
+.. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
 
    Macro form of :cfunc:`PySet_Size` without error checking.
 
 
@@ -395,55 +395,103 @@ Setting the :attr:`default_factory` to :class:`set` makes the
 
 .. _named-tuple-factory:
 
-:func:`NamedTuple` datatype factory function
---------------------------------------------
+:func:`NamedTuple` factory function
+-----------------------------------
 
+Named tuples assign meaning to each position in a tuple and allow for more readable,
+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, fieldnames)
+.. function:: NamedTuple(typename, fieldnames, [verbose])
 
    Returns a new tuple subclass named *typename*.  The new subclass is used to
    create tuple-like objects that have fields accessable by attribute lookup as
    well as being indexable and iterable.  Instances of the subclass also have a
    helpful docstring (with typename and fieldnames) and a helpful :meth:`__repr__`
    method which lists the tuple contents in a ``name=value`` format.
 
-   The *fieldnames* are specified in a single string and are separated by spaces.
-   Any valid Python identifier may be used for a field name.
-
-   Example::
-
-      >>> Point = NamedTuple('Point', 'x y')
-      >>> Point.__doc__           # docstring for the new datatype
-      'Point(x, y)'
-      >>> p = Point(11, y=22)     # instantiate with positional or keyword arguments
-      >>> p[0] + p[1]             # works just like the tuple (11, 22)
-      33
-      >>> x, y = p                # unpacks just like a tuple
-      >>> x, y
-      (11, 22)
-      >>> p.x + p.y               # fields also accessable by name
-      33
-      >>> p                       # readable __repr__ with name=value style
-      Point(x=11, y=22)  
-
-   The use cases are the same as those for tuples.  The named factories assign
-   meaning to each tuple position and allow for more readable, self-documenting
-   code.  Named tuples can also be used to assign field names  to tuples returned
-   by the :mod:`csv` or :mod:`sqlite3` modules. For example::
-
-      from itertools import starmap
-      import csv
-      EmployeeRecord = NamedTuple('EmployeeRecord', 'name age title department paygrade')
-      for record in starmap(EmployeeRecord, csv.reader(open("employees.csv", "rb"))):
-          print(record)
-
-   To cast an individual record stored as :class:`list`, :class:`tuple`, or some
-   other iterable type, use the star-operator [#]_ to unpack the values::
-
-      >>> Color = NamedTuple('Color', 'name code')
-      >>> m = dict(red=1, green=2, blue=3)
-      >>> print(Color(*m.popitem()))
-      Color(name='blue', code=3)
+   The *fieldnames* are specified in a single string with each fieldname separated by
+   a space and/or comma.  Any valid Python identifier may be used for a field name.
+
+   If *verbose* is true, the *NamedTuple* call will print the class definition.
+
+   *NamedTuple* instances do not have per-instance dictionaries, so they are
+   lightweight, requiring no more memory than regular tuples.
+
+Example::
+
+   >>> Point = NamedTuple('Point', 'x y', True)
+   class Point(tuple):
+           'Point(x, y)'
+           __slots__ = ()
+           __fields__ = ('x', 'y')
+           def __new__(cls, x, y):
+               return tuple.__new__(cls, (x, y))
+           def __repr__(self):
+               return 'Point(x=%r, y=%r)' % self
+           def __replace__(self, field, value):
+               'Return a new Point object replacing one field with a new value'
+               return Point(**dict(zip(('x', 'y'), self) + [(field, value)]))
+           x = property(itemgetter(0))
+           y = property(itemgetter(1))
+
+   >>> p = Point(11, y=22)     # instantiate with positional or keyword arguments
+   >>> p[0] + p[1]             # indexable like the regular tuple (11, 22)
+   33
+   >>> x, y = p                # unpack like a regular tuple
+   >>> x, y
+   (11, 22)
+   >>> p.x + p.y               # fields also accessable by name
+   33
+   >>> p                       # readable __repr__ with a name=value style
+   Point(x=11, y=22)
+
+Named tuples are especially useful for assigning field names to result tuples returned
+by the :mod:`csv` or :mod:`sqlite3` modules::
+
+   from itertools import starmap
+   import csv
+   EmployeeRecord = NamedTuple('EmployeeRecord', 'name age title department paygrade')
+   for record in starmap(EmployeeRecord, csv.reader(open("employees.csv", "rb"))):
+       print(emp.name, emp.title)
+
+When casting a single record to a *NamedTuple*, use the star-operator [#]_ to unpack
+the values::
+
+   >>> t = [11, 22]
+   >>> Point(*t)               # the star-operator unpacks any iterable object
+   Point(x=11, y=22)
+
+In addition to the methods inherited from tuples, named tuples support
+an additonal method and an informational read-only attribute.
+
+.. method:: somenamedtuple.replace(field, value)
+
+   Return a new instance of the named tuple replacing the named *field* with a new *value*::
+
+      >>> p = Point(x=11, y=22)
+      >>> p.__replace__('x', 33)
+      Point(x=33, y=22)
+
+      >>> for recordnum, record in inventory:
+      ...     inventory[recordnum] = record.replace('total', record.price * record.quantity)
+
+.. attribute:: somenamedtuple.__fields__
+
+   Return a tuple of strings listing the field names.  This is useful for introspection,
+   for converting a named tuple instance to a dictionary, and for combining named tuple
+   types to create new named tuple types::
+
+      >>> p.__fields__                         # view the field names
+      ('x', 'y')
+      >>> dict(zip(p.__fields__, p))           # convert to a dictionary
+      {'y': 22, 'x': 11}
+
+      >>> Color = NamedTuple('Color', 'red green blue')
+      >>> pixel_fields = ' '.join(Point.__fields__ + Color.__fields__)  # combine fields
+      >>> Pixel = NamedTuple('Pixel', pixel_fields)
+      >>> Pixel(11, 22, 128, 255, 0)
+      Pixel(x=11, y=22, red=128, green=255, blue=0)'
 
 .. rubric:: Footnotes