Merged revisions 67326,67498,67531-67532,67538,67553-67554,67556-67557 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r67326 | benjamin.peterson | 2008-11-22 02:59:15 +0100 (Sat, 22 Nov 2008) | 1 line

  backport r67325: make FileIO.mode always contain 'b'
........
  r67498 | raymond.hettinger | 2008-12-03 16:42:10 +0100 (Wed, 03 Dec 2008) | 1 line

  Backport r67478
........
  r67531 | georg.brandl | 2008-12-04 19:54:05 +0100 (Thu, 04 Dec 2008) | 2 lines

  Add reference to enumerate() to indices example.
........
  r67532 | georg.brandl | 2008-12-04 19:59:16 +0100 (Thu, 04 Dec 2008) | 2 lines

  Add another heapq example.
........
  r67538 | georg.brandl | 2008-12-04 22:28:16 +0100 (Thu, 04 Dec 2008) | 2 lines

  Clarification to avoid confusing output with file descriptors.
........
  r67553 | georg.brandl | 2008-12-05 08:49:49 +0100 (Fri, 05 Dec 2008) | 2 lines

  #4408: document regex.groups.
........
  r67554 | georg.brandl | 2008-12-05 08:52:26 +0100 (Fri, 05 Dec 2008) | 2 lines

  #4409: fix asterisks looking like footnotes.
........
  r67556 | georg.brandl | 2008-12-05 09:02:17 +0100 (Fri, 05 Dec 2008) | 2 lines

  #4441: improve doc for os.open() flags.
........
  r67557 | georg.brandl | 2008-12-05 09:06:57 +0100 (Fri, 05 Dec 2008) | 2 lines

  Add an index entry for "subclassing immutable types".
........

12 files changed, 74 insertions, 42 deletions

diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst
index 5cf8163..2190b80 100644
--- a/Doc/library/heapq.rst
+++ b/Doc/library/heapq.rst
@@ -88,6 +88,21 @@ Example of use:
    >>> print data == ordered
    True
 
+Using a heap to insert items at the correct place in a priority queue:
+
+   >>> heap = []
+   >>> data = [(1, 'J'), (4, 'N'), (3, 'H'), (2, 'O')]
+   >>> for item in data:
+   ...     heappush(heap, item)
+   ...
+   >>> while heap:
+   ...     print heappop(heap)[1]
+   J
+   O
+   H
+   N
+
+   
 The module also offers three general purpose functions based on heaps.
 
 
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 1cb450b..6136e41 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -681,10 +681,11 @@ by file descriptors.
       :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its :meth:`write`
       method.
 
-The following data items are available for use in constructing the *flags*
-parameter to the :func:`open` function.  Some items will not be available on all
-platforms.  For descriptions of their availability and use, consult
-:manpage:`open(2)`.
+The following constants are options for the *flags* parameter to the
+:func:`open` function.  They can be combined using the bitwise OR operator
+``|``.  Some of them are not available on all platforms.  For descriptions of
+their availability and use, consult the :manpage:`open(2)` manual page or the
+respective documentation for your operating system.
 
 
 .. data:: O_RDONLY
@@ -695,8 +696,7 @@ platforms.  For descriptions of their availability and use, consult
           O_EXCL
           O_TRUNC
 
-   Options for the *flag* argument to the :func:`open` function. These can be
-   combined using the bitwise OR operator ``|``. Availability: Unix, Windows.
+   These constants are available on Unix and Windows.
 
 
 .. data:: O_DSYNC
@@ -708,8 +708,7 @@ platforms.  For descriptions of their availability and use, consult
           O_SHLOCK
           O_EXLOCK
 
-   More options for the *flag* argument to the :func:`open` function. Availability:
-   Unix.
+   These constants are only available on Unix.
 
 
 .. data:: O_BINARY
@@ -720,8 +719,7 @@ platforms.  For descriptions of their availability and use, consult
           O_SEQUENTIAL
           O_TEXT
 
-   Options for the *flag* argument to the :func:`open` function. These can be
-   combined using the bitwise OR operator ``|``. Availability: Windows.
+   These constants are only available on Windows.
 
 
 .. data:: O_ASYNC
@@ -730,8 +728,8 @@ platforms.  For descriptions of their availability and use, consult
           O_NOFOLLOW
           O_NOATIME
 
-   Options for the *flag* argument to the :func:`open` function. These are
-   GNU extensions and not present if they are not defined by the C library.
+   These constants are GNU extensions and not present if they are not defined by
+   the C library.
 
 
 .. data:: SEEK_SET
diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index c9466af..916feca 100644
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -750,6 +750,11 @@ attributes:
    were provided.
 
 
+.. attribute:: RegexObject.groups
+
+   The number of capturing groups in the pattern.
+
+
 .. attribute:: RegexObject.groupindex
 
    A dictionary mapping any symbolic group names defined by ``(?P<id>)`` to group
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 42e50f6..dae582c 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -207,7 +207,7 @@ Instances of the :class:`Popen` class have the following methods:
    *input* argument should be a string to be sent to the child process, or
    ``None``, if no data should be sent to the child.
 
