Merged revisions 59259-59274 via svnmerge from

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

........
  r59260 | lars.gustaebel | 2007-12-01 22:02:12 +0100 (Sat, 01 Dec 2007) | 5 lines

  Issue #1531: Read fileobj from the current offset, do not seek to
  the start.

  (will backport to 2.5)
........
  r59262 | georg.brandl | 2007-12-01 23:24:47 +0100 (Sat, 01 Dec 2007) | 4 lines

  Document PyEval_* functions from ceval.c.

  Credits to Michael Sloan from GHOP.
........
  r59263 | georg.brandl | 2007-12-01 23:27:56 +0100 (Sat, 01 Dec 2007) | 2 lines

  Add a few refcount data entries.
........
  r59264 | georg.brandl | 2007-12-01 23:38:48 +0100 (Sat, 01 Dec 2007) | 4 lines

  Add test suite for cmd module.

  Written by Michael Schneider for GHOP.
........
  r59265 | georg.brandl | 2007-12-01 23:42:46 +0100 (Sat, 01 Dec 2007) | 3 lines

  Add examples to the ElementTree documentation.
  Written by h4wk.cz for GHOP.
........
  r59266 | georg.brandl | 2007-12-02 00:12:45 +0100 (Sun, 02 Dec 2007) | 3 lines

  Add "Using Python on Windows" document, by Robert Lehmann.
  Written for GHOP.
........
  r59271 | georg.brandl | 2007-12-02 15:34:34 +0100 (Sun, 02 Dec 2007) | 3 lines

  Add example to mmap docs.
  Written for GHOP by Rafal Rawicki.
........
  r59272 | georg.brandl | 2007-12-02 15:37:29 +0100 (Sun, 02 Dec 2007) | 2 lines

  Convert bdb.rst line endings to Unix style.
........
  r59274 | georg.brandl | 2007-12-02 15:58:50 +0100 (Sun, 02 Dec 2007) | 4 lines

  Add more entries to the glossary.

  Written by Jeff Wheeler for GHOP.
........

Doc/ACKS.txt

@@ -163,6 +163,7 @@ docs@python.org), and we'll be glad to correct the problem.
 * Justin Sheehy
 * Michael Simcich
 * Ionel Simionescu
+* Michael Sloan
 * Gregory P. Smith
 * Roy Smith
 * Clay Spence
@@ -185,6 +186,7 @@ docs@python.org), and we'll be glad to correct the problem.
 * Glyn Webster
 * Bob Weiner
 * Eddy Welbourne
+* Jeff Wheeler
 * Mats Wichmann
 * Gerry Wiener
 * Timothy Wild

Doc/Makefile

@@ -57,6 +57,10 @@ htmlhelp: build
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      "build/htmlhelp/pydoc.hhp project file."
 
+latex: BUILDER = latex
+latex: build
+	@echo "Build finished; the LaTeX files are in build/latex."
+
 clean:
 	-rm -rf build/*
 	-rm -rf tools/sphinx

Doc/README.txt

@@ -53,6 +53,9 @@ Available make targets are:
    To create the CHM file, you need to run the Microsoft HTML Help Workshop
    over the generated project (.hhp) file.
 
+ * "latex", which builds LaTeX source files that can be run with "pdflatex"
+   to produce PDF documents.
+
 A "make update" updates the Subversion checkouts in `tools/`.
 
 

Doc/c-api/init.rst

@@ -615,6 +615,14 @@ supports the creation of additional interpreters (using
    deadlock ensues.  (This function is available even when thread support is
    disabled at compile time.)
 
+
+.. cfunction:: void PyEval_ReInitThreads()
+
+   This function is called from :cfunc:`PyOS_AfterFork` to ensure that newly
+   created child processes don't hold locks referring to threads which
+   are not running in the child process.
+
+
 The following macros are normally used without a trailing semicolon; look for
 example usage in the Python source distribution.
 
@@ -876,6 +884,46 @@ in previous versions.
    :cfunc:`PyEval_SetProfile`, except the tracing function does receive line-number
    events.
 
+.. cfunction:: PyObject* PyEval_GetCallStats(PyObject *self)
+
+   Return a tuple of function call counts.  There are constants defined for the
+   positions within the tuple:
+   
+   +-------------------------------+-------+
+   | Name                          | Value |
+   +===============================+=======+
+   | :const:`PCALL_ALL`            | 0     |
+   +-------------------------------+-------+
+   | :const:`PCALL_FUNCTION`       | 1     |
+   +-------------------------------+-------+
+   | :const:`PCALL_FAST_FUNCTION`  | 2     |
+   +-------------------------------+-------+
+   | :const:`PCALL_FASTER_FUNCTION`| 3     |
+   +-------------------------------+-------+
+   | :const:`PCALL_METHOD`         | 4     |
+   +-------------------------------+-------+
+   | :const:`PCALL_BOUND_METHOD`   | 5     |
+   +-------------------------------+-------+
+   | :const:`PCALL_CFUNCTION`      | 6     |
+   +-------------------------------+-------+
+   | :const:`PCALL_TYPE`           | 7     |
+   +-------------------------------+-------+
+   | :const:`PCALL_GENERATOR`      | 8     |
+   +-------------------------------+-------+
+   | :const:`PCALL_OTHER`          | 9     |
+   +-------------------------------+-------+
+   | :const:`PCALL_POP`            | 10    |
+   +-------------------------------+-------+
+   
+   :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created.
+   :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used.
+
+   If there is a method call where the call can be optimized by changing
+   the argument tuple and calling the function directly, it gets recorded
+   twice.
+
+   This function is only present if Python is compiled with :const:`CALL_PROFILE`
+   defined.
 
 .. _advanced-debugging:
 

Doc/c-api/utilities.rst

@@ -989,3 +989,52 @@ The following functions provide locale-independent string to number conversions.
 
    See the Unix man page :manpage:`atof(2)` for details.
 
+
+.. _reflection:
+
+Reflection
+==========
+
+.. cfunction:: PyObject* PyEval_GetBuiltins()
+
+   Return a dictionary of the builtins in the current execution frame,
+   or the interpreter of the thread state if no frame is currently executing.
+
+
+.. cfunction:: PyObject* PyEval_GetLocals()
+
+   Return a dictionary of the local variables in the current execution frame,
+   or *NULL* if no frame is currently executing.
+   
+
+.. cfunction:: PyObject* PyEval_GetGlobals()
+
+   Return a dictionary of the global variables in the current execution frame,
+   or *NULL* if no frame is currently executing.
+
+
+.. cfunction:: PyFrameObject* PyEval_GetFrame()
+
+   Return the current thread state's frame, which is *NULL* if no frame is
+   currently executing.
+
+
+.. cfunction:: int PyEval_GetRestricted()
+
+   If there is a current frame and it is executing in restricted mode, return true,
+   otherwise false.
+
+
+.. cfunction:: const char* PyEval_GetFuncName(PyObject *func)
+
+   Return the name of *func* if it is a function, class or instance object, else the
+   name of *func*\s type.
+
+
+.. cfunction:: const char* PyEval_GetFuncDesc(PyObject *func)
+
+   Return a description string, depending on the type of *func*.
+   Return values include "()" for functions and methods, " constructor",
+   " instance", and " object".  Concatenated with the result of
+   :cfunc:`PyEval_GetFuncName`, the result will be a description of
+   *func*.

Doc/c-api/veryhigh.rst

@@ -229,6 +229,43 @@ the same library that the Python runtime is using.
    be parsed or compiled.
 
 
+.. cfunction:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)
+
+   This is a simplified interface to :cfunc:`PyEval_EvalCodeEx`, with just
+   the code object, and the dictionaries of global and local variables.
+   The other arguments are set to *NULL*.
+
+
+.. cfunction:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)
+
+   Evaluate a precompiled code object, given a particular environment for its
+   evaluation.  This environment consists of dictionaries of global and local
+   variables, arrays of arguments, keywords and defaults, and a closure tuple of
+   cells.
+
+
+.. cfunction:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
+
+   Evaluate an execution frame.  This is a simplified interface to
+   PyEval_EvalFrameEx, for backward compatibility.
+
+
+.. cfunction:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
+
+   This is the main, unvarnished function of Python interpretation.  It is
+   literally 2000 lines long.  The code object associated with the execution
+   frame *f* is executed, interpreting bytecode and executing calls as needed.
+   The additional *throwflag* parameter can mostly be ignored - if true, then
+   it causes an exception to immediately be thrown; this is used for the
+   :meth:`throw` methods of generator objects.
+
+
+.. cfunction:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
+
+   This function changes the flags of the current evaluation frame, and returns
+   true on success, false on failure.
+
+
 .. cvar:: int Py_eval_input
 
    .. index:: single: Py_CompileString()

Doc/data/refcounts.dat

@@ -309,6 +309,11 @@ PyEval_AcquireLock:void:::
 PyEval_AcquireThread:void:::
 PyEval_AcquireThread:PyThreadState*:tstate::
 
+PyEval_GetBuiltins:PyObject*::0:
+PyEval_GetLocals:PyObject*::0:
+PyEval_GetGlobals:PyObject*::0:
+PyEval_GetFrame:PyObject*::0:
+
 PyEval_InitThreads:void:::
 
 PyEval_ReleaseLock:void:::

Doc/distutils/extending.rst

-.. _extending:
+.. _extending-distutils:
 
 *******************
 Extending Distutils

Doc/extending/extending.rst

@@ -466,10 +466,10 @@ Later, when it is time to call the function, you call the C function
 :cfunc:`PyEval_CallObject`.  This function has two arguments, both pointers to
 arbitrary Python objects: the Python function, and the argument list.  The
 argument list must always be a tuple object, whose length is the number of
-arguments.  To call the Python function with no arguments, pass an empty tuple;
-to call it with one argument, pass a singleton tuple. :cfunc:`Py_BuildValue`
-returns a tuple when its format string consists of zero or more format codes
-between parentheses.  For example::
+arguments.  To call the Python function with no arguments, pass in NULL, or 
+an empty tuple; to call it with one argument, pass a singleton tuple.
+:cfunc:`Py_BuildValue` returns a tuple when its format string consists of zero
+or more format codes between parentheses.  For example::
 
    int arg;
    PyObject *arglist;
@@ -527,9 +527,22 @@ event code, you might use the following code::
    Py_DECREF(result);
 
 Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before
-the error check!  Also note that strictly spoken this code is not complete:
+the error check!  Also note that strictly speaking this code is not complete:
 :cfunc:`Py_BuildValue` may run out of memory, and this should be checked.
 
+You may also call a function with keyword arguments by using 
+:cfunc:`PyEval_CallObjectWithKeywords`.  As in the above example, we use
+:cfunc:`Py_BuildValue` to construct the dictionary. ::
+
+   PyObject *dict;
+   ...
+   dict = Py_BuildValue("{s:i}", "name", val);
+   result = PyEval_CallObjectWithKeywords(my_callback, NULL, dict);
+   Py_DECREF(dict);
+   if (result == NULL)
+       return NULL; /* Pass error back */
+   /* Here maybe use the result */
+   Py_DECREF(result);
 
 .. _parsetuple:
 

