Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from

svn+ssh://svn.python.org/python/branches/py3k

........
  r87101 | georg.brandl | 2010-12-06 23:02:48 +0100 (Mo, 06 Dez 2010) | 1 line

  Remove visible XXX comments.
........
  r87146 | georg.brandl | 2010-12-09 19:08:43 +0100 (Do, 09 Dez 2010) | 1 line

  Fix "seperate".
........
  r87156 | georg.brandl | 2010-12-10 11:01:44 +0100 (Fr, 10 Dez 2010) | 1 line

  #10668: fix wrong call of __init__.
........
  r87172 | georg.brandl | 2010-12-11 20:10:30 +0100 (Sa, 11 Dez 2010) | 1 line

  Avoid AttributeError(_closed) when a TemporaryDirectory is deallocated whose mkdtemp call failed.
........
  r87175 | georg.brandl | 2010-12-11 23:19:34 +0100 (Sa, 11 Dez 2010) | 1 line

  Fix markup.
........
  r87371 | georg.brandl | 2010-12-18 17:21:58 +0100 (Sa, 18 Dez 2010) | 1 line

  Fix typo.
........
  r87378 | georg.brandl | 2010-12-18 18:51:28 +0100 (Sa, 18 Dez 2010) | 1 line

  #10723: add missing builtin exceptions.
........
  r87522 | georg.brandl | 2010-12-28 10:16:12 +0100 (Di, 28 Dez 2010) | 1 line

  Replace sys.maxint mention by sys.maxsize.
........
  r87523 | georg.brandl | 2010-12-28 10:18:24 +0100 (Di, 28 Dez 2010) | 1 line

  Remove confusing paragraph -- this is relevant only to advanced users anyway and does not belong into the tutorial.
........
  r87524 | georg.brandl | 2010-12-28 10:29:19 +0100 (Di, 28 Dez 2010) | 1 line

  Fix advice: call PyType_Ready to fill in ob_type of custom types.
........
  r87526 | georg.brandl | 2010-12-28 11:38:33 +0100 (Di, 28 Dez 2010) | 1 line

  #10777: fix iteration over dict keys while mutating the dict.
........
  r87527 | georg.brandl | 2010-12-28 11:56:20 +0100 (Di, 28 Dez 2010) | 1 line

  #10768: fix ScrolledText widget construction, and make the example work from the interactive shell.
........
  r87528 | georg.brandl | 2010-12-28 12:02:12 +0100 (Di, 28 Dez 2010) | 1 line

  Add news entry and clarify another.
........
  r87530 | georg.brandl | 2010-12-28 12:06:07 +0100 (Di, 28 Dez 2010) | 1 line

  #10767: update README in crashers; not all may have a bug entry and/or be fixed.
........
  r87531 | georg.brandl | 2010-12-28 12:08:17 +0100 (Di, 28 Dez 2010) | 1 line

  #10742: document readonly attribute of memoryviews.
........
  r87532 | georg.brandl | 2010-12-28 12:15:49 +0100 (Di, 28 Dez 2010) | 1 line

  #10781: clarify that *encoding* is not a parameter for Node objects in general.
........
  r87533 | georg.brandl | 2010-12-28 12:38:12 +0100 (Di, 28 Dez 2010) | 1 line

  Remove history; adapt a bit more to reST, since this will once be part of the dev guide.
........
  r87534 | georg.brandl | 2010-12-28 12:48:53 +0100 (Di, 28 Dez 2010) | 1 line

  Rewrap.
........
  r87535 | georg.brandl | 2010-12-28 12:49:41 +0100 (Di, 28 Dez 2010) | 1 line

  #10739: document that on Windows, socket.makefile() does not make a file that has a true file descriptor usable where such a thing is expected.
........
  r87536 | georg.brandl | 2010-12-28 12:53:25 +0100 (Di, 28 Dez 2010) | 1 line

  #10609: fix non-working dbm example.
........
  r87581 | georg.brandl | 2010-12-30 18:36:17 +0100 (Do, 30 Dez 2010) | 1 line

  Fix NameErrors.
........

Doc/ACKS.txt

@@ -112,6 +112,7 @@ docs@python.org), and we'll be glad to correct the problem.
    * Andrew M. Kuchling
    * Dave Kuhlman
    * Erno Kuusela