-   :meth:`communicate` returns a tuple ``(stdout, stderr)``.
+   :meth:`communicate` returns a tuple ``(stdoutdata, stderrdata)``.
 
    Note that if you want to send data to the process's stdin, you need to create
    the Popen object with ``stdin=PIPE``.  Similarly, to get anything other than
@@ -358,8 +358,8 @@ A more realistic example would look like this::
        print >>sys.stderr, "Execution failed:", e
 
 
-Replacing os.spawn\*
-^^^^^^^^^^^^^^^^^^^^
+Replacing the os.spawn family
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 P_NOWAIT example::
 
@@ -386,8 +386,8 @@ Environment example::
    Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
 
 
-Replacing os.popen\*
-^^^^^^^^^^^^^^^^^^^^
+Replacing os.popen, os.popen2, os.popen3
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -430,8 +430,8 @@ Replacing os.popen\*
    (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
 
 
-Replacing popen2.\*
-^^^^^^^^^^^^^^^^^^^
+Replacing functions from the popen2 module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. note::
 
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 7304c9c..4dcc96f 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1162,9 +1162,10 @@ of this is the :class:`NodeList` interface in the W3C's Document Object Model.)
 Basic customization
 -------------------
 
-
 .. method:: object.__new__(cls[, ...])
 
+   .. index:: pair: subclassing; immutable types
+
    Called to create a new instance of class *cls*.  :meth:`__new__` is a static
    method (special-cased so you need not declare it as such) that takes the class
    of which an instance was requested as its first argument.  The remaining
diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
index 809afc1..f57e9e9 100644
--- a/Doc/tutorial/controlflow.rst
+++ b/Doc/tutorial/controlflow.rst
@@ -104,8 +104,8 @@ increment (even negative; sometimes this is called the 'step')::
    >>> range(-10, -100, -30)
    [-10, -40, -70]
 
-To iterate over the indices of a sequence, combine :func:`range` and :func:`len`
-as follows::
+To iterate over the indices of a sequence, you can combine :func:`range` and
+:func:`len` as follows::
 
    >>> a = ['Mary', 'had', 'a', 'little', 'lamb']
    >>> for i in range(len(a)):
@@ -117,6 +117,9 @@ as follows::
    3 little
    4 lamb
 
+In most such cases, however, it is convenient to use the :func:`enumerate`
+function, see :ref:`tut-loopidioms`.
+
 
 .. _tut-break:
 
diff --git a/Lib/test/list_tests.py b/Lib/test/list_tests.py
index b3f24d3..c9aa316 100644
--- a/Lib/test/list_tests.py
+++ b/Lib/test/list_tests.py
@@ -84,6 +84,8 @@ class CommonTest(seq_tests.CommonTest):
         self.assertRaises(StopIteration, r.next)
         self.assertEqual(list(reversed(self.type2test())),
                          self.type2test())
+        # Bug 3689: make sure list-reversed-iterator doesn't have __len__
+        self.assertRaises(TypeError, len, reversed([1,2,3]))
 
     def test_setitem(self):
         a = self.type2test([0, 1])
diff --git a/Lib/test/test_fileio.py b/Lib/test/test_fileio.py
index cbc7165..c978779 100644
--- a/Lib/test/test_fileio.py
+++ b/Lib/test/test_fileio.py
@@ -50,7 +50,7 @@ class AutoFileTests(unittest.TestCase):
         # verify expected attributes exist
         f = self.f
 
-        self.assertEquals(f.mode, "w")
+        self.assertEquals(f.mode, "wb")
         self.assertEquals(f.closed, False)
 
         # verify the attributes are readonly
@@ -160,7 +160,7 @@ class OtherFileTests(unittest.TestCase):
 
     def testModeStrings(self):
         # check invalid mode strings
-        for mode in ("", "aU", "wU+", "rb", "rt"):
+        for mode in ("", "aU", "wU+", "rw", "rt"):
             try:
                 f = _fileio._FileIO(TESTFN, mode)
             except ValueError:
diff --git a/Lib/test/test_io.py b/Lib/test/test_io.py
index c9bd38d..eb41d1f 100644
--- a/Lib/test/test_io.py
+++ b/Lib/test/test_io.py
@@ -1266,7 +1266,7 @@ class MiscIOTest(unittest.TestCase):
 
     def test_attributes(self):
         f = io.open(test_support.TESTFN, "wb", buffering=0)
-        self.assertEquals(f.mode, "w")
+        self.assertEquals(f.mode, "wb")
         f.close()
 
         f = io.open(test_support.TESTFN, "U")
@@ -1274,18 +1274,18 @@ class MiscIOTest(unittest.TestCase):
         self.assertEquals(f.buffer.name,     test_support.TESTFN)
         self.assertEquals(f.buffer.raw.name, test_support.TESTFN)
         self.assertEquals(f.mode,            "U")
-        self.assertEquals(f.buffer.mode,     "r")
-        self.assertEquals(f.buffer.raw.mode, "r")
+        self.assertEquals(f.buffer.mode,     "rb")
+        self.assertEquals(f.buffer.raw.mode, "rb")
         f.close()
 
         f = io.open(test_support.TESTFN, "w+")
         self.assertEquals(f.mode,            "w+")
-        self.assertEquals(f.buffer.mode,     "r+") # Does it really matter?
-        self.assertEquals(f.buffer.raw.mode, "r+")
+        self.assertEquals(f.buffer.mode,     "rb+") # Does it really matter?
+        self.assertEquals(f.buffer.raw.mode, "rb+")
 
         g = io.open(f.fileno(), "wb", closefd=False)
-        self.assertEquals(g.mode,     "w")
-        self.assertEquals(g.raw.mode, "w")
+        self.assertEquals(g.mode,     "wb")
+        self.assertEquals(g.raw.mode, "wb")
         self.assertEquals(g.name,     f.fileno())
         self.assertEquals(g.raw.name, f.fileno())
         f.close()
diff --git a/Misc/NEWS b/Misc/NEWS
index af50cf7..876abc8 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -17,9 +17,14 @@ Core and Builtins
   kept open but the file object behaves like a closed file. The ``FileIO``
   object also got a new readonly attribute ``closefd``.
 
+- Issue #3689: The list reversed iterator now supports __length_hint__
+  instead of __len__.  Behavior now matches other reversed iterators.
+
 Library
 -------
 
+- FileIO's mode attribute now always includes ``"b"``.
+
 
 What's New in Python 2.6.1
 ==========================
diff --git a/Modules/_fileio.c b/Modules/_fileio.c
index b9310f3..65cc99d 100644
--- a/Modules/_fileio.c
+++ b/Modules/_fileio.c
@@ -208,6 +208,8 @@ fileio_init(PyObject *oself, PyObject *args, PyObject *kwds)
 			flags |= O_CREAT;
 			append = 1;
 			break;
+		case 'b':
+			break;
 		case '+':
 			if (plus)
 				goto bad_mode;
@@ -682,12 +684,12 @@ mode_string(PyFileIOObject *self)
 {
 	if (self->readable) {
 		if (self->writable)
-			return "r+";
+			return "rb+";
 		else
-			return "r";
+			return "rb";
 	}
 	else
-		return "w";
+		return "wb";
 }
 
 static PyObject *
diff --git a/Objects/listobject.c b/Objects/listobject.c
index e8379e1..7b4bf35 100644
--- a/Objects/listobject.c
+++ b/Objects/listobject.c
@@ -2911,11 +2911,11 @@ static PyObject *list_reversed(PyListObject *, PyObject *);
 static void listreviter_dealloc(listreviterobject *);
 static int listreviter_traverse(listreviterobject *, visitproc, void *);
 static PyObject *listreviter_next(listreviterobject *);
-static Py_ssize_t listreviter_len(listreviterobject *);
+static PyObject *listreviter_len(listreviterobject *);
 
-static PySequenceMethods listreviter_as_sequence = {
-	(lenfunc)listreviter_len,	/* sq_length */
-	0,				/* sq_concat */
+static PyMethodDef listreviter_methods[] = {
+	{"__length_hint__", (PyCFunction)listreviter_len, METH_NOARGS, length_hint_doc},
+ 	{NULL,		NULL}		/* sentinel */
 };
 
 PyTypeObject PyListRevIter_Type = {
@@ -2931,7 +2931,7 @@ PyTypeObject PyListRevIter_Type = {
 	0,					/* tp_compare */
 	0,					/* tp_repr */
 	0,					/* tp_as_number */
-	&listreviter_as_sequence,		/* tp_as_sequence */
+	0,					/* tp_as_sequence */
 	0,					/* tp_as_mapping */
 	0,					/* tp_hash */
 	0,					/* tp_call */
@@ -2947,6 +2947,7 @@ PyTypeObject PyListRevIter_Type = {
 	0,					/* tp_weaklistoffset */
 	PyObject_SelfIter,			/* tp_iter */
 	(iternextfunc)listreviter_next,		/* tp_iternext */
+	listreviter_methods,		/* tp_methods */
 	0,
 };
 
@@ -3002,11 +3003,11 @@ listreviter_next(listreviterobject *it)
 	return NULL;
 }
 
-static Py_ssize_t
+static PyObject *
 listreviter_len(listreviterobject *it)
 {
 	Py_ssize_t len = it->it_index + 1;
 	if (it->it_seq == NULL || PyList_GET_SIZE(it->it_seq) < len)
-		return 0;
-	return len;
+		len = 0;
+	return PyLong_FromSsize_t(len);
 }