Merged revisions 58095-58132,58136-58148,58151-58197 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r58096 | brett.cannon | 2007-09-10 23:38:27 +0200 (Mon, 10 Sep 2007) | 4 lines
Fix a possible segfault from recursing too deep to get the repr of a list.
Closes issue #1096.
........
r58097 | bill.janssen | 2007-09-10 23:51:02 +0200 (Mon, 10 Sep 2007) | 33 lines
More work on SSL support.
* Much expanded test suite:
All protocols tested against all other protocols.
All protocols tested with all certificate options.
Tests for bad key and bad cert.
Test of STARTTLS functionality.
Test of RAND_* functions.
* Fixes for threading/malloc bug.
* Issue 1065 fixed:
sslsocket class renamed to SSLSocket.
sslerror class renamed to SSLError.
Function "wrap_socket" now used to wrap an existing socket.
* Issue 1583946 finally fixed:
Support for subjectAltName added.
Subject name now returned as proper DN list of RDNs.
* SSLError exported from socket as "sslerror".
* RAND_* functions properly exported from ssl.py.
* Documentation improved:
Example of how to create a self-signed certificate.
Better indexing.
........
r58098 | guido.van.rossum | 2007-09-11 00:02:25 +0200 (Tue, 11 Sep 2007) | 9 lines
Patch # 1140 (my code, approved by Effbot).
Make sure the type of the return value of re.sub(x, y, z) is the type
of y+x (i.e. unicode if either is unicode, str if they are both str)
even if there are no substitutions or if x==z (which triggered various
special cases in join_list()).
Could be backported to 2.5; no need to port to 3.0.
........
r58099 | guido.van.rossum | 2007-09-11 00:36:02 +0200 (Tue, 11 Sep 2007) | 8 lines
Patch # 1026 by Benjamin Aranguren (with Alex Martelli):
Backport abc.py and isinstance/issubclass overloading to 2.6.
I had to backport test_typechecks.py myself, and make one small change
to abc.py to avoid duplicate work when x.__class__ and type(x) are the
same.
........
r58100 | bill.janssen | 2007-09-11 01:41:24 +0200 (Tue, 11 Sep 2007) | 3 lines
A better way of finding an open port to test with.
........
r58101 | bill.janssen | 2007-09-11 03:09:19 +0200 (Tue, 11 Sep 2007) | 4 lines
Make sure test_ssl doesn't reference the ssl module in a
context where it can't be imported.
........
r58102 | bill.janssen | 2007-09-11 04:42:07 +0200 (Tue, 11 Sep 2007) | 3 lines
Fix some documentation bugs.
........
r58103 | nick.coghlan | 2007-09-11 16:01:18 +0200 (Tue, 11 Sep 2007) | 1 line
Always use the -E flag when spawning subprocesses in test_cmd_line (Issue 1056)
........
r58106 | thomas.heller | 2007-09-11 21:17:48 +0200 (Tue, 11 Sep 2007) | 3 lines
Disable some tests that fail on the 'ppc Debian unstable' buildbot to
find out if they cause the segfault on the 'alpha Debian' machine.
........
r58108 | brett.cannon | 2007-09-11 23:02:28 +0200 (Tue, 11 Sep 2007) | 6 lines
Generators had their throw() method allowing string exceptions. That's a
no-no.
Fixes issue #1147. Need to fix 2.5 to raise a proper warning if a string
exception is passed in.
........
r58112 | georg.brandl | 2007-09-12 20:03:51 +0200 (Wed, 12 Sep 2007) | 3 lines
New documentation page for the bdb module.
(This doesn't need to be merged to Py3k.)
........
r58114 | georg.brandl | 2007-09-12 20:05:57 +0200 (Wed, 12 Sep 2007) | 2 lines
Bug #1152: use non-deprecated name in example.
........
r58115 | georg.brandl | 2007-09-12 20:08:33 +0200 (Wed, 12 Sep 2007) | 2 lines
Fix #1122: wrong return type documented for various _Size() functions.
........
r58117 | georg.brandl | 2007-09-12 20:10:56 +0200 (Wed, 12 Sep 2007) | 2 lines
Fix #1139: PyFile_Encoding really is PyFile_SetEncoding.
........
r58119 | georg.brandl | 2007-09-12 20:29:18 +0200 (Wed, 12 Sep 2007) | 2 lines
bug #1154: release memory allocated by "es" PyArg_ParseTuple format specifier.
........
r58121 | bill.janssen | 2007-09-12 20:52:05 +0200 (Wed, 12 Sep 2007) | 1 line
root certificate for https://svn.python.org/, used in test_ssl
........
r58122 | georg.brandl | 2007-09-12 21:00:07 +0200 (Wed, 12 Sep 2007) | 3 lines
Bug #1153: repr.repr() now doesn't require set and dictionary items
to be orderable to properly represent them.
........
r58125 | georg.brandl | 2007-09-12 21:29:28 +0200 (Wed, 12 Sep 2007) | 4 lines
#1120: put explicit version in the shebang lines of pydoc, idle
and smtpd.py scripts that are installed by setup.py. That way, they
work when only "make altinstall" is used.
........
r58139 | mark.summerfield | 2007-09-13 16:54:30 +0200 (Thu, 13 Sep 2007) | 9 lines
Replaced variable o with obj in operator.rst because o is easy to
confuse.
Added a note about Python 3's collections.Mapping etc., above section
that describes isMappingType() etc.
Added xrefs between os, os.path, fileinput, and open().
........
r58143 | facundo.batista | 2007-09-13 20:13:15 +0200 (Thu, 13 Sep 2007) | 7 lines
Merged the decimal-branch (revisions 54886 to 58140). Decimal is now
fully updated to the latests Decimal Specification (v1.66) and the
latests test cases (v2.56).
Thanks to Mark Dickinson for all his help during this process.
........
r58145 | facundo.batista | 2007-09-13 20:42:09 +0200 (Thu, 13 Sep 2007) | 7 lines
Put the parameter watchexp back in (changed watchexp from an int
to a bool). Also second argument to watchexp is now converted
to Decimal, just as with all the other two-argument operations.
Thanks Mark Dickinson.
........
r58147 | andrew.kuchling | 2007-09-14 00:49:34 +0200 (Fri, 14 Sep 2007) | 1 line
Add various items
........
r58148 | andrew.kuchling | 2007-09-14 00:50:10 +0200 (Fri, 14 Sep 2007) | 1 line
Make target unique
........
r58154 | facundo.batista | 2007-09-14 20:58:34 +0200 (Fri, 14 Sep 2007) | 3 lines
Included the new functions, and new descriptions.
........
r58155 | thomas.heller | 2007-09-14 21:40:35 +0200 (Fri, 14 Sep 2007) | 2 lines
ctypes.util.find_library uses dump(1) instead of objdump(1) on Solaris.
Fixes issue #1777530; will backport to release25-maint.
........
r58159 | facundo.batista | 2007-09-14 23:29:52 +0200 (Fri, 14 Sep 2007) | 3 lines
Some additions (examples and a bit on the tutorial).
........
r58160 | georg.brandl | 2007-09-15 18:53:36 +0200 (Sat, 15 Sep 2007) | 2 lines
Remove bdb from the "undocumented modules" list.
........
r58164 | bill.janssen | 2007-09-17 00:06:00 +0200 (Mon, 17 Sep 2007) | 15 lines
Add support for asyncore server-side SSL support. This requires
adding the 'makefile' method to ssl.SSLSocket, and importing the
requisite fakefile class from socket.py, and making the appropriate
changes to it to make it use the SSL connection.
Added sample HTTPS server to test_ssl.py, and test that uses it.
Change SSL tests to use https://svn.python.org/, instead of
www.sf.net and pop.gmail.com.
Added utility function to ssl module, get_server_certificate,
to wrap up the several things to be done to pull a certificate
from a remote server.
........
r58173 | bill.janssen | 2007-09-17 01:16:46 +0200 (Mon, 17 Sep 2007) | 1 line
use binary mode when reading files for testAsyncore to make Windows happy
........
r58175 | raymond.hettinger | 2007-09-17 02:55:00 +0200 (Mon, 17 Sep 2007) | 7 lines
Sync-up named tuples with the latest version of the ASPN recipe.
Allows optional commas in the field-name spec (help when named tuples are used in conjuction with sql queries).
Adds the __fields__ attribute for introspection and to support conversion to dictionary form.
Adds a __replace__() method similar to str.replace() but using a named field as a target.
Clean-up spelling and presentation in doc-strings.
........
r58176 | brett.cannon | 2007-09-17 05:28:34 +0200 (Mon, 17 Sep 2007) | 5 lines
Add a bunch of GIL release/acquire points in tp_print implementations and for
PyObject_Print().
Closes issue #1164.
........
r58177 | sean.reifschneider | 2007-09-17 07:45:04 +0200 (Mon, 17 Sep 2007) | 2 lines
issue1597011: Fix for bz2 module corner-case error due to error checking bug.
........
r58180 | facundo.batista | 2007-09-17 18:26:50 +0200 (Mon, 17 Sep 2007) | 3 lines
Decimal is updated, :)
........
r58181 | facundo.batista | 2007-09-17 19:30:13 +0200 (Mon, 17 Sep 2007) | 5 lines
The methods always return Decimal classes, even if they're
executed through a subclass (thanks Mark Dickinson).
Added a bit of testing for this.
........
r58183 | sean.reifschneider | 2007-09-17 22:53:21 +0200 (Mon, 17 Sep 2007) | 2 lines
issue1082: Fixing platform and system for Vista.
........
r58185 | andrew.kuchling | 2007-09-18 03:36:16 +0200 (Tue, 18 Sep 2007) | 1 line
Add item; sort properly
........
r58186 | raymond.hettinger | 2007-09-18 05:33:19 +0200 (Tue, 18 Sep 2007) | 1 line
Handle corner cased on 0-tuples and 1-tuples. Add verbose option so people can see how it works.
........
r58192 | georg.brandl | 2007-09-18 09:24:40 +0200 (Tue, 18 Sep 2007) | 2 lines
A bit of reordering, also show more subheadings in the lang ref index.
........
r58193 | facundo.batista | 2007-09-18 18:53:18 +0200 (Tue, 18 Sep 2007) | 4 lines
Speed up of the various division operations (remainder, divide,
divideint and divmod). Thanks Mark Dickinson.
........
r58197 | raymond.hettinger | 2007-09-19 00:18:02 +0200 (Wed, 19 Sep 2007) | 1 line
Cleanup docs for NamedTuple.
........
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index fe57f12..227f721 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -395,11 +395,14 @@
.. _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
@@ -407,43 +410,88 @@
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.
+ 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.
- Example::
+ If *verbose* is true, the *NamedTuple* call will print the class definition.
- >>> 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)
+ *NamedTuple* instances do not have per-instance dictionaries, so they are
+ lightweight, requiring no more memory than regular tuples.
- 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::
+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)
+ >>> 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))
- To cast an individual record stored as :class:`list`, :class:`tuple`, or some
- other iterable type, use the star-operator [#]_ to unpack the values::
+ >>> 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)
- >>> Color = NamedTuple('Color', 'name code')
- >>> m = dict(red=1, green=2, blue=3)
- >>> print(Color(*m.popitem()))
- Color(name='blue', code=3)
+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