Merged revisions 59952-59984 via svnmerge from

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

........
  r59952 | thomas.heller | 2008-01-14 02:35:28 -0800 (Mon, 14 Jan 2008) | 1 line

  Issue 1821: configure libffi for amd64 on FreeeBSD.
........
  r59953 | andrew.kuchling | 2008-01-14 06:48:43 -0800 (Mon, 14 Jan 2008) | 1 line

  Update description of float_info
........
  r59959 | raymond.hettinger | 2008-01-14 14:58:05 -0800 (Mon, 14 Jan 2008) | 1 line

  Fix 1698398:  Zipfile.printdir() crashed because the format string expected a tuple object of length six instead of a time.struct_time object.
........
  r59961 | andrew.kuchling | 2008-01-14 17:29:16 -0800 (Mon, 14 Jan 2008) | 1 line

  Typo fixes
........
  r59962 | andrew.kuchling | 2008-01-14 17:29:44 -0800 (Mon, 14 Jan 2008) | 1 line

  Markup fix
........
  r59963 | andrew.kuchling | 2008-01-14 17:47:32 -0800 (Mon, 14 Jan 2008) | 1 line

  Add many items
........
  r59964 | andrew.kuchling | 2008-01-14 17:55:32 -0800 (Mon, 14 Jan 2008) | 1 line

  Repair unfinished sentence
........
  r59967 | raymond.hettinger | 2008-01-14 19:02:37 -0800 (Mon, 14 Jan 2008) | 5 lines

  Issue 1820:  structseq objects did not work with the % formatting operator or isinstance(t, tuple).

  Orignal patch (without tests) by Leif Walsh.
........
  r59968 | raymond.hettinger | 2008-01-14 19:07:42 -0800 (Mon, 14 Jan 2008) | 1 line

  Tighten the definition of a named tuple.
........
  r59969 | skip.montanaro | 2008-01-14 19:40:20 -0800 (Mon, 14 Jan 2008) | 3 lines

  Better (?) text describing the lack of guarantees provided by qsize(),
  empty() and full().
........
  r59970 | raymond.hettinger | 2008-01-14 21:39:59 -0800 (Mon, 14 Jan 2008) | 1 line

  Temporarily revert 59967 until GC can be added.
........
  r59971 | raymond.hettinger | 2008-01-14 21:46:43 -0800 (Mon, 14 Jan 2008) | 1 line

  Small grammar nit
........
  r59972 | georg.brandl | 2008-01-14 22:55:56 -0800 (Mon, 14 Jan 2008) | 2 lines

  Typo.
........
  r59973 | georg.brandl | 2008-01-14 22:58:15 -0800 (Mon, 14 Jan 2008) | 2 lines

  Remove duplicate entry.
........
  r59974 | jeffrey.yasskin | 2008-01-14 23:46:24 -0800 (Mon, 14 Jan 2008) | 12 lines

  Add rational.Rational as an implementation of numbers.Rational with infinite
  precision. This has been discussed at http://bugs.python.org/issue1682. It's
  useful primarily for teaching, but it also demonstrates how to implement a
  member of the numeric tower, including fallbacks for mixed-mode arithmetic.

  I expect to write a couple more patches in this area:
   * Rational.from_decimal()
   * Rational.trim/approximate() (maybe with different names)
   * Maybe remove the parentheses from Rational.__str__()
   * Maybe rename one of the Rational classes
   * Maybe make Rational('3/2') work.
........
  r59978 | andrew.kuchling | 2008-01-15 06:38:05 -0800 (Tue, 15 Jan 2008) | 8 lines

  Restore description of sys.dont_write_bytecode.

  The duplication is intentional -- this paragraph is in a section
  describing additions to the sys module, and there's a later section
  that mentions the switch.  I think most people scan the what's-new and
  don't read it in detail, so a bit of duplication is OK.
........
  r59984 | guido.van.rossum | 2008-01-15 09:59:29 -0800 (Tue, 15 Jan 2008) | 3 lines

  Issue #1786 (by myself): pdb should use its own stdin/stdout around an
  exec call and when creating a recursive instance.
........

7 files changed, 212 insertions, 16 deletions

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 5c11ae0..13c254c 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -329,7 +329,7 @@ Glossary
       also :term:`immutable`.
 
    named tuple
-      Any tuple-like class whose indexable fields are also accessible with
+      Any tuple subclass whose indexable fields are also accessible with
       named attributes (for example, :func:`time.localtime` returns a
       tuple-like object where the *year* is accessible either with an
       index such as ``t[0]`` or with a named attribute like ``t.tm_year``).
diff --git a/Doc/library/numeric.rst b/Doc/library/numeric.rst
index d2b4d8b..4c65a43 100644
--- a/Doc/library/numeric.rst
+++ b/Doc/library/numeric.rst
@@ -21,6 +21,7 @@ The following modules are documented in this chapter:
    math.rst
    cmath.rst
    decimal.rst