+   * Ross Lagerwall
    * Thomas Lamb
    * Detlef Lannert
    * Piers Lauder

Doc/c-api/slice.rst

@@ -48,4 +48,3 @@ Slice Objects
    normal slices.
 
    Returns 0 on success and -1 on error with exception set.
-

Doc/c-api/typeobj.rst

@@ -705,7 +705,9 @@ type objects) *must* have the :attr:`ob_size` field.
    This field is not inherited by subtypes (computed attributes are inherited
    through a different mechanism).
 
-   Docs for PyGetSetDef (XXX belong elsewhere)::
+   .. XXX belongs elsewhere
+
+   Docs for PyGetSetDef::
 
       typedef PyObject *(*getter)(PyObject *, void *);
       typedef int (*setter)(PyObject *, PyObject *, void *);
@@ -752,7 +754,7 @@ type objects) *must* have the :attr:`ob_size` field.
 
       PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
 
-   XXX explain.
+   .. XXX explain.
 
    This field is inherited by subtypes.
 
@@ -767,7 +769,7 @@ type objects) *must* have the :attr:`ob_size` field.
 
    This field is inherited by subtypes.
 
-   XXX explain.
+   .. XXX explain.
 
 
 .. cmember:: long PyTypeObject.tp_dictoffset

Doc/extending/windows.rst

@@ -179,8 +179,8 @@ constant".  This shows up when building DLL under MSVC.  Change it to::
 
 and add the following to the module initialization function::
 
-   MyObject_Type.ob_type = &PyType_Type;
+   if (PyType_Ready(&MyObject_Type) < 0)
-
+        return NULL;
 
 
 .. _dynamic-linking:

Doc/glossary.rst

@@ -179,22 +179,22 @@ Glossary
       not expressions.
 
    extension module
-      A module written in C or C++, using Python's C API to interact with the core and
+      A module written in C or C++, using Python's C API to interact with the
-      with user code.
+      core and with user code.
 
    file object
       An object exposing a file-oriented API (with methods such as
-      :meth:`read()` or :meth:`write()`) to an underlying resource.
+      :meth:`read()` or :meth:`write()`) to an underlying resource.  Depending
-      Depending on the way it was created, a file object can mediate access
+      on the way it was created, a file object can mediate access to a real
-      to a real on-disk file or to another other type of storage or
+      on-disk file or to another other type of storage or communication device
-      communication device (for example standard input/output, in-memory
+      (for example standard input/output, in-memory buffers, sockets, pipes,
-      buffers, sockets, pipes, etc.).  File objects are also called
+      etc.).  File objects are also called :dfn:`file-like objects` or
-      :dfn:`file-like objects` or :dfn:`streams`.
+      :dfn:`streams`.
 
-      There are actually three categories of file objects: raw binary
+      There are actually three categories of file objects: raw binary files,
-      files, buffered binary files and text files.  Their interfaces are
+      buffered binary files and text files.  Their interfaces are defined in the
-      defined in the :mod:`io` module.  The canonical way to create a
+      :mod:`io` module.  The canonical way to create a file object is by using
-      file object is by using the :func:`open` function.
+      the :func:`open` function.
 
    file-like object
       A synonym for :term:`file object`.

Doc/library/collections.rst

@@ -810,7 +810,7 @@ If a new entry overwrites an existing entry, the
 original insertion position is changed and moved to the end::
 
     class LastUpdatedOrderedDict(OrderedDict):
-        'Store items is the order the keys were last added'
+        'Store items in the order the keys were last added'
         def __setitem__(self, key, value):
             if key in self:
                 del self[key]

Doc/library/dbm.rst

@@ -86,10 +86,8 @@ then prints out the contents of the database::
    # Notice how the value is now in bytes.
    assert db['www.cnn.com'] == b'Cable News Network'
 
-   # Loop through contents.  Other dictionary methods
+   # Often-used methods of the dict interface work too.
-   # such as .keys(), .values() also work.
+   print(db.get('python.org', b'not present'))
-   for k, v in db.iteritems():
-       print(k, '\t', v)
 
    # Storing a non-string key or value will raise an exception (most
    # likely a TypeError).

Doc/library/exceptions.rst

@@ -77,6 +77,12 @@ The following exceptions are used mostly as base classes for other exceptions.
    :exc:`FloatingPointError`.
 
 
+.. exception:: BufferError
+
+   Raised when a :ref:`buffer <bufferobjects>` related operation cannot be
+   performed.
+
+
 .. exception:: LookupError
 
    The base class for the exceptions that are raised when a key or index used on
@@ -271,6 +277,18 @@ The following exceptions are the exceptions that are usually raised.
    of the exception instance returns only the message.
 
 
+.. exception:: IndentationError
+
+   Base class for syntax errors related to incorrect indentation.  This is a
+   subclass of :exc:`SyntaxError`.
+
+
+.. exception:: TabError
+
+   Raised when indentation contains an inconsistent use of tabs and spaces.
+   This is a subclass of :exc:`IndentationError`.
+
+
 .. exception:: SystemError
 
    Raised when the interpreter finds an internal error, but the situation does not

Doc/library/socket.rst

@@ -616,16 +616,21 @@ correspond to Unix system calls applicable to sockets.
 
    .. index:: single: I/O control; buffering
 
-   Return a :term:`file object` associated with the socket.  The exact
+   Return a :term:`file object` associated with the socket.  The exact returned
-   returned type depends on the arguments given to :meth:`makefile`.  These
+   type depends on the arguments given to :meth:`makefile`.  These arguments are
-   arguments are interpreted the same way as by the built-in :func:`open`
+   interpreted the same way as by the built-in :func:`open` function.
-   function.
 
    Closing the file object won't close the socket unless there are no remaining
    references to the socket.  The socket must be in blocking mode; it can have
    a timeout, but the file object's internal buffer may end up in a inconsistent
    state if a timeout occurs.
 
+   .. note::
+
+      On Windows, the file-like object created by :meth:`makefile` cannot be
+      used where a file object with a file descriptor is expected, such as the
+      stream arguments of :meth:`subprocess.Popen`.
+
 
 .. method:: socket.recv(bufsize[, flags])
 

Doc/library/stdtypes.rst

@@ -2203,6 +2203,10 @@ copying.  Memory is generally interpreted as simple bytes.
       A tuple of integers the length of :attr:`ndim` giving the size in bytes to
       access each element for each dimension of the array.
 
+   .. attribute:: readonly
+
+      A bool indicating whether the memory is read only.
+
    .. memoryview.suboffsets isn't documented because it only seems useful for C
 
 

Doc/library/xml.dom.minidom.rst

@@ -125,7 +125,7 @@ module documentation.  This section lists the differences between the API and
    to discard children of that node.
 
 
-.. method:: Node.writexml(writer, indent="", addindent="", newl="", encoding="")
+.. method:: Node.writexml(writer, indent="", addindent="", newl="")
 
    Write XML to the writer object.  The writer should have a :meth:`write` method
    which matches that of the file object interface.  The *indent* parameter is the
@@ -133,8 +133,8 @@ module documentation.  This section lists the differences between the API and
    indentation to use for subnodes of the current one.  The *newl* parameter
    specifies the string to use to terminate newlines.
 
-   For the :class:`Document` node, an additional keyword argument *encoding* can be
+   For the :class:`Document` node, an additional keyword argument *encoding* can
-   used to specify the encoding field of the XML header.
+   be used to specify the encoding field of the XML header.
 
 
 .. method:: Node.toxml(encoding=None)

Doc/tutorial/interpreter.rst

@@ -58,14 +58,6 @@ Some Python modules are also useful as scripts.  These can be invoked using
 ``python -m module [arg] ...``, which executes the source file for *module* as
 if you had spelled out its full name on the command line.
 
-Note that there is a difference between ``python file`` and ``python
-<file``.  In the latter case, input requests from the program, such as calling
-``sys.stdin.read()``, are satisfied from *file*.  Since this file has already
-been read until the end by the parser before the program starts executing, the
-program will encounter end-of-file immediately.  In the former case (which is
-usually what you want) they are satisfied from whatever file or device is
-connected to standard input of the Python interpreter.
-
 When a script file is used, it is sometimes useful to be able to run the script
 and enter interactive mode afterwards.  This can be done by passing :option:`-i`
 before the script.  (This does not work if the script is read from standard

Lib/test/crashers/README

@@ -1,20 +1,16 @@
-This directory only contains tests for outstanding bugs that cause
+This directory only contains tests for outstanding bugs that cause the
-the interpreter to segfault.  Ideally this directory should always
+interpreter to segfault.  Ideally this directory should always be empty, but
-be empty.  Sometimes it may not be easy to fix the underlying cause.
+sometimes it may not be easy to fix the underlying cause and the bug is deemed
+too obscure to invest the effort.
 
 Each test should fail when run from the command line:
 
 	./python Lib/test/crashers/weakref_in_del.py
 
-Each test should have a link to the bug report:
+Put as much info into a docstring or comments to help determine the cause of the
+failure, as well as a bugs.python.org issue number if it exists.  Particularly
+note if the cause is system or environment dependent and what the variables are.
 
-	# http://python.org/sf/BUG#
+Once the crash is fixed, the test case should be moved into an appropriate test
-
+(even if it was originally from the test suite).  This ensures the regression
-Put as much info into a docstring or comments to help determine
+doesn't happen again.  And if it does, it should be easier to track down.
-the cause of the failure.  Particularly note if the cause is
-system or environment dependent and what the variables are.
-
-Once the crash is fixed, the test case should be moved into an appropriate
-test (even if it was originally from the test suite).  This ensures the
-regression doesn't happen again.  And if it does, it should be easier
-to track down.

Lib/test/test_array.py

@@ -15,7 +15,7 @@ class ArraySubclass(array.array):
 
 class ArraySubclassWithKwargs(array.array):
     def __init__(self, typecode, newarg=None):
-        array.array.__init__(typecode)
+        array.array.__init__(self, typecode)
 
 tests = [] # list to accumulate all tests
 typecodes = "ubBhHiIlLfd"

Lib/tkinter/scrolledtext.py

@@ -39,11 +39,10 @@ class ScrolledText(Text):
 
 
 def example():
-    import __main__
     from tkinter.constants import END
 
     stext = ScrolledText(bg='white', height=10)
-    stext.insert(END, __main__.__doc__)
+    stext.insert(END, __doc__)
     stext.pack(fill=BOTH, side=LEFT, expand=True)
     stext.focus_set()
     stext.mainloop()

Misc/SpecialBuilds.txt

@@ -1,17 +1,20 @@
-This file describes some special Python build types enabled via
+This file describes some special Python build types enabled via compile-time
-compile-time preprocessor defines.
+preprocessor defines.
 
-It is best to define these options in the EXTRA_CFLAGS make variable;
+IMPORTANT: if you want to build a debug-enabled Python, it is recommended that
+you use ``./configure --with-pydebug``, rather than the options listed here.
+
+However, if you wish to define some of these options individually, it is best
+to define them in the EXTRA_CFLAGS make variable;
 ``make EXTRA_CFLAGS="-DPy_REF_DEBUG"``.
 
----------------------------------------------------------------------------
-Py_REF_DEBUG                                              introduced in 1.4
-                                                 named REF_DEBUG before 1.4
 
-Turn on aggregate reference counting.  This arranges that extern
+Py_REF_DEBUG
-_Py_RefTotal hold a count of all references, the sum of ob_refcnt across
+------------
-all objects.  In a debug-mode build, this is where the "8288" comes from
+
-in
+Turn on aggregate reference counting.  This arranges that extern _Py_RefTotal
+hold a count of all references, the sum of ob_refcnt across all objects.  In a
+debug-mode build, this is where the "8288" comes from in
 
     >>> 23
     23
@@ -19,75 +22,72 @@ in
     >>>
 
 Note that if this count increases when you're not storing away new objects,
-there's probably a leak.  Remember, though, that in interactive mode the
+there's probably a leak.  Remember, though, that in interactive mode the special
-special name "_" holds a reference to the last result displayed!
+name "_" holds a reference to the last result displayed!
 
-Py_REF_DEBUG also checks after every decref to verify that the refcount
+Py_REF_DEBUG also checks after every decref to verify that the refcount hasn't
-hasn't gone negative, and causes an immediate fatal error if it has.
+gone negative, and causes an immediate fatal error if it has.
 
 Special gimmicks:
 
 sys.gettotalrefcount()
     Return current total of all refcounts.
-    Available under Py_REF_DEBUG in Python 2.3.
-    Before 2.3, Py_TRACE_REFS was required to enable this function.
----------------------------------------------------------------------------
-Py_TRACE_REFS                                             introduced in 1.4
-                                                named TRACE_REFS before 1.4
 
-Turn on heavy reference debugging.  This is major surgery.  Every PyObject
+
-grows two more pointers, to maintain a doubly-linked list of all live
+Py_TRACE_REFS
-heap-allocated objects.  Most built-in type objects are not in this list,
+-------------
-as they're statically allocated.  Starting in Python 2.3, if COUNT_ALLOCS
+
-(see below) is also defined, a static type object T does appear in this
+Turn on heavy reference debugging.  This is major surgery.  Every PyObject grows
-list if at least one object of type T has been created.
+two more pointers, to maintain a doubly-linked list of all live heap-allocated
+objects.  Most built-in type objects are not in this list, as they're statically
+allocated.  Starting in Python 2.3, if COUNT_ALLOCS (see below) is also defined,
+a static type object T does appear in this list if at least one object of type T
+has been created.
 
 Note that because the fundamental PyObject layout changes, Python modules
-compiled with Py_TRACE_REFS are incompatible with modules compiled without
+compiled with Py_TRACE_REFS are incompatible with modules compiled without it.
-it.
 
 Py_TRACE_REFS implies Py_REF_DEBUG.
 
 Special gimmicks:
 
 sys.getobjects(max[, type])
-    Return list of the (no more than) max most-recently allocated objects,
+    Return list of the (no more than) max most-recently allocated objects, most
-    most recently allocated first in the list, least-recently allocated
+    recently allocated first in the list, least-recently allocated last in the
-    last in the list.  max=0 means no limit on list length.
+    list.  max=0 means no limit on list length.  If an optional type object is
-    If an optional type object is passed, the list is also restricted to
+    passed, the list is also restricted to objects of that type.  The return
-    objects of that type.
+    list itself, and some temp objects created just to call sys.getobjects(),
-    The return list itself, and some temp objects created just to call
+    are excluded from the return list.  Note that the list returned is just
-    sys.getobjects(), are excluded from the return list.  Note that the
+    another object, though, so may appear in the return list the next time you
-    list returned is just another object, though, so may appear in the
+    call getobjects(); note that every object in the list is kept alive too,
-    return list the next time you call getobjects(); note that every
+    simply by virtue of being in the list.
-    object in the list is kept alive too, simply by virtue of being in
-    the list.
 
-envar PYTHONDUMPREFS
+envvar PYTHONDUMPREFS
-    If this envar exists, Py_Finalize() arranges to print a list of
+    If this envvar exists, Py_Finalize() arranges to print a list of all
-    all still-live heap objects.  This is printed twice, in different
+    still-live heap objects.  This is printed twice, in different formats,
-    formats, before and after Py_Finalize has cleaned up everything it
+    before and after Py_Finalize has cleaned up everything it can clean up.  The
-    can clean up.  The first output block produces the repr() of each
+    first output block produces the repr() of each object so is more
-    object so is more informative; however, a lot of stuff destined to
+    informative; however, a lot of stuff destined to die is still alive then.
-    die is still alive then.  The second output block is much harder
+    The second output block is much harder to work with (repr() can't be invoked
-    to work with (repr() can't be invoked anymore -- the interpreter
+    anymore -- the interpreter has been torn down too far), but doesn't list any
-    has been torn down too far), but doesn't list any objects that will
+    objects that will die.  The tool script combinerefs.py can be run over this
-    die.  The tool script combinerefs.py can be run over this to combine
+    to combine the info from both output blocks.  The second output block, and
-    the info from both output blocks.  The second output block, and
     combinerefs.py, were new in Python 2.3b1.
----------------------------------------------------------------------------
+
-PYMALLOC_DEBUG                                            introduced in 2.3
+
+PYMALLOC_DEBUG
+--------------
 
 When pymalloc is enabled (WITH_PYMALLOC is defined), calls to the PyObject_
-memory routines are handled by Python's own small-object allocator, while
+memory routines are handled by Python's own small-object allocator, while calls
-calls to the PyMem_ memory routines are directed to the system malloc/
+to the PyMem_ memory routines are directed to the system malloc/ realloc/free.
-realloc/free.  If PYMALLOC_DEBUG is also defined, calls to both PyObject_
+If PYMALLOC_DEBUG is also defined, calls to both PyObject_ and PyMem_ memory
-and PyMem_ memory routines are directed to a special debugging mode of
+routines are directed to a special debugging mode of Python's small-object
-Python's small-object allocator.
+allocator.
 
-This mode fills dynamically allocated memory blocks with special,
+This mode fills dynamically allocated memory blocks with special, recognizable
-recognizable bit patterns, and adds debugging info on each end of
+bit patterns, and adds debugging info on each end of dynamically allocated
-dynamically allocated memory blocks.  The special bit patterns are:
+memory blocks.  The special bit patterns are:
 
 #define CLEANBYTE     0xCB   /* clean (newly allocated) memory */
 #define DEADBYTE      0xDB   /* dead (newly freed) memory */
@@ -96,73 +96,70 @@ dynamically allocated memory blocks.  The special bit patterns are:
 Strings of these bytes are unlikely to be valid addresses, floats, or 7-bit
 ASCII strings.
 
-Let S = sizeof(size_t). 2*S bytes are added at each end of each block of N
+Let S = sizeof(size_t). 2*S bytes are added at each end of each block of N bytes
-bytes requested.  The memory layout is like so, where p represents the
+requested.  The memory layout is like so, where p represents the address
-address returned by a malloc-like or realloc-like function (p[i:j] means
+returned by a malloc-like or realloc-like function (p[i:j] means the slice of
-the slice of bytes from *(p+i) inclusive up to *(p+j) exclusive; note that
+bytes from *(p+i) inclusive up to *(p+j) exclusive; note that the treatment of
-the treatment of negative indices differs from a Python slice):
+negative indices differs from a Python slice):
 
 p[-2*S:-S]
-    Number of bytes originally asked for.  This is a size_t, big-endian
+    Number of bytes originally asked for.  This is a size_t, big-endian (easier
-    (easier to read in a memory dump).
+    to read in a memory dump).
 p[-S:0]
     Copies of FORBIDDENBYTE.  Used to catch under- writes and reads.
 p[0:N]
     The requested memory, filled with copies of CLEANBYTE, used to catch
-    reference to uninitialized memory.
+    reference to uninitialized memory.  When a realloc-like function is called
-    When a realloc-like function is called requesting a larger memory
+    requesting a larger memory block, the new excess bytes are also filled with
-    block, the new excess bytes are also filled with CLEANBYTE.
+    CLEANBYTE.  When a free-like function is called, these are overwritten with
-    When a free-like function is called, these are overwritten with
+    DEADBYTE, to catch reference to freed memory.  When a realloc- like function
-    DEADBYTE, to catch reference to freed memory.  When a realloc-
+    is called requesting a smaller memory block, the excess old bytes are also
-    like function is called requesting a smaller memory block, the excess
+    filled with DEADBYTE.
-    old bytes are also filled with DEADBYTE.
 p[N:N+S]
     Copies of FORBIDDENBYTE.  Used to catch over- writes and reads.
 p[N+S:N+2*S]
     A serial number, incremented by 1 on each call to a malloc-like or
-    realloc-like function.
+    realloc-like function.  Big-endian size_t.  If "bad memory" is detected
-    Big-endian size_t.
+    later, the serial number gives an excellent way to set a breakpoint on the
-    If "bad memory" is detected later, the serial number gives an
+    next run, to capture the instant at which this block was passed out.  The
-    excellent way to set a breakpoint on the next run, to capture the
+    static function bumpserialno() in obmalloc.c is the only place the serial
-    instant at which this block was passed out.  The static function
+    number is incremented, and exists so you can set such a breakpoint easily.
-    bumpserialno() in obmalloc.c is the only place the serial number
-    is incremented, and exists so you can set such a breakpoint easily.
 
-A realloc-like or free-like function first checks that the FORBIDDENBYTEs
+A realloc-like or free-like function first checks that the FORBIDDENBYTEs at
-at each end are intact.  If they've been altered, diagnostic output is
+each end are intact.  If they've been altered, diagnostic output is written to
-written to stderr, and the program is aborted via Py_FatalError().  The
+stderr, and the program is aborted via Py_FatalError().  The other main failure
-other main failure mode is provoking a memory error when a program
+mode is provoking a memory error when a program reads up one of the special bit
-reads up one of the special bit patterns and tries to use it as an address.
+patterns and tries to use it as an address.  If you get in a debugger then and
-If you get in a debugger then and look at the object, you're likely
+look at the object, you're likely to see that it's entirely filled with 0xDB
-to see that it's entirely filled with 0xDB (meaning freed memory is
+(meaning freed memory is getting used) or 0xCB (meaning uninitialized memory is
-getting used) or 0xCB (meaning uninitialized memory is getting used).
+getting used).
 
 Note that PYMALLOC_DEBUG requires WITH_PYMALLOC.
 
 Special gimmicks:
 
-envar PYTHONMALLOCSTATS
+envvar PYTHONMALLOCSTATS
-    If this envar exists, a report of pymalloc summary statistics is
+    If this envvar exists, a report of pymalloc summary statistics is printed to
-    printed to stderr whenever a new arena is allocated, and also
+    stderr whenever a new arena is allocated, and also by Py_Finalize().
-    by Py_Finalize().
 
 Changed in 2.5:  The number of extra bytes allocated is 4*sizeof(size_t).
 Before it was 16 on all boxes, reflecting that Python couldn't make use of
 allocations >= 2**32 bytes even on 64-bit boxes before 2.5.
----------------------------------------------------------------------------
+
-Py_DEBUG                                                  introduced in 1.5
+
-                                                     named DEBUG before 1.5
+Py_DEBUG
+--------
 
 This is what is generally meant by "a debug build" of Python.
 
-Py_DEBUG implies LLTRACE, Py_REF_DEBUG, Py_TRACE_REFS, and
+Py_DEBUG implies LLTRACE, Py_REF_DEBUG, Py_TRACE_REFS, and PYMALLOC_DEBUG (if
-PYMALLOC_DEBUG (if WITH_PYMALLOC is enabled).  In addition, C
+WITH_PYMALLOC is enabled).  In addition, C assert()s are enabled (via the C way:
-assert()s are enabled (via the C way: by not defining NDEBUG), and
+by not defining NDEBUG), and some routines do additional sanity checks inside
-some routines do additional sanity checks inside "#ifdef Py_DEBUG"
+"#ifdef Py_DEBUG" blocks.
-blocks.
+
----------------------------------------------------------------------------
+
-COUNT_ALLOCS                                            introduced in 0.9.9
+COUNT_ALLOCS
-                                             partly broken in 2.2 and 2.2.1
+------------
 
 Each type object grows three new members:
 
@@ -178,84 +175,85 @@ Each type object grows three new members:
      */
     int tp_maxalloc;
 
-Allocation and deallocation code keeps these counts up to date.
+Allocation and deallocation code keeps these counts up to date.  Py_Finalize()
-Py_Finalize() displays a summary of the info returned by sys.getcounts()
+displays a summary of the info returned by sys.getcounts() (see below), along
-(see below), along with assorted other special allocation counts (like
+with assorted other special allocation counts (like the number of tuple
-the number of tuple allocations satisfied by a tuple free-list, the number
+allocations satisfied by a tuple free-list, the number of 1-character strings
-of 1-character strings allocated, etc).
+allocated, etc).
 
 Before Python 2.2, type objects were immortal, and the COUNT_ALLOCS
-implementation relies on that.  As of Python 2.2, heap-allocated type/
+implementation relies on that.  As of Python 2.2, heap-allocated type/ class
-class objects can go away.  COUNT_ALLOCS can blow up in 2.2 and 2.2.1
+objects can go away.  COUNT_ALLOCS can blow up in 2.2 and 2.2.1 because of this;
-because of this; this was fixed in 2.2.2.  Use of COUNT_ALLOCS makes
+this was fixed in 2.2.2.  Use of COUNT_ALLOCS makes all heap-allocated type
-all heap-allocated type objects immortal, except for those for which no
+objects immortal, except for those for which no object of that type is ever
-object of that type is ever allocated.
+allocated.
 
 Starting with Python 2.3, If Py_TRACE_REFS is also defined, COUNT_ALLOCS