Doc/glossary.rst

@@ -15,6 +15,17 @@ Glossary
    ``...``
       The typical Python prompt of the interactive shell when entering code for
       an indented code block.
+
+   argument
+      A value passed to a function or method, assigned to a name local to
+      the body.  A function or method may have both positional arguments and
+      keyword arguments in its definition.  Positional and keyword arguments
+      may be variable-length: ``*`` accepts or passes (if in the function
+      definition or call) several positional arguments in a list, while ``**``
+      does the same for keyword arguments in a dictionary.
+
+      Any expression may be used within the argument list, and the evaluated
+      value is passed to the local variable.
     
    BDFL
       Benevolent Dictator For Life, a.k.a. `Guido van Rossum
@@ -44,6 +55,22 @@ Glossary
       advanced mathematical feature.  If you're not aware of a need for them,
       it's almost certain you can safely ignore them.
     
+   decorator
+      A function returning another function, usually applied as a function
+      transformation using the ``@wrapper`` syntax.  Common examples for
+      decorators are :func:`classmethod` and :func:`staticmethod`.
+
+      The decorator syntax is merely syntactic sugar, the following two
+      function definitions are semantically equivalent::
+
+         def f(...):
+             ...
+         f = staticmethod(f)
+
+         @staticmethod
+         def f(...):
+             ...
+
    descriptor
       An object that defines the methods :meth:`__get__`, :meth:`__set__`, or
       :meth:`__delete__`.  When a class attribute is a descriptor, its special
@@ -81,10 +108,24 @@ Glossary
       statements.  The technique contrasts with the :term:`LBYL` style that is
       common in many other languages such as C.
 
+   expression
+      A piece of syntax which can be evaluated to some value.  In other words,
+      an expression is an accumulation of expression elements like literals, names,
+      attribute access, operators or function calls that all return a value.
+      In contrast to other languages, not all language constructs are expressions,
+      but there are also :term:`statement`\s that cannot be used as expressions,
+      such as :keyword:`print` or :keyword:`if`.  Assignments are also not
+      expressions.
+
    extension module
       A module written in C, using Python's C API to interact with the core and
       with user code.
-    
+
+   function
+      A series of statements which returns some value to a caller. It can also
+      be passed zero or more arguments which may be used in the execution of
+      the body. See also :term:`argument` and :term:`method`.
+
    __future__
       A pseudo module which programmers can use to enable new language features
       which are not compatible with the current interpreter.  For example, the
@@ -228,6 +269,17 @@ Glossary
     
       More information can be found in :ref:`typeiter`.
 
+   keyword argument
+      Arguments which are preceded with a ``variable_name=`` in the call.
+      The variable name designates the local name in the function to which the
+      value is assigned.  ``**`` is used to accept or pass a dictionary of
+      keyword arguments.  See :term:`argument`.
+
+   lambda
+      An anonymous inline function consisting of a single :term:`expression`
+      which is evaluated when the function is called.  The syntax to create
+      a lambda function is ``lambda [arguments]: expression``
+
    LBYL
       Look before you leap.  This coding style explicitly tests for
       pre-conditions before making calls or lookups.  This style contrasts with
@@ -258,6 +310,12 @@ Glossary
       singletons, and many other tasks.
 
       More information can be found in :ref:`metaclasses`.
+
+   method
+      A function that is defined inside a class body.  If called as an attribute
+      of an instance of that class, the method will get the instance object as
+      its first :term:`argument` (which is usually called ``self``).
+      See :term:`function` and :term:`nested scope`.
     
    mutable
       Mutable objects can change their value but keep their :func:`id`.  See
@@ -291,10 +349,32 @@ Glossary
 
       More information can be found in :ref:`newstyle`.
     
+   positional argument
+      The arguments assigned to local names inside a function or method,
+      determined by the order in which they were given in the call.  ``*`` is
+      used to either accept multiple positional arguments (when in the
+      definition), or pass several arguments as a list to a function.  See
+      :term:`argument`.
+
    Python 3000
       Nickname for the next major Python version, 3.0 (coined long ago when the
       release of version 3 was something in the distant future.)
 
+   Pythonic
+      An idea or piece of code which closely follows the most common idioms of
+      the Python language, rather than implementing code using concepts common
+      in other languages.  For example, a common idiom in Python is the :keyword:`for`
+      loop structure; other languages don't have this easy keyword, so people
+      use a numerical counter instead::
+     
+          for i in range(len(food)):
+              print food[i]
+
+      As opposed to the cleaner, Pythonic method::
+
+         for piece in food:
+             print piece
+
    reference count
       The number of places where a certain object is referenced to.  When the
       reference count drops to zero, an object is deallocated.  While reference
@@ -317,6 +397,18 @@ Glossary
       mapping rather than a sequence because the lookups use arbitrary
       :term:`immutable` keys rather than integers.
 
+   slice
+      A list containing a portion of an indexed list-like object.  A slice is
+      created using the subscript notation, ``[]`` with colons between numbers
+      when several are given, such as in ``variable_name[1:3:5]``.  The bracket
+      (subscript) notation uses :class:`slice` objects internally (or in older
+      versions, :meth:`__getslice__` and :meth:`__setslice__`).
+
+   statement
+      A statement is part of a suite (a "block" of code).  A statement is either
+      an :term:`expression` or a one of several constructs with a keyword, such
+      as :keyword:`if`, :keyword:`while` or :keyword:`print`.
+
    type
       The type of a Python object determines what kind of object it is; every
       object has a type.  An object's type is accessible as its

Doc/library/atexit.rst

@@ -88,7 +88,7 @@ passed along to the registered function when it is called::
    # or:
    atexit.register(goodbye, adjective='nice', name='Donny')
 
-Usage as a decorator::
+Usage as a :term:`decorator`::
 
    import atexit
 

Doc/library/bdb.rst

-:mod:`bdb` --- Debugger framework
-=================================
-
-.. module:: bdb
-   :synopsis: Debugger framework.
-
-The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
-or managing execution via the debugger.
-
-The following exception is defined:
-
-.. exception:: BdbQuit
-
-   Exception raised by the :class:`Bdb` class for quitting the debugger.
-
-
-The :mod:`bdb` module also defines two classes:
-
-.. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]])
-
-   This class implements temporary breakpoints, ignore counts, disabling and
-   (re-)enabling, and conditionals.
-
-   Breakpoints are indexed by number through a list called :attr:`bpbynumber`
-   and by ``(file, line)`` pairs through :attr:`bplist`.  The former points to a
-   single instance of class :class:`Breakpoint`.  The latter points to a list of
-   such instances since there may be more than one breakpoint per line.
-
-   When creating a breakpoint, its associated filename should be in canonical
-   form.  If a *funcname* is defined, a breakpoint hit will be counted when the
-   first line of that function is executed.  A conditional breakpoint always
-   counts a hit.
-
-:class:`Breakpoint` instances have the following methods:
-
-.. method:: Breakpoint.deleteMe()
-
-   Delete the breakpoint from the list associated to a file/line.  If it is the
-   last breakpoint in that position, it also deletes the entry for the
-   file/line.
-
-.. method:: Breakpoint.enable()
-
-   Mark the breakpoint as enabled.
-
-.. method:: Breakpoint.disable()
-
-   Mark the breakpoint as disabled.
-
-.. method:: Breakpoint.bpprint([out])
-
-   Print all the information about the breakpoint:
-
-   * The breakpoint number.
-   * If it is temporary or not.
-   * Its file,line position.
-   * The condition that causes a break.
-   * If it must be ignored the next N times.
-   * The breakpoint hit count.
-
-
-.. class:: Bdb()
-
-   The :class:`Bdb` acts as a generic Python debugger base class.
-
-   This class takes care of the details of the trace facility; a derived class
-   should implement user interaction.  The standard debugger class
-   (:class:`pdb.Pdb`) is an example.
-
-
-The following methods of :class:`Bdb` normally don't need to be overridden.
-
-.. method:: Bdb.canonic(filename)
-
-   Auxiliary method for getting a filename in a canonical form, that is, as a
-   case-normalized (on case-insensitive filesystems) absolute path, stripped
-   of surrounding angle brackets.
-
-.. method:: Bdb.reset()
-
-   Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
-   :attr:`quitting` attributes with values ready to start debugging.
-
-
-.. method:: Bdb.trace_dispatch(frame, event, arg)
-
-   This function is installed as the trace function of debugged frames.  Its
-   return value is the new trace function (in most cases, that is, itself).
-
-   The default implementation decides how to dispatch a frame, depending on the
-   type of event (passed as a string) that is about to be executed.  *event* can
-   be one of the following:
-
-   * ``"line"``: A new line of code is going to be executed.
-   * ``"call"``: A function is about to be called, or another code block
-     entered.
-   * ``"return"``: A function or other code block is about to return.
-   * ``"exception"``: An exception has occurred.
-   * ``"c_call"``: A C function is about to be called.
-   * ``"c_return"``: A C function has returned.
-   * ``"c_exception"``: A C function has thrown an exception.
-
-   For the Python events, specialized functions (see below) are called.  For the
-   C events, no action is taken.
-
-   The *arg* parameter depends on the previous event.
-
-   For more information on trace functions, see :ref:`debugger-hooks`.  For more
-   information on code and frame objects, refer to :ref:`types`.
-
-.. method:: Bdb.dispatch_line(frame)
-
-   If the debugger should stop on the current line, invoke the :meth:`user_line`
-   method (which should be overridden in subclasses).  Raise a :exc:`BdbQuit`
-   exception if the :attr:`Bdb.quitting` flag is set (which can be set from
-   :meth:`user_line`).  Return a reference to the :meth:`trace_dispatch` method
-   for further tracing in that scope.
-
-.. method:: Bdb.dispatch_call(frame, arg)
-
-   If the debugger should stop on this function call, invoke the
-   :meth:`user_call` method (which should be overridden in subclasses).  Raise a
-   :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
-   be set from :meth:`user_call`).  Return a reference to the
-   :meth:`trace_dispatch` method for further tracing in that scope.
-
-.. method:: Bdb.dispatch_return(frame, arg)
-
-   If the debugger should stop on this function return, invoke the
-   :meth:`user_return` method (which should be overridden in subclasses).  Raise
-   a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
-   be set from :meth:`user_return`).  Return a reference to the
-   :meth:`trace_dispatch` method for further tracing in that scope.
-
-.. method:: Bdb.dispatch_exception(frame, arg)
-
-   If the debugger should stop at this exception, invokes the
-   :meth:`user_exception` method (which should be overridden in subclasses).
-   Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
-   (which can be set from :meth:`user_exception`).  Return a reference to the
-   :meth:`trace_dispatch` method for further tracing in that scope.
-
-Normally derived classes don't override the following methods, but they may if
-they want to redefine the definition of stopping and breakpoints.
-
-.. method:: Bdb.stop_here(frame)
-
-   This method checks if the *frame* is somewhere below :attr:`botframe` in the
-   call stack.  :attr:`botframe` is the frame in which debugging started.
-
-.. method:: Bdb.break_here(frame)
-
-   This method checks if there is a breakpoint in the filename and line
-   belonging to *frame* or, at least, in the current function.  If the
-   breakpoint is a temporary one, this method deletes it.
-
-.. method:: Bdb.break_anywhere(frame)
-
-   This method checks if there is a breakpoint in the filename of the current
-   frame.
-
-Derived classes should override these methods to gain control over debugger
-operation.
-
-.. method:: Bdb.user_call(frame, argument_list)
-
-   This method is called from :meth:`dispatch_call` when there is the
-   possibility that a break might be necessary anywhere inside the called
-   function.
-
-.. method:: Bdb.user_line(frame)
-
-   This method is called from :meth:`dispatch_line` when either
-   :meth:`stop_here` or :meth:`break_here` yields True.
-
-.. method:: Bdb.user_return(frame, return_value)
-
-   This method is called from :meth:`dispatch_return` when :meth:`stop_here`
-   yields True.
-
-.. method:: Bdb.user_exception(frame, exc_info)
-
-   This method is called from :meth:`dispatch_exception` when :meth:`stop_here`
-   yields True.
-
-.. method:: Bdb.do_clear(arg)
-
-   Handle how a breakpoint must be removed when it is a temporary one.
-
-   This method must be implemented by derived classes.
-
-
-Derived classes and clients can call the following methods to affect the 
-stepping state.
-
-.. method:: Bdb.set_step()
-
-   Stop after one line of code.
-
-.. method:: Bdb.set_next(frame)
-
-   Stop on the next line in or below the given frame.
-
-.. method:: Bdb.set_return(frame)
-
-   Stop when returning from the given frame.
-
-.. method:: Bdb.set_trace([frame])
-
-   Start debugging from *frame*.  If *frame* is not specified, debugging starts
-   from caller's frame.
-
-.. method:: Bdb.set_continue()
-
-   Stop only at breakpoints or when finished.  If there are no breakpoints, set
-   the system trace function to None.
-
-.. method:: Bdb.set_quit()
-
-   Set the :attr:`quitting` attribute to True.  This raises :exc:`BdbQuit` in
-   the next call to one of the :meth:`dispatch_\*` methods.
-
-
-Derived classes and clients can call the following methods to manipulate
-breakpoints.  These methods return a string containing an error message if
-something went wrong, or ``None`` if all is well.
-
-.. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]])
-
-   Set a new breakpoint.  If the *lineno* line doesn't exist for the *filename*
-   passed as argument, return an error message.  The *filename* should be in
-   canonical form, as described in the :meth:`canonic` method.
-
-.. method:: Bdb.clear_break(filename, lineno)
-
-   Delete the breakpoints in *filename* and *lineno*.  If none were set, an
-   error message is returned.
-
-.. method:: Bdb.clear_bpbynumber(arg)
-
-   Delete the breakpoint which has the index *arg* in the
-   :attr:`Breakpoint.bpbynumber`.  If `arg` is not numeric or out of range,
-   return an error message.
-
-.. method:: Bdb.clear_all_file_breaks(filename)
-
-   Delete all breakpoints in *filename*.  If none were set, an error message is
-   returned.
-
-.. method:: Bdb.clear_all_breaks()
-
-   Delete all existing breakpoints.
-
-.. method:: Bdb.get_break(filename, lineno)
-
-   Check if there is a breakpoint for *lineno* of *filename*.
-
-.. method:: Bdb.get_breaks(filename, lineno)
-
-   Return all breakpoints for *lineno* in *filename*, or an empty list if none
-   are set.
-
-.. method:: Bdb.get_file_breaks(filename)
-
-   Return all breakpoints in *filename*, or an empty list if none are set.
-
-.. method:: Bdb.get_all_breaks()
-
-   Return all breakpoints that are set.
-
-
-Derived classes and clients can call the following methods to get a data
-structure representing a stack trace.
-
-.. method:: Bdb.get_stack(f, t)
-
-   Get a list of records for a frame and all higher (calling) and lower frames,
-   and the size of the higher part.
-
-.. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': '])
-
-   Return a string with information about a stack entry, identified by a
-   ``(frame, lineno)`` tuple:
-
-   * The canonical form of the filename which contains the frame.
-   * The function name, or ``"<lambda>"``.
-   * The input arguments.
-   * The return value.
-   * The line of code (if it exists).
-
-
-The following two methods can be called by clients to use a debugger to debug a
-statement, given as a string.
-
-.. method:: Bdb.run(cmd, [globals, [locals]])
-
-   Debug a statement executed via the :func:`exec` function.  *globals*
-   defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
-
-.. method:: Bdb.runeval(expr, [globals, [locals]])
-
-   Debug an expression executed via the :func:`eval` function.  *globals* and
-   *locals* have the same meaning as in :meth:`run`.
-
-.. method:: Bdb.runctx(cmd, globals, locals)
-
-   For backwards compatibility.  Calls the :meth:`run` method.
-
-.. method:: Bdb.runcall(func, *args, **kwds)
-
-   Debug a single function call, and return its result.
-
-
-Finally, the module defines the following functions:
-
-.. function:: checkfuncname(b, frame)
-
-   Check whether we should break here, depending on the way the breakpoint *b*
-   was set.
-   
-   If it was set via line number, it checks if ``b.line`` is the same as the one
-   in the frame also passed as argument.  If the breakpoint was set via function
-   name, we have to check we are in the right frame (the right function) and if
-   we are in its first executable line.
-
-.. function:: effective(file, line, frame)
-
-   Determine if there is an effective (active) breakpoint at this line of code.
-   Return breakpoint number or 0 if none.
-	
-   Called only if we know there is a breakpoint at this location.  Returns the
-   breakpoint that was triggered and a flag that indicates if it is ok to delete
-   a temporary breakpoint.
-
-.. function:: set_trace()
-
-   Starts debugging with a :class:`Bdb` instance from caller's frame.
+:mod:`bdb` --- Debugger framework
+=================================
+
+.. module:: bdb
+   :synopsis: Debugger framework.
+
+The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
+or managing execution via the debugger.
+
+The following exception is defined:
+
+.. exception:: BdbQuit
+
+   Exception raised by the :class:`Bdb` class for quitting the debugger.
+
+
+The :mod:`bdb` module also defines two classes:
+
+.. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]])
+
+   This class implements temporary breakpoints, ignore counts, disabling and
+   (re-)enabling, and conditionals.
+
+   Breakpoints are indexed by number through a list called :attr:`bpbynumber`
+   and by ``(file, line)`` pairs through :attr:`bplist`.  The former points to a
+   single instance of class :class:`Breakpoint`.  The latter points to a list of
+   such instances since there may be more than one breakpoint per line.
+
+   When creating a breakpoint, its associated filename should be in canonical
+   form.  If a *funcname* is defined, a breakpoint hit will be counted when the
+   first line of that function is executed.  A conditional breakpoint always
+   counts a hit.
+
+:class:`Breakpoint` instances have the following methods:
+
+.. method:: Breakpoint.deleteMe()
+
+   Delete the breakpoint from the list associated to a file/line.  If it is the
+   last breakpoint in that position, it also deletes the entry for the
+   file/line.
+
+.. method:: Breakpoint.enable()
+
+   Mark the breakpoint as enabled.
+
+.. method:: Breakpoint.disable()
+
+   Mark the breakpoint as disabled.
+
+.. method:: Breakpoint.bpprint([out])
+
+   Print all the information about the breakpoint:
+
+   * The breakpoint number.
+   * If it is temporary or not.
+   * Its file,line position.
+   * The condition that causes a break.
+   * If it must be ignored the next N times.
+   * The breakpoint hit count.
+
+
+.. class:: Bdb()
+
+   The :class:`Bdb` acts as a generic Python debugger base class.
+
+   This class takes care of the details of the trace facility; a derived class
+   should implement user interaction.  The standard debugger class
+   (:class:`pdb.Pdb`) is an example.
+
+
+The following methods of :class:`Bdb` normally don't need to be overridden.
+
+.. method:: Bdb.canonic(filename)
+
+   Auxiliary method for getting a filename in a canonical form, that is, as a
+   case-normalized (on case-insensitive filesystems) absolute path, stripped
+   of surrounding angle brackets.
+
+.. method:: Bdb.reset()
+
+   Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
+   :attr:`quitting` attributes with values ready to start debugging.
+
+
+.. method:: Bdb.trace_dispatch(frame, event, arg)
+
+   This function is installed as the trace function of debugged frames.  Its
+   return value is the new trace function (in most cases, that is, itself).
+
+   The default implementation decides how to dispatch a frame, depending on the
+   type of event (passed as a string) that is about to be executed.  *event* can
+   be one of the following:
+
+   * ``"line"``: A new line of code is going to be executed.
+   * ``"call"``: A function is about to be called, or another code block
+     entered.
+   * ``"return"``: A function or other code block is about to return.
+   * ``"exception"``: An exception has occurred.
+   * ``"c_call"``: A C function is about to be called.
+   * ``"c_return"``: A C function has returned.
+   * ``"c_exception"``: A C function has thrown an exception.
+
+   For the Python events, specialized functions (see below) are called.  For the
+   C events, no action is taken.
+
+   The *arg* parameter depends on the previous event.
+
+   For more information on trace functions, see :ref:`debugger-hooks`.  For more
+   information on code and frame objects, refer to :ref:`types`.
+
+.. method:: Bdb.dispatch_line(frame)
+
+   If the debugger should stop on the current line, invoke the :meth:`user_line`
+   method (which should be overridden in subclasses).  Raise a :exc:`BdbQuit`
+   exception if the :attr:`Bdb.quitting` flag is set (which can be set from
+   :meth:`user_line`).  Return a reference to the :meth:`trace_dispatch` method
+   for further tracing in that scope.
+
+.. method:: Bdb.dispatch_call(frame, arg)
+
+   If the debugger should stop on this function call, invoke the
+   :meth:`user_call` method (which should be overridden in subclasses).  Raise a
+   :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
+   be set from :meth:`user_call`).  Return a reference to the
+   :meth:`trace_dispatch` method for further tracing in that scope.
+
+.. method:: Bdb.dispatch_return(frame, arg)
+
+   If the debugger should stop on this function return, invoke the
+   :meth:`user_return` method (which should be overridden in subclasses).  Raise
+   a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
+   be set from :meth:`user_return`).  Return a reference to the
+   :meth:`trace_dispatch` method for further tracing in that scope.
+
+.. method:: Bdb.dispatch_exception(frame, arg)
+
+   If the debugger should stop at this exception, invokes the
+   :meth:`user_exception` method (which should be overridden in subclasses).
+   Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
+   (which can be set from :meth:`user_exception`).  Return a reference to the
+   :meth:`trace_dispatch` method for further tracing in that scope.
+
+Normally derived classes don't override the following methods, but they may if
+they want to redefine the definition of stopping and breakpoints.
+
+.. method:: Bdb.stop_here(frame)
+
+   This method checks if the *frame* is somewhere below :attr:`botframe` in the
+   call stack.  :attr:`botframe` is the frame in which debugging started.
+
+.. method:: Bdb.break_here(frame)
+
+   This method checks if there is a breakpoint in the filename and line
+   belonging to *frame* or, at least, in the current function.  If the
+   breakpoint is a temporary one, this method deletes it.
+
+.. method:: Bdb.break_anywhere(frame)
+
+   This method checks if there is a breakpoint in the filename of the current
+   frame.
+
+Derived classes should override these methods to gain control over debugger
+operation.
+
+.. method:: Bdb.user_call(frame, argument_list)
+
+   This method is called from :meth:`dispatch_call` when there is the
+   possibility that a break might be necessary anywhere inside the called
+   function.
+
+.. method:: Bdb.user_line(frame)
+
+   This method is called from :meth:`dispatch_line` when either
+   :meth:`stop_here` or :meth:`break_here` yields True.
+
+.. method:: Bdb.user_return(frame, return_value)
+
+   This method is called from :meth:`dispatch_return` when :meth:`stop_here`
+   yields True.
+
+.. method:: Bdb.user_exception(frame, exc_info)
+
+   This method is called from :meth:`dispatch_exception` when :meth:`stop_here`
+   yields True.
+
+.. method:: Bdb.do_clear(arg)
+
+   Handle how a breakpoint must be removed when it is a temporary one.
+
+   This method must be implemented by derived classes.
+
+
+Derived classes and clients can call the following methods to affect the 
+stepping state.
+
+.. method:: Bdb.set_step()
+
+   Stop after one line of code.
+
+.. method:: Bdb.set_next(frame)
+
+   Stop on the next line in or below the given frame.
+
+.. method:: Bdb.set_return(frame)
+
+   Stop when returning from the given frame.
+
+.. method:: Bdb.set_trace([frame])
+
+   Start debugging from *frame*.  If *frame* is not specified, debugging starts
+   from caller's frame.
+
+.. method:: Bdb.set_continue()
+
+   Stop only at breakpoints or when finished.  If there are no breakpoints, set
+   the system trace function to None.
+
+.. method:: Bdb.set_quit()
+
+   Set the :attr:`quitting` attribute to True.  This raises :exc:`BdbQuit` in
+   the next call to one of the :meth:`dispatch_\*` methods.
+
+
+Derived classes and clients can call the following methods to manipulate
+breakpoints.  These methods return a string containing an error message if
+something went wrong, or ``None`` if all is well.
+
+.. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]])
+
+   Set a new breakpoint.  If the *lineno* line doesn't exist for the *filename*
+   passed as argument, return an error message.  The *filename* should be in
+   canonical form, as described in the :meth:`canonic` method.
+
+.. method:: Bdb.clear_break(filename, lineno)
+
+   Delete the breakpoints in *filename* and *lineno*.  If none were set, an
+   error message is returned.
+
+.. method:: Bdb.clear_bpbynumber(arg)
+
+   Delete the breakpoint which has the index *arg* in the
+   :attr:`Breakpoint.bpbynumber`.  If `arg` is not numeric or out of range,
+   return an error message.
+
+.. method:: Bdb.clear_all_file_breaks(filename)
+
+   Delete all breakpoints in *filename*.  If none were set, an error message is
+   returned.
+
+.. method:: Bdb.clear_all_breaks()
+
+   Delete all existing breakpoints.
+
+.. method:: Bdb.get_break(filename, lineno)
+
+   Check if there is a breakpoint for *lineno* of *filename*.
+
+.. method:: Bdb.get_breaks(filename, lineno)
+
+   Return all breakpoints for *lineno* in *filename*, or an empty list if none
+   are set.
+
+.. method:: Bdb.get_file_breaks(filename)
+
+   Return all breakpoints in *filename*, or an empty list if none are set.
+
+.. method:: Bdb.get_all_breaks()
+
+   Return all breakpoints that are set.
+
+
+Derived classes and clients can call the following methods to get a data
+structure representing a stack trace.
+
+.. method:: Bdb.get_stack(f, t)
+
+   Get a list of records for a frame and all higher (calling) and lower frames,
+   and the size of the higher part.
+
+.. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': '])
+
+   Return a string with information about a stack entry, identified by a
+   ``(frame, lineno)`` tuple:
+
+   * The canonical form of the filename which contains the frame.
+   * The function name, or ``"<lambda>"``.
+   * The input arguments.
+   * The return value.
+   * The line of code (if it exists).
+
+
+The following two methods can be called by clients to use a debugger to debug a
+:term:`statement`, given as a string.
+
+.. method:: Bdb.run(cmd, [globals, [locals]])
+
+   Debug a statement executed via the :keyword:`exec` statement.  *globals*
+   defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
+
+.. method:: Bdb.runeval(expr, [globals, [locals]])
+
+   Debug an expression executed via the :func:`eval` function.  *globals* and
+   *locals* have the same meaning as in :meth:`run`.
+
+.. method:: Bdb.runctx(cmd, globals, locals)
+
+   For backwards compatibility.  Calls the :meth:`run` method.
+
+.. method:: Bdb.runcall(func, *args, **kwds)
+
+   Debug a single function call, and return its result.
+
+
+Finally, the module defines the following functions:
+
+.. function:: checkfuncname(b, frame)
+
+   Check whether we should break here, depending on the way the breakpoint *b*
+   was set.
+   
+   If it was set via line number, it checks if ``b.line`` is the same as the one
+   in the frame also passed as argument.  If the breakpoint was set via function
+   name, we have to check we are in the right frame (the right function) and if
+   we are in its first executable line.
+
+.. function:: effective(file, line, frame)
+
+   Determine if there is an effective (active) breakpoint at this line of code.
+   Return breakpoint number or 0 if none.
+	
+   Called only if we know there is a breakpoint at this location.  Returns the
+   breakpoint that was triggered and a flag that indicates if it is ok to delete
+   a temporary breakpoint.
+
+.. function:: set_trace()
+
+   Starts debugging with a :class:`Bdb` instance from caller's frame.

Doc/library/codeop.rst

@@ -43,8 +43,8 @@ To do just the former:
    :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.
 
    The *symbol* argument determines whether *source* is compiled as a statement
-   (``'single'``, the default) or as an expression (``'eval'``).  Any other value
-   will cause :exc:`ValueError` to  be raised.
+   (``'single'``, the default) or as an :term:`expression` (``'eval'``).  Any
+   other value will cause :exc:`ValueError` to  be raised.
 
    .. warning::
       

Doc/library/contextlib.rst

@@ -15,9 +15,9 @@ Functions provided:
 
 .. function:: contextmanager(func)
 
-   This function is a decorator that can be used to define a factory function for
-   :keyword:`with` statement context managers, without needing to create a class or
-   separate :meth:`__enter__` and :meth:`__exit__` methods.
+   This function is a :term:`decorator` that can be used to define a factory
+   function for :keyword:`with` statement context managers, without needing to
+   create a class or separate :meth:`__enter__` and :meth:`__exit__` methods.
 
    A simple example (this is not recommended as a real way of generating HTML!)::
 

Doc/library/doctest.rst

@@ -1070,7 +1070,8 @@ capabilities, then you should use the advanced API.
 The advanced API revolves around two container classes, which are used to store
 the interactive examples extracted from doctest cases:
 
-* :class:`Example`: A single python statement, paired with its expected output.
+* :class:`Example`: A single python :term:`statement`, paired with its expected
+  output.
 
 * :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
   from a single docstring or text file.

Doc/library/functions.rst

@@ -177,8 +177,8 @@ available.  They are listed here in alphabetical order.
           @classmethod
           def f(cls, arg1, arg2, ...): ...
 
-   The ``@classmethod`` form is a function decorator -- see the description of
-   function definitions in :ref:`function` for details.
+   The ``@classmethod`` form is a function :term:`decorator` -- see the description
+   of function definitions in :ref:`function` for details.
 
    It can be called either on the class (such as ``C.f()``) or on an instance (such
    as ``C().f()``).  The instance is ignored except for its class. If a class
@@ -814,7 +814,7 @@ available.  They are listed here in alphabetical order.
 
    If given, *doc* will be the docstring of the property attribute. Otherwise, the
    property will copy *fget*'s docstring (if it exists).  This makes it possible to
-   create read-only properties easily using :func:`property` as a decorator::
+   create read-only properties easily using :func:`property` as a :term:`decorator`::
 
       class Parrot(object):
           def __init__(self):
@@ -906,7 +906,7 @@ available.  They are listed here in alphabetical order.
 
    .. index:: single: Numerical Python
 
-   Return a slice object representing the set of indices specified by
+   Return a :term:`slice` object representing the set of indices specified by
    ``range(start, stop, step)``.  The *start* and *step* arguments default to
    ``None``.  Slice objects have read-only data attributes :attr:`start`,
    :attr:`stop` and :attr:`step` which merely return the argument values (or their
@@ -952,8 +952,8 @@ available.  They are listed here in alphabetical order.
           @staticmethod
           def f(arg1, arg2, ...): ...
 
-   The ``@staticmethod`` form is a function decorator -- see the description of
-   function definitions in :ref:`function` for details.
+   The ``@staticmethod`` form is a function :term:`decorator` -- see the
+   description of function definitions in :ref:`function` for details.
 
    It can be called either on the class (such as ``C.f()``) or on an instance (such
    as ``C().f()``).  The instance is ignored except for its class.

Doc/library/functools.rst

@@ -76,9 +76,9 @@ The :mod:`functools` module defines the following functions:
    *WRAPPER_UPDATES* (which updates the wrapper function's *__dict__*, i.e. the
    instance dictionary).
 
-   The main intended use for this function is in decorator functions which wrap the
-   decorated function and return the wrapper. If the wrapper function is not
-   updated, the metadata of the returned function will reflect the wrapper
+   The main intended use for this function is in :term:`decorator` functions which
+   wrap the decorated function and return the wrapper. If the wrapper function is
+   not updated, the metadata of the returned function will reflect the wrapper
    definition rather than the original function definition, which is typically less
    than helpful.
 

Doc/library/inspect.rst

@@ -220,7 +220,7 @@ attributes:
 
 .. function:: isfunction(object)
 
-   Return true if the object is a Python function or unnamed (lambda) function.
+   Return true if the object is a Python function or unnamed (:term:`lambda`) function.
 
 
 .. function:: istraceback(object)

Doc/library/mmap.rst

@@ -84,6 +84,49 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
    *offset* may be specified as a non-negative integer offset. mmap references will 
    be relative to the offset from the beginning of the file. *offset* defaults to 0.
    *offset* must be a multiple of the PAGESIZE or ALLOCATIONGRANULARITY.
+   
+   This example shows a simple way of using :func:`mmap`::
+
+      import mmap
+
+      # write a simple example file
+      with open("hello.txt", "w") as f:
+          f.write("Hello Python!\n")
+
+      with open("hello.txt", "r+") as f:
+          # memory-map the file, size 0 means whole file
+          map = mmap.mmap(f.fileno(), 0)
+          # read content via standard file methods
+          print map.readline()  # prints "Hello Python!"
+          # read content via slice notation
+          print map[:5]  # prints "Hello"
+          # update content using slice notation;
+          # note that new content must have same size
+          map[6:] = " world!\n"
+          # ... and read again using standard file methods
+          map.seek(0)
+          print map.readline()  # prints "Hello  world!"
+          # close the map
+          map.close()
+
+
+   The next example demonstrates how to create an anonymous map and exchange
+   data between the parent and child processes::
+
+      import mmap
+      import os
+
+      map = mmap.mmap(-1, 13)
+      map.write("Hello world!")
+
+      pid = os.fork()
+
+      if pid == 0: # In a child process
+          map.seek(0)
+          print map.readline()
+
+          map.close()
+
 
 Memory-mapped file objects support the following methods:
 

Doc/library/operator.rst

@@ -262,10 +262,10 @@ Operations which work with sequences include:
 
 Many operations have an "in-place" version.  The following functions provide a
 more primitive access to in-place operators than the usual syntax does; for
-example, the statement ``x += y`` is equivalent to ``x = operator.iadd(x, y)``.
-Another way to put it is to say that ``z = operator.iadd(x, y)`` is equivalent
-to the compound statement ``z = x; z += y``.
-
+example, the :term:`statement` ``x += y`` is equivalent to
+``x = operator.iadd(x, y)``.  Another way to put it is to say that
+``z = operator.iadd(x, y)`` is equivalent to the compound statement
+``z = x; z += y``.
 
 .. function:: iadd(a, b)
               __iadd__(a, b)

Doc/library/stdtypes.rst

@@ -2149,8 +2149,8 @@ decimal arithmetic context. The specific types are not treated specially beyond
 their implementation of the context management protocol. See the
 :mod:`contextlib` module for some examples.
 
-Python's :term:`generator`\s and the ``contextlib.contextfactory`` decorator provide a
-convenient way to implement these protocols.  If a generator function is
+Python's :term:`generator`\s and the ``contextlib.contextfactory`` :term:`decorator`
+provide a convenient way to implement these protocols.  If a generator function is
 decorated with the ``contextlib.contextfactory`` decorator, it will return a
 context manager implementing the necessary :meth:`__enter__` and
 :meth:`__exit__` methods, rather than the iterator produced by an undecorated

Doc/library/sys.rst

@@ -80,9 +80,9 @@ always available.
    If *value* is not ``None``, this function prints it to ``sys.stdout``, and saves
    it in ``builtins._``.
 
-   ``sys.displayhook`` is called on the result of evaluating an expression entered
-   in an interactive Python session.  The display of these values can be customized
-   by assigning another one-argument function to ``sys.displayhook``.
+   ``sys.displayhook`` is called on the result of evaluating an :term:`expression`
+   entered in an interactive Python session.  The display of these values can be
+   customized by assigning another one-argument function to ``sys.displayhook``.
 
 
 .. function:: excepthook(type, value, traceback)
@@ -536,14 +536,16 @@ always available.
           stderr
 
    File objects corresponding to the interpreter's standard input, output and error
-   streams.  ``stdin`` is used for all interpreter input except for scripts.
-   ``stdout`` is used for the output of :func:`print` and expression statements.
-   The interpreter's own prompts and (almost all of) its error messages go to
-   ``stderr``.  ``stdout`` and ``stderr`` needn't be built-in file objects: any
-   object is acceptable as long as it has a :meth:`write` method that takes a
-   string argument.  (Changing these objects doesn't affect the standard I/O
-   streams of processes executed by :func:`os.popen`, :func:`os.system` or the
-   :func:`exec\*` family of functions in the :mod:`os` module.)
+   streams.  ``stdin`` is used for all interpreter input except for scripts but
+   including calls to :func:`input`.  ``stdout`` is used for
+   the output of :func:`print` and :term:`expression` statements and for the
+   prompts of :func:`input`. The interpreter's own prompts
+   and (almost all of) its error messages go to ``stderr``.  ``stdout`` and
+   ``stderr`` needn't be built-in file objects: any object is acceptable as long
+   as it has a :meth:`write` method that takes a string argument.  (Changing these 
+   objects doesn't affect the standard I/O streams of processes executed by
+   :func:`os.popen`, :func:`os.system` or the :func:`exec\*` family of functions in
+   the :mod:`os` module.)
 
 
 .. data:: __stdin__

Doc/library/timeit.rst

@@ -85,11 +85,12 @@ The module defines the following public class:
 
    .. note::
 
-      By default, :meth:`timeit` temporarily turns off garbage collection during the
-      timing.  The advantage of this approach is that it makes independent timings
-      more comparable.  This disadvantage is that GC may be an important component of
-      the performance of the function being measured.  If so, GC can be re-enabled as
-      the first statement in the *setup* string.  For example::
+      By default, :meth:`timeit` temporarily turns off :term:`garbage collection`
+      during the timing.  The advantage of this approach is that it makes
+      independent timings more comparable.  This disadvantage is that GC may be
+      an important component of the performance of the function being measured.
+      If so, GC can be re-enabled as the first statement in the *setup* string.
+      For example::
 
          timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
 

Doc/library/weakref.rst

@@ -20,22 +20,22 @@ In the following, the term :dfn:`referent` means the object which is referred to
 by a weak reference.
 
 A weak reference to an object is not enough to keep the object alive: when the
-only remaining references to a referent are weak references, garbage collection
-is free to destroy the referent and reuse its memory for something else.  A
-primary use for weak references is to implement caches or mappings holding large
-objects, where it's desired that a large object not be kept alive solely because
-it appears in a cache or mapping.  For example, if you have a number of large
-binary image objects, you may wish to associate a name with each.  If you used a
-Python dictionary to map names to images, or images to names, the image objects
-would remain alive just because they appeared as values or keys in the
-dictionaries.  The :class:`WeakKeyDictionary`, :class:`WeakValueDictionary`
-and :class:`WeakSet` classes supplied by the :mod:`weakref` module are an
-alternative, using weak references to construct mappings that don't keep objects
-alive solely because they appear in the container objects.
-If, for example, an image object is a value in a :class:`WeakValueDictionary`,
-then when the last remaining references to that image object are the weak
-references held by weak mappings, garbage collection can reclaim the object,
-and its corresponding entries in weak mappings are simply deleted.
+only remaining references to a referent are weak references,
+:term:`garbage collection` is free to destroy the referent and reuse its memory
+for something else.  A primary use for weak references is to implement caches or
+mappings holding large objects, where it's desired that a large object not be
+kept alive solely because it appears in a cache or mapping.  For example, if you
+have a number of large binary image objects, you may wish to associate a name
+with each.  If you used a Python dictionary to map names to images, or images to
+names, the image objects would remain alive just because they appeared as values
+or keys in the dictionaries.  The :class:`WeakKeyDictionary` and
+:class:`WeakValueDictionary` classes supplied by the :mod:`weakref` module are
+an alternative, using weak references to construct mappings that don't keep
+objects alive solely because they appear in the mapping objects.  If, for
+example, an image object is a value in a :class:`WeakValueDictionary`, then when
+the last remaining references to that image object are the weak references held
+by weak mappings, garbage collection can reclaim the object, and its
+corresponding entries in weak mappings are simply deleted.
 
 :class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references
 in their implementation, setting up callback functions on the weak references

Doc/library/windows.rst

+.. _mswin-specific-services:
 
 ****************************
 MS Windows Specific Services

Doc/library/xml.etree.elementtree.rst

@@ -31,6 +31,9 @@ convert it from and to XML.
 
 A C implementation of this API is available as :mod:`xml.etree.cElementTree`.
 
+See http://effbot.org/zone/element-index.htm for tutorials and links to other
+docs. Fredrik Lundh's page is also the location of the development version of the 
+xml.etree.ElementTree.
 
 .. _elementtree-functions:
 
@@ -355,6 +358,33 @@ ElementTree Objects
    object opened for writing. *encoding* is the output encoding (default is
    US-ASCII).
 
+This is the XML file that is going to be manipulated::
+
+    <html>
+        <head>
+            <title>Example page</title>
+        </head>
+        <body>
+            <p>Moved to <a href="http://example.org/">example.org</a> 
+            or <a href="http://example.com/">example.com</a>.</p>
+        </body>
+    </html>
+
+Example of changing the attribute "target" of every link in first paragraph::
+
+    >>> from xml.etree.ElementTree import ElementTree
+    >>> tree = ElementTree()
+    >>> tree.parse("index.xhtml")
+    <Element html at b7d3f1ec>
+    >>> p = tree.find("body/p")     # Finds first occurrence of tag p in body
+    >>> p
+    <Element p at 8416e0c>
+    >>> links = p.getiterator("a")  # Returns list of all links
+    >>> links
+    [<Element a at b7d4f9ec>, <Element a at b7d4fb0c>]
+    >>> for i in links:             # Iterates through all found links
+    ...     i.attrib["target"] = "blank"
+    >>> tree.write("output.xhtml")
 
 .. _elementtree-qname-objects:
 
@@ -440,3 +470,41 @@ XMLTreeBuilder Objects
 
    Feeds data to the parser. *data* is encoded data.
 
+:meth:`XMLTreeBuilder.feed` calls *target*\'s :meth:`start` method
+for each opening tag, its :meth:`end` method for each closing tag,
+and data is processed by method :meth:`data`. :meth:`XMLTreeBuilder.close` 
+calls *target*\'s method :meth:`close`. 
+:class:`XMLTreeBuilder` can be used not only for building a tree structure. 
+This is an example of counting the maximum depth of an XML file::
+
+    >>> from xml.etree.ElementTree import XMLTreeBuilder
+    >>> class MaxDepth:                     # The target object of the parser
+    ...     maxDepth = 0
+    ...     depth = 0
+    ...     def start(self, tag, attrib):   # Called for each opening tag.
+    ...         self.depth += 1 
+    ...         if self.depth > self.maxDepth:
+    ...             self.maxDepth = self.depth
+    ...     def end(self, tag):             # Called for each closing tag.
+    ...         self.depth -= 1
+    ...     def data(self, data):   
+    ...         pass            # We do not need to do anything with data.
+    ...     def close(self):    # Called when all data has been parsed.
+    ...         return self.maxDepth
+    ... 
+    >>> target = MaxDepth()
+    >>> parser = XMLTreeBuilder(target=target)
+    >>> exampleXml = """
+    ... <a>
+    ...   <b>
+    ...   </b>
+    ...   <b>
+    ...     <c>
+    ...       <d>
+    ...       </d>
+    ...     </c>
+    ...   </b>
+    ... </a>"""
+    >>> parser.feed(exampleXml)
+    >>> parser.close()
+    4

Doc/reference/compound_stmts.rst

@@ -421,7 +421,7 @@ when the function is called.
 The function definition does not execute the function body; this gets executed
 only when the function is called.
 
-A function definition may be wrapped by one or more decorator expressions.
+A function definition may be wrapped by one or more :term:`decorator` expressions.
 Decorator expressions are evaluated when the function is defined, in the scope
 that contains the function definition.  The result must be a callable, which is
 invoked with the function object as the only argument. The returned value is

Doc/tutorial/stdlib2.rst

@@ -244,8 +244,8 @@ Weak References
 ===============
 
 Python does automatic memory management (reference counting for most objects and
-garbage collection to eliminate cycles).  The memory is freed shortly after the
-last reference to it has been eliminated.
+:term:`garbage collection` to eliminate cycles).  The memory is freed shortly
+after the last reference to it has been eliminated.
 
 This approach works fine for most applications but occasionally there is a need
 to track objects only as long as they are being used by something else.

Doc/using/cmdline.rst

 .. highlightlang:: none
 
+.. _using-on-general:
+
 Command line and environment
 ============================
 
@@ -12,6 +14,8 @@ settings.
    :ref:`implementations` for further resources.
 
 
+.. _using-on-cmdline:
+
 Command line
 ------------
 
@@ -289,35 +293,7 @@ Miscellaneous options
    
    .. warning:: The line numbers in error messages will be off by one!
 
-
-Related files -- UNIX
----------------------
-
-These are subject to difference depending on local installation conventions;
-:envvar:`prefix` (``${prefix}``) and :envvar:`exec_prefix` (``${exec_prefix}``)
-are installation-dependent and should be interpreted as for GNU software; they
-may be the same.
-
-For example, on most Linux systems, the default for both is :file:`/usr`.
-
-+-----------------------------------------------+------------------------------------------+
-| File/directory                                | Meaning                                  |
-+===============================================+==========================================+
-| :file:`{exec_prefix}/bin/python`              | Recommended location of the interpreter. |
-+-----------------------------------------------+------------------------------------------+
-| :file:`{prefix}/lib/python{version}`,         | Recommended locations of the directories |
-| :file:`{exec_prefix}/lib/python{version}`     | containing the standard modules.         |
-+-----------------------------------------------+------------------------------------------+
-| :file:`{prefix}/include/python{version}`,     | Recommended locations of the directories |
-| :file:`{exec_prefix}/include/python{version}` | containing the include files needed for  |
-|                                               | developing Python extensions and         |
-|                                               | embedding the interpreter.               |
-+-----------------------------------------------+------------------------------------------+
-| :file:`~/.pythonrc.py`                        | User-specific initialization file loaded |
-|                                               | by the user module; not used by default  |
-|                                               | or by most applications.                 |
-+-----------------------------------------------+------------------------------------------+
-
+.. _using-on-envvars:
 
 Environment variables
 ---------------------

Doc/using/index.rst

@@ -13,5 +13,6 @@ interpreter and things that make working with Python easier.
 .. toctree::
 
    cmdline.rst
+   windows.rst
    mac.rst
 

Doc/using/windows.rst

+.. highlightlang:: none
+
+.. _using-on-windows:
+
+*************************
+ Using Python on Windows
+*************************
+
+.. sectionauthor:: Robert Lehmann <lehmannro@gmail.com>
+
+This document aims to give an overview of Windows-specific behaviour you should
+know about when using Python on Microsoft Windows.
+
+
+Installing Python
+=================
+
+Unlike most Unix systems and services, Windows does not require Python natively
+and thus does not pre-install a version of Python.  However, the CPython team
+has compiled Windows installers (MSI packages) with every `release
+<http://www.python.org/download/releases/>`_ for many years.
+
+With ongoing development of Python, some platforms that used to be supported
+earlier are not longer supported (due to the lack of users or developers).
+Check :pep:`11` for details on all unsupported platforms.
+
+* DOS and Windows 3.x are deprecated since Python 2.0 and code specific to these
+  systems was removed in Python 2.1.
+* Up to 2.5, Python was still compatible with Windows 95, 98 and ME (but already
+  raised a deprecation warning on installation).  For Python 2.6 (and all
+  following releases), this support was dropped and new releases are just
+  expected to work on the Windows NT family.
+* `Windows CE <http://pythonce.sourceforge.net/>`_ is still supported.
+* The `Cygwin <http://cygwin.com/>`_ installer offers to install the `Python
+  interpreter <http://cygwin.com/packages/python>`_ as well; it is located under
+  "Interpreters." (cf. `Cygwin package source
+  <ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/mirrors/cygnus/
+  release/python>`_, `Maintainer releases
+  <http://www.tishler.net/jason/software/python/>`_)
+
+See `Python for Windows (and DOS) <http://www.python.org/download/windows/>`_
+for detailed information about platforms with precompiled installers.
+
+.. seealso::
+
+   `Python on XP <http://www.richarddooling.com/index.php/2006/03/14/python-on-xp-7-minutes-to-hello-world/>`_
+      "7 Minutes to "Hello World!""
+      by Richard Dooling, 2006
+
+   `Installing on Windows <http://diveintopython.org/installing_python/windows.html>`_
+      in "`Dive into Python: Python from novice to pro
+      <http://diveintopython.org/index.html>`_"
+      by Mark Pilgrim, 2004,
+      ISBN 1-59059-356-1
+
+   `For Windows users <http://swaroopch.com/text/Byte_of_Python:Installing_Python#For_Windows_users>`_
+      in "Installing Python"
+      in "`A Byte of Python <http://www.byteofpython.info>`_"
+      by Swaroop C H, 2003
+
+
+Alternative bundles
+===================
+
+Besides the standard CPython distribution, there are modified packages including
+additional functionality.  The following is a list of popular versions and their
+key features:
+
+`ActivePython <http://www.activestate.com/Products/activepython/>`_
+    Installer with multi-platform compatibility, documentation, PyWin32
+
+`Python Enthought Edition <http://code.enthought.com/enthon/>`_
+    Popular modules (such as PyWin32) with their respective documentation, tool
+    suite for building extensible python applications
+
+
+
+Configuring Python
+==================
+
+In order to run Python flawlessly, you might have to change certain environment
+settings in Windows.
+
+
+Excursus: Setting environment variables
+---------------------------------------
+
+Windows has a built-in dialog for changing environment variables: Right-click
+the icon for your machine (usually located on your Desktop and called "My
+Computer") and choose :menuselection:`Properties` there.  Then, open the
+:guilabel:`Advanced` tab and click the :guilabel:`Environment Variables` button.
+
+In short, your path is:
+
+    :menuselection:`My Computer
+    --> Properties
+    --> Advanced
+    --> Environment Variables`
+
+In this dialog, you can add or modify User and System variables. To change
+System variables, you need non-restricted access to your machine
+(i.e. Administrator rights).
+
+Another way of adding variables to your environment is using the :command:`set`
+command::
+
+    set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
+
+To make this setting permanent, you could add the corresponding command line to
+your :file:`autoexec.bat`.
+
+Viewing environment variables can also be done more straight-forward: The
+command prompt will expand strings wrapped into percent signs automatically::
+
+    echo %PATH%
+
+Consult :command:`set /?` for details on this behaviour.
+
+.. seealso::
+
+   http://support.microsoft.com/kb/100843
+      Environment variables in Windows NT
+
+   http://support.microsoft.com/kb/310519
+      How To Manage Environment Variables in Windows XP
+
+
+Finding the Python executable
+-----------------------------
+
+Besides using the automatically created start menu entry for the Python
+interpreter, you might want to start Python in the DOS prompt.  To make this
+work, you need to set your :envvar:`%PATH%` environment variable to include the
+directory of your Python distribution, delimited by a semicolon from other
+entries.  An example variable could look like this (assuming the first two
+entries are Windows' default)::
+
+    C:\WINNT\system32;C:\WINNT;C:\Python25
+
+Typing :command:`python` on your command prompt will now fire up the Python
+interpreter.  Thus, you can also execute your scripts with command line options,
+see :ref:`using-on-cmdline` documentation.
+
+
+Finding modules
+---------------
+
+Python usually stores its library (and thereby your site-packages folder) in the
+installation directory.  So, if you had installed Python to
+:file:`C:\\Python\\`, the default library would reside in
+:file:`C:\\Python\\Lib\\` and third-party modules should be stored in
+:file:`C:\\Python\\Lib\\site-packages\\`.
+
+.. % `` this fixes syntax highlighting errors in some editors
+   due to the \\ hackery
+
+You can add folders to your search path to make Python's import mechanism search
+in these directories as well.  Use :envvar:`PYTHONPATH`, as described in
+:ref:`using-on-envvars`, to modify :data:`sys.path`.  On Windows, paths are
+separated by semicolons, though, to distinguish them from drive identifiers
+(:file:`C:\\` etc.).
+
+.. % ``
+
+Modifying the module search path can also be done through the Windows registry:
+Edit
+:file:`HKEY_LOCAL_MACHINE\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath\\`,
+as described above for the environment variable :envvar:`%PYTHONPATH%`.  A
+convenient registry editor is :program:`regedit` (start it by typing "regedit"
+into :menuselection:`Start --> Run`).
+
+
+Executing scripts
+-----------------
+
+Python scripts (files with the extension ``.py``) will be executed by
+:program:`python.exe` by default.  This executable opens a terminal, which stays
+open even if the program uses a GUI.  If you do not want this to happen, use the
+extension ``.pyw`` which will cause the script to be executed by
+:program:`pythonw.exe` by default (both executables are located in the top-level
+of your Python installation directory).  This suppresses the terminal window on
+startup.
+
+You can also make all ``.py`` scripts execute with :program:`pythonw.exe`,
+setting this through the usual facilites, for example (names might differ,
+depending on your version of Windows):
+
+#. Open the context menu of a :file:`{*}.py` file.
+#. Click :menuselection:`Open with...`.
+#. Choose the interpreter of your choice (utilize :guilabel:`Other...` or
+   :guilabel:`Choose Program...` if it is not in the list of default programs).
+#. Check :guilabel:`Always open files with this program`.
+#. Click :guilabel:`OK`.
+
+
+
+Additional modules
+==================
+
+Even though Python aims to be portable among all platforms, there are features
+that are unique to Windows.  A couple of modules, both in the standard library
+and external, and snippets exist to use these features.
+
+The Windows-specific standard modules are documented in
+:ref:`mswin-specific-services`.
+
+
+PyWin32
+-------
+
+The `PyWin32 <http://python.net/crew/mhammond/win32/>`_ module by Mark Hammond
+is a collection of modules for advanced Windows-specific support.  This includes
+utilites for:
+
+* `Component Object Model <http://www.microsoft.com/com/>`_ (COM)
+* Win32 API calls
+* Registry
+* Event log
+* `Microsoft Foundation Classes <http://msdn.microsoft.com/library/
+  en-us/vclib/html/_mfc_Class_Library_Reference_Introduction.asp>`_ (MFC)
+  user interfaces
+
+`PythonWin <http://web.archive.org/web/20060524042422/
+http://www.python.org/windows/pythonwin/>`_ is a sample MFC application
+shipped with PyWin32.  It is an embeddable IDE with a built-in debugger.
+
+.. seealso::
+
+   `Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_
+      by Tim Golden
+
+   `Python and COM <http://www.boddie.org.uk/python/COM.html>`_
+      by David and Paul Boddie
+
+
+Py2exe
+------
+
+`Py2exe <http://www.py2exe.org/>`_ is a :mod:`distutils` extension (see
+:ref:`extending-distutils`) which wraps Python scripts into executable Windows
+programs (:file:`{*}.exe` files).  When you have done this, you can distribute
+your application without requiring your users to install Python.
+
+
+WConio
+------
+
+Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to
+Unix-like systems, there is a library exclusive to Windows as well: Windows
+Console I/O for Python.
+
+`WConio <http://newcenturycomputers.net/projects/wconio.html>`_ is a wrapper for
+Turbo-C's :file:`CONIO.H`, used to create text user interfaces.
+
+
+
+Compiling Python on Windows
+===========================
+
+If you want to compile CPython yourself, first thing you should do is get the
+`source <http://python.org/download/source/>`_. You can download either the
+latest release's source or just grab a fresh `checkout
+<http://www.python.org/dev/faq/
+#how-do-i-get-a-checkout-of-the-repository-read-only-and-read-write>`_.
+
+For Microsoft Visual C++, which is the compiler with which official Python
+releases are built, the source tree contains solutions/project files.  View the
+:file:`readme.txt` in their respective directories:
+
++--------------------+--------------+-----------------------+
+| Directory          | MSVC version | Visual Studio version |
++====================+==============+=======================+
+| :file:`PC/VC6/`    | 5.0          | 97                    |
+|                    +--------------+-----------------------+
+|                    | 6.0          | 6.0                   |
++--------------------+--------------+-----------------------+
+| :file:`PCbuild/`   | 7.1          | 2003                  |
++--------------------+--------------+-----------------------+
+| :file:`PCbuild8/`  | 8.0          | 2005                  |
++--------------------+--------------+-----------------------+
+| :file:`PCbuild9/`  | 9.0          | 2008                  |
++--------------------+--------------+-----------------------+
+
+Note that not all of these build directories are fully supported.  Read the
+release notes to see which compiler version the official releases for your
+version are built with.
+
+Check :file:`PC/readme.txt` for general information on the build process.
+
+
+For extension modules, consult :ref:`building-on-windows`.
+
+.. seealso::
+
+   `Python + Windows + distutils + SWIG + gcc MinGW <http://sebsauvage.net/python/mingw.html>`_
+      or "Creating Python extensions in C/C++ with SWIG and compiling them with
+      MinGW gcc under Windows" or "Installing Python extension with distutils
+      and without Microsoft Visual C++" by Sébastien Sauvage, 2003
+
+   `MingW -- Python extensions <http://www.mingw.org/MinGWiki/index.php/Python%20extensions>`_
+      by Trent Apted et al, 2007
+
+
+Other resources
+===============
+
+.. seealso::
+
+   `Python Programming On Win32 <http://www.oreilly.com/catalog/pythonwin32/>`_
+      "Help for Windows Programmers"
+      by Mark Hammond and Andy Robinson, O'Reilly Media, 2000,
+      ISBN 1-56592-621-8
+
+   `A Python for Windows Tutorial <http://www.imladris.com/Scripts/PythonForWindows.html>`_
+      by Amanda Birmingham, 2004
+

Lib/tarfile.py

@@ -1542,7 +1542,8 @@ class TarFile(object):
         self.closed = False
         self.members = []       # list of members as TarInfo objects
         self._loaded = False    # flag if all members have been read
-        self.offset = 0         # current position in the archive file
+        self.offset = self.fileobj.tell()
+                                # current position in the archive file
         self.inodes = {}        # dictionary caching the inodes of
                                 # archive members already added
 

Lib/test/test_cmd.py

+#!/usr/bin/env python
+"""
+Test script for the 'cmd' module
+Original by Michael Schneider
+"""
+
+
+from test import test_support
+import cmd
+import sys
+
+class samplecmdclass(cmd.Cmd):
+    """
+    Instance the sampleclass:
+    >>> mycmd = samplecmdclass()
+
+    Test for the function parseline():
+    >>> mycmd.parseline("")
+    (None, None, '')
+    >>> mycmd.parseline("?")
+    ('help', '', 'help ')
+    >>> mycmd.parseline("?help")
+    ('help', 'help', 'help help')
+    >>> mycmd.parseline("!")
+    ('shell', '', 'shell ')
+    >>> mycmd.parseline("!command")
+    ('shell', 'command', 'shell command')
+    >>> mycmd.parseline("func")
+    ('func', '', 'func')
+    >>> mycmd.parseline("func arg1")
+    ('func', 'arg1', 'func arg1')
+
+
+    Test for the function onecmd():
+    >>> mycmd.onecmd("")
+    >>> mycmd.onecmd("add 4 5")
+    9
+    >>> mycmd.onecmd("")
+    9
+    >>> mycmd.onecmd("test")
+    *** Unknown syntax: test
+
+    Test for the function emptyline():
+    >>> mycmd.emptyline()
+    *** Unknown syntax: test
+
+    Test for the function default():
+    >>> mycmd.default("default")
+    *** Unknown syntax: default
+
+    Test for the function completedefault():
+    >>> mycmd.completedefault()
+    This is the completedefault methode
+    >>> mycmd.completenames("a")
+    ['add']
+
+    Test for the function completenames():
+    >>> mycmd.completenames("12")
+    []
+    >>> mycmd.completenames("help")
+    ['help', 'help']
+
+    Test for the function complete_help():
+    >>> mycmd.complete_help("a")
+    ['add']
+    >>> mycmd.complete_help("he")
+    ['help', 'help']
+    >>> mycmd.complete_help("12")
+    []
+
+    Test for the function do_help():
+    >>> mycmd.do_help("testet")
+    *** No help on testet
+    >>> mycmd.do_help("add")
+    help text for add
+    >>> mycmd.onecmd("help add")
+    help text for add
+    >>> mycmd.do_help("")
+    <BLANKLINE>
+    Documented commands (type help <topic>):
+    ========================================
+    add
+    <BLANKLINE>
+    Undocumented commands:
+    ======================
+    exit  help  shell
+    <BLANKLINE>
+
+    Test for the function print_topics():
+    >>> mycmd.print_topics("header", ["command1", "command2"], 2 ,10)
+    header
+    ======
+    command1
+    command2
+    <BLANKLINE>
+
+    Test for the function columnize():
+    >>> mycmd.columnize([str(i) for i in xrange(20)])
+    0  1  2  3  4  5  6  7  8  9  10  11  12  13  14  15  16  17  18  19
+    >>> mycmd.columnize([str(i) for i in xrange(20)], 10)
+    0  7   14
+    1  8   15
+    2  9   16
+    3  10  17
+    4  11  18
+    5  12  19
+    6  13
+
+    This is a interactive test, put some commands in the cmdqueue attribute
+    and let it execute
+    This test includes the preloop(), postloop(), default(), emptyline(),
+    parseline(), do_help() functions
+    >>> mycmd.use_rawinput=0
+    >>> mycmd.cmdqueue=["", "add", "add 4 5", "help", "help add","exit"]
+    >>> mycmd.cmdloop()
+    Hello from preloop
+    help text for add
+    *** invalid number of arguments
+    9
+    <BLANKLINE>
+    Documented commands (type help <topic>):
+    ========================================
+    add
+    <BLANKLINE>
+    Undocumented commands:
+    ======================
+    exit  help  shell
+    <BLANKLINE>
+    help text for add
+    Hello from postloop
+    """
+
+    def preloop(self):
+        print "Hello from preloop"
+
+    def postloop(self):
+        print "Hello from postloop"
+
+    def completedefault(self, *ignored):
+        print "This is the completedefault methode"
+        return
+
+    def complete_command(self):
+        print "complete command"
+        return
+
+    def do_shell(self):
+        pass
+
+    def do_add(self, s):
+        l = s.split()
+        if len(l) != 2:
+            print "*** invalid number of arguments"
+            return
+        try:
+            l = [int(i) for i in l]
+        except ValueError:
+            print "*** arguments should be numbers"
+            return
+        print l[0]+l[1]
+
+    def help_add(self):
+        print "help text for add"
+        return
+
+    def do_exit(self, arg):
+        return True
+
+def test_main(verbose=None):
+    from test import test_support, test_cmd
+    test_support.run_doctest(test_cmd, verbose)
+
+import trace, sys,re,StringIO
+def test_coverage(coverdir):
+    tracer=trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,],
+                        trace=0, count=1)
+    tracer.run('reload(cmd);test_main()')
+    r=tracer.results()
+    print "Writing coverage results..."
+    r.write_results(show_missing=True, summary=True, coverdir=coverdir)
+
+if __name__ == "__main__":
+    if "-c" in sys.argv:
+        test_coverage('/tmp/cmd.cover')
+    else:
+        test_main()

Lib/test/test_tarfile.py

@@ -159,6 +159,38 @@ class MiscReadTest(ReadTest):
         tar = tarfile.open(fileobj=fobj, mode=self.mode)
         self.assertEqual(tar.name, None)
 
+    def test_fileobj_with_offset(self):
+        # Skip the first member and store values from the second member
+        # of the testtar.
+        tar = tarfile.open(self.tarname, mode=self.mode)
+        tar.next()
+        t = tar.next()
+        name = t.name
+        offset = t.offset
+        data = tar.extractfile(t).read()
+        tar.close()
+
+        # Open the testtar and seek to the offset of the second member.
+        if self.mode.endswith(":gz"):
+            _open = gzip.GzipFile
+        elif self.mode.endswith(":bz2"):
+            _open = bz2.BZ2File
+        else:
+            _open = open
+        fobj = _open(self.tarname, "rb")
+        fobj.seek(offset)
+
+        # Test if the tarfile starts with the second member.
+        tar = tar.open(self.tarname, mode="r:", fileobj=fobj)
+        t = tar.next()
+        self.assertEqual(t.name, name)
+        # Read to the end of fileobj and test if seeking back to the
+        # beginning works.
+        tar.getmembers()
+        self.assertEqual(tar.extractfile(t).read(), data,
+                "seek back did not work")
+        tar.close()
+
     def test_fail_comp(self):
         # For Gzip and Bz2 Tests: fail with a ReadError on an uncompressed file.
         if self.mode == "r:":

Misc/ACKS

@@ -579,6 +579,7 @@ Neil Schemenauer
 David Scherer
 Gregor Schmid
 Ralf Schmitt
+Michael Schneider
 Peter Schneider-Kamp
 Arvin Schnell
 Chad J. Schroeder