+   rational.rst
    random.rst
    itertools.rst
    functools.rst
diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst
index c5dbc20..331680d 100644
--- a/Doc/library/queue.rst
+++ b/Doc/library/queue.rst
@@ -49,8 +49,9 @@ See the source code for details.  The public methods are:
 
 .. method:: Queue.qsize()
 
-   Return the approximate size of the queue.  Because of multithreading semantics,
-   this number is not reliable.
+   Return the approximate size of the queue.  Note, qsize() > 0 doesn't
+   guarantee that a subsequent get() will not block, nor will qsize() < maxsize
+   guarantee that put() will not block.
 
 
 .. method:: Queue.put(item[, block[, timeout]])
diff --git a/Doc/library/rational.rst b/Doc/library/rational.rst
new file mode 100644
index 0000000..dd18305
--- /dev/null
+++ b/Doc/library/rational.rst
@@ -0,0 +1,65 @@
+
+:mod:`rational` --- Rational numbers
+====================================
+
+.. module:: rational
+   :synopsis: Rational numbers.
+.. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
+.. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
+.. versionadded:: 2.6
+
+
+The :mod:`rational` module defines an immutable, infinite-precision
+Rational number class.
+
+
+.. class:: Rational(numerator=0, denominator=1)
+           Rational(other_rational)
+
+   The first version requires that *numerator* and *denominator* are
+   instances of :class:`numbers.Integral` and returns a new
+   ``Rational`` representing ``numerator/denominator``. If
+   *denominator* is :const:`0`, raises a :exc:`ZeroDivisionError`. The
+   second version requires that *other_rational* is an instance of
+   :class:`numbers.Rational` and returns an instance of
+   :class:`Rational` with the same value.
+
+   Implements all of the methods and operations from
+   :class:`numbers.Rational` and is hashable.
+
+
+.. method:: Rational.from_float(flt)
+
+   This classmethod constructs a :class:`Rational` representing the
+   exact value of *flt*, which must be a :class:`float`. Beware that
+   ``Rational.from_float(0.3)`` is not the same value as ``Rational(3,
+   10)``
+
+
+.. method:: Rational.__floor__()
+
+   Returns the greatest :class:`int` ``<= self``. Will be accessible
+   through :func:`math.floor` in Py3k.
+
+
+.. method:: Rational.__ceil__()
+
+   Returns the least :class:`int` ``>= self``. Will be accessible
+   through :func:`math.ceil` in Py3k.
+
+
+.. method:: Rational.__round__()
+            Rational.__round__(ndigits)
+
+   The first version returns the nearest :class:`int` to ``self``,
+   rounding half to even. The second version rounds ``self`` to the
+   nearest multiple of ``Rational(1, 10**ndigits)`` (logically, if
+   ``ndigits`` is negative), again rounding half toward even. Will be
+   accessible through :func:`round` in Py3k.
+
+
+.. seealso::
+
+   Module :mod:`numbers`
+      The abstract base classes making up the numeric tower.
+
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 4ab3529..6d1a09b 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -210,7 +210,7 @@ always available.
    +------------------------------+------------------------------------------+
    | :const:`no_site`             | -S                                       |
    +------------------------------+------------------------------------------+
-   | :const:`ingnore_environment` | -E                                       |
+   | :const:`ignore_environment`  | -E                                       |
    +------------------------------+------------------------------------------+
    | :const:`tabcheck`            | -t or -tt                                |
    +------------------------------+------------------------------------------+
diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index a0f7841..6c35d50 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -300,7 +300,7 @@ The :mod:`test.test_support` module defines the following functions:
 
    This is a context manager than runs the :keyword:`with` statement body using
    a :class:`StringIO.StringIO` object as sys.stdout.  That object can be
-   retrieved using the ``as`` clause of the with statement.
+   retrieved using the ``as`` clause of the :keyword:`with` statement.
 
    Example use::
 
diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index 4d90d35..0539a44 100644
--- a/Doc/whatsnew/2.6.rst
+++ b/Doc/whatsnew/2.6.rst
@@ -426,6 +426,29 @@ can now be used in scripts running from inside a package.
 
 .. ======================================================================
 
+.. ::
+
+    .. _pep-0370:
+
+    PEP 370: XXX
+    =====================================================
+
+    When you run Python, the module search page ``sys.modules`` usually
+    includes a directory whose path ends in ``"site-packages"``.  This
+    directory is intended to hold locally-installed packages available to
+    all users on a machine or using a particular site installation.
+
+    Python 2.6 introduces a convention for user-specific site directories.
+
+    .. seealso::
+
+       :pep:`370` - XXX
+
+       PEP written by XXX; implemented by Christian Heimes.
+
+  
+.. ======================================================================
+
 .. _pep-3110:
 
 PEP 3110: Exception-Handling Changes