-arranges to ensure that the type object for each allocated object
+arranges to ensure that the type object for each allocated object appears in the
-appears in the doubly-linked list of all objects maintained by
+doubly-linked list of all objects maintained by Py_TRACE_REFS.
-Py_TRACE_REFS.
 
 Special gimmicks:
 
 sys.getcounts()
-    Return a list of 4-tuples, one entry for each type object for which
+    Return a list of 4-tuples, one entry for each type object for which at least
-    at least one object of that type was allocated.  Each tuple is of
+    one object of that type was allocated.  Each tuple is of the form:
-    the form:
 
         (tp_name, tp_allocs, tp_frees, tp_maxalloc)
 
-    Each distinct type object gets a distinct entry in this list, even
+    Each distinct type object gets a distinct entry in this list, even if two or
-    if two or more type objects have the same tp_name (in which case
+    more type objects have the same tp_name (in which case there's no way to
-    there's no way to distinguish them by looking at this list).  The
+    distinguish them by looking at this list).  The list is ordered by time of
-    list is ordered by time of first object allocation:  the type object
+    first object allocation: the type object for which the first allocation of
-    for which the first allocation of an object of that type occurred
+    an object of that type occurred most recently is at the front of the list.
-    most recently is at the front of the list.
+
----------------------------------------------------------------------------
+
-LLTRACE                                          introduced well before 1.0
+LLTRACE
+-------
 
 Compile in support for Low Level TRACE-ing of the main interpreter loop.
 
-When this preprocessor symbol is defined, before PyEval_EvalFrame
+When this preprocessor symbol is defined, before PyEval_EvalFrame (eval_frame in
-(eval_frame in 2.3 and 2.2, eval_code2 before that) executes a frame's code
+2.3 and 2.2, eval_code2 before that) executes a frame's code it checks the
-it checks the frame's global namespace for a variable "__lltrace__".  If
+frame's global namespace for a variable "__lltrace__".  If such a variable is
-such a variable is found, mounds of information about what the interpreter
+found, mounds of information about what the interpreter is doing are sprayed to
-is doing are sprayed to stdout, such as every opcode and opcode argument
+stdout, such as every opcode and opcode argument and values pushed onto and
-and values pushed onto and popped off the value stack.
+popped off the value stack.
 
 Not useful very often, but very useful when needed.
 
----------------------------------------------------------------------------
+
-CALL_PROFILE                                      introduced for Python 2.3
+CALL_PROFILE
+------------
 
 Count the number of function calls executed.
 
-When this symbol is defined, the ceval mainloop and helper functions
+When this symbol is defined, the ceval mainloop and helper functions count the
-count the number of function calls made.  It keeps detailed statistics
+number of function calls made.  It keeps detailed statistics about what kind of
-about what kind of object was called and whether the call hit any of
+object was called and whether the call hit any of the special fast paths in the
-the special fast paths in the code.
+code.
 
----------------------------------------------------------------------------
-WITH_TSC                                          introduced for Python 2.4
 
-Super-lowlevel profiling of the interpreter.  When enabled, the sys
+WITH_TSC
-module grows a new function:
+--------
+
+Super-lowlevel profiling of the interpreter.  When enabled, the sys module grows
+a new function:
 
 settscdump(bool)
-    If true, tell the Python interpreter to dump VM measurements to
+    If true, tell the Python interpreter to dump VM measurements to stderr.  If
-    stderr.  If false, turn off dump.  The measurements are based on the
+    false, turn off dump.  The measurements are based on the processor's
-    processor's time-stamp counter.
+    time-stamp counter.
 
-This build option requires a small amount of platform specific code.
+This build option requires a small amount of platform specific code.  Currently
-Currently this code is present for linux/x86 and any PowerPC platform
+this code is present for linux/x86 and any PowerPC platform that uses GCC
-that uses GCC (i.e. OS X and linux/ppc).
+(i.e. OS X and linux/ppc).
 
-On the PowerPC the rate at which the time base register is incremented
+On the PowerPC the rate at which the time base register is incremented is not
-is not defined by the architecture specification, so you'll need to
+defined by the architecture specification, so you'll need to find the manual for
-find the manual for your specific processor.  For the 750CX, 750CXe
+your specific processor.  For the 750CX, 750CXe and 750FX (all sold as the G3)
-and 750FX (all sold as the G3) we find:
+we find:
 
-    The time base counter is clocked at a frequency that is
+    The time base counter is clocked at a frequency that is one-fourth that of
-    one-fourth that of the bus clock.
+    the bus clock.
 
 This build is enabled by the --with-tsc flag to configure.