@@ -650,6 +673,18 @@ Here are all of the changes that Python 2.6 makes to the core Python language.
 Optimizations
 -------------
 
+* Type objects now have a cache of methods that can reduce
+  the amount of work required to find the correct method implementation
+  for a particular class; once cached, the interpreter doesn't need to
+  traverse base classes to figure out the right method to call.  
+  The cache is cleared if a base class or the class itself is modified, 
+  so the cache should remain correct even in the face of Python's dynamic 
+  nature.
+  (Original optimization implemented by Armin Rigo, updated for 
+  Python 2.6 by Kevin Jacobs.) 
+
+  .. % Patch 1700288
+
 * All of the functions in the :mod:`struct` module have been rewritten in
   C, thanks to work at the Need For Speed sprint.
   (Contributed by Raymond Hettinger.)
@@ -700,6 +735,11 @@ complete list of changes, or look through the CVS logs for all the details.
      >>> v2
      variable(id=1, name='amplitude', type='int', size=4)
 
+  Where the new :class:`namedtuple` type proved suitable, the standard
+  library has been modified to return them.  For example, 
+  the :meth:`Decimal.as_tuple` method now returns a named tuple with 
+  :attr:`sign`, :attr:`digits`, and :attr:`exponent` fields.
+
   (Contributed by Raymond Hettinger.)
 
 * Another change to the :mod:`collections` module is that the 
@@ -758,7 +798,17 @@ complete list of changes, or look through the CVS logs for all the details.
     >>> Decimal(1000).log10()
     Decimal("3")
 
-  (Implemented by Facundo Batista and Mark Dickinson.)
+  The :meth:`as_tuple` method of :class:`Decimal` objects now returns a 
+  named tuple with :attr:`sign`, :attr:`digits`, and :attr:`exponent` fields.
+  
+  (Implemented by Facundo Batista and Mark Dickinson.  Named tuple
+  support added by Raymond Hettinger.)
+
+* The :mod:`difflib` module's :class:`SequenceMatcher` class 
+  now returns named tuples representing matches. 
+  In addition to behaving like tuples, the returned values
+  also have :attr:`a`, :attr:`b`, and :attr:`size` attributes.
+  (Contributed by Raymond Hettinger.)
 
 * An optional ``timeout`` parameter was added to the
   :class:`ftplib.FTP` class constructor as well as the :meth:`connect`
@@ -795,6 +845,12 @@ complete list of changes, or look through the CVS logs for all the details.
   class constructors, specifying a timeout measured in seconds.
   (Added by Facundo Batista.)
 
+* Most of the :mod:`inspect` module's functions, such as 
+  :func:`getmoduleinfo` and :func:`getargs`, now return named tuples.  
+  In addition to behaving like tuples, the elements of the  return value
+  can also be accessed as attributes.
+  (Contributed by Raymond Hettinger.)
+
 * A new function in the :mod:`itertools` module: ``izip_longest(iter1, iter2,
   ...[, fillvalue])`` makes tuples from each of the elements; if some of the
   iterables are shorter than others, the missing values  are set to *fillvalue*.
@@ -891,6 +947,13 @@ complete list of changes, or look through the CVS logs for all the details.
 
   .. Issue 1727780
 
+* Long regular expression searches carried out by the  :mod:`re`
+  module will now check for signals being delivered, so especially
+  long searches can now be interrupted.
+  (Contributed by Josh Hoyt and Ralf Schmitt.)
+
+  .. % Patch 846388
+
 * The :mod:`rgbimg` module has been removed.
 
 * The :mod:`sets` module has been deprecated; it's better to 
@@ -934,17 +997,42 @@ complete list of changes, or look through the CVS logs for all the details.
 
   .. Patch #957003
 
+* The :mod:`socket` module now supports TIPC (http://tipc.sf.net),
+  a high-performance non-IP-based protocol designed for use in clustered
+  environments.  TIPC addresses are 4- or 5-tuples.
+  (Contributed by Alberto Bertogli.)
+
+  .. Patch #1646
+ 
 * A new variable in the :mod:`sys` module,
-  :attr:`float_info`, is a dictionary 
+  :attr:`float_info`, is an object
   containing information about the platform's floating-point support
-  derived from the :file:`float.h` file.  Key/value pairs 
-  in this dictionary include 
-  ``"mant_dig"`` (number of digits in the mantissa), ``"epsilon"``
+  derived from the :file:`float.h` file.  Attributes of this object
+  include 
+  :attr:`mant_dig` (number of digits in the mantissa), :attr:`epsilon`
   (smallest difference between 1.0 and the next largest value
   representable), and several others.  (Contributed by Christian Heimes.)
 
   .. Patch 1534
 
+  Another new variable, :attr:`dont_write_bytecode`, controls whether Python
+  writes any :file:`.pyc` or :file:`.pyo` files on importing a module.
+  If this variable is true, the compiled files are not written.  The
+  variable is initially set on start-up by supplying the :option:`-B`
+  switch to the Python interpreter, or by setting the
+  :envvar:`PYTHONDONTWRITEBYTECODE` environment variable before
+  running the interpreter.  Python code can subsequently 
+  change the value of this variable to control whether bytecode files
+  are written or not.
+  (Contributed by Neal Norwitz and Georg Brandl.)
+
+  Information about the command-line arguments supplied to the Python 
+  interpreter are available as attributes of a ``sys.flags`` named 
+  tuple.  For example, the :attr:`verbose` attribute is true if Python 
+  was executed in verbose mode, :attr:`debug` is true in debugging mode, etc.
+  These attributes are all read-only.
+  (Contributed by Christian Heimes.)
+
 * The :mod:`tarfile` module now supports POSIX.1-2001 (pax) and
   POSIX.1-1988 (ustar) format tarfiles, in addition to the GNU tar
   format that was already supported.  The default format 
@@ -1061,6 +1149,22 @@ complete list of changes, or look through the CVS logs for all the details.
   information.  (Contributed by Alan McIntyre as part of his 
   project for Google's Summer of Code 2007.)
 
+* The :mod:`zipfile` module's :class:`ZipFile` class now has 
+  :meth:`extract` and :meth:`extractall` methods that will unpack 
+  a single file or all the files in the archive to the current directory, or 
+  to a specified directory::
+
+    z = zipfile.ZipFile('python-251.zip')
+
+    # Unpack a single file, writing it relative to the /tmp directory.
+    z.extract('Python/sysmodule.c', '/tmp')
+
+    # Unpack all the files in the archive.
+    z.extractall()
+
+  (Contributed by Alan McIntyre.)
+  .. % Patch 467924
+
 .. ======================================================================
 .. whole new modules get described in subsections here
 
@@ -1143,7 +1247,12 @@ Port-Specific Changes: Windows
   value, as does the :func:`getwche` function.  The :func:`putwch` function
   takes a Unicode character and writes it to the console.
 
-Platform-specific changes go here.
+* The :mod:`_winreg` module now has a function, 
+  :func:`ExpandEnvironmentStrings`, 
+  that expands environment variable references such as ``%NAME%``
+  in an input string.  The handle objects provided by this
+  module now support the context protocol, so they can be used 
+  in :keyword:`with` statements.
 
 .. ======================================================================
 
@@ -1153,14 +1262,21 @@ Platform-specific changes go here.
 Other Changes and Fixes
 =======================
 
-As usual, there were a bunch of other improvements and bugfixes scattered
-throughout the source tree.  A search through the change logs finds there were
-XXX patches applied and YYY bugs fixed between Python 2.5 and 2.6.  Both figures
-are likely to be underestimates.
+As usual, there were a bunch of other improvements and bugfixes
+scattered throughout the source tree.  A search through the change
+logs finds there were XXX patches applied and YYY bugs fixed between
+Python 2.5 and 2.6.  Both figures are likely to be underestimates.
 
 Some of the more notable changes are:
 
-* Details will go here.
+* It's now possible to prevent Python from writing any :file:`.pyc` 
+  or :file:`.pyo` files by either supplying the :option:`-B` switch
+  or setting the :envvar:`PYTHONDONTWRITEBYTECODE` environment variable
+  to any non-empty string when running the Python interpreter.  These
+  are also used to set the :data:`sys.dont_write_bytecode` attribute;
+  Python code can change this variable to control whether bytecode
+  files are subsequently written.
+  (Contributed by Neal Norwitz and Georg Brandl.)
 
 .. ======================================================================
 
@@ -1177,6 +1293,19 @@ code:
   before adding elements from the iterable.  This change makes the
   behavior match that of ``list.__init__()``.  
 
+* The :class:`Decimal` constructor now accepts leading and trailing 
+  whitespace when passed a string.  Previously it would raise an
+  :exc:`InvalidOperation` exception.  On the other hand, the
+  :meth:`create_decimal` method of :class:`Context` objects now
+  explicitly disallows extra whitespace, raising a 
+  :exc:`ConversionSyntax` exception.
+
+* Due to an implementation accident, if you passed a file path to 
+  the built-in  :func:`__import__` function, it would actually import
+  the specified file.  This was never intended to work, however, and 
+  the implementation now explicitly checks for this case and raises 
+  an :exc:`ImportError`.
+
 * The :mod:`socket` module exception :exc:`socket.error` now inherits
   from :exc:`IOError`.  Previously it wasn't a subclass of
   :exc:`StandardError` but now it is, through :exc:`IOError`.