Merged revisions 67654,67676-67677,67681,67692,67725,67761,67784-67785,67787-67788,67802,67848-67850,67862-67864,67880,67882 via svnmerge from

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

........
  r67654 | georg.brandl | 2008-12-07 16:42:09 -0600 (Sun, 07 Dec 2008) | 2 lines

  #4457: rewrite __import__() documentation.
........
  r67676 | benjamin.peterson | 2008-12-08 20:03:03 -0600 (Mon, 08 Dec 2008) | 1 line

  specify how things are copied
........
  r67677 | benjamin.peterson | 2008-12-08 20:05:11 -0600 (Mon, 08 Dec 2008) | 1 line

  revert unrelated change to installer script
........
  r67681 | jeremy.hylton | 2008-12-09 15:03:10 -0600 (Tue, 09 Dec 2008) | 2 lines

  Add simple unittests for Request
........
  r67692 | amaury.forgeotdarc | 2008-12-10 18:03:42 -0600 (Wed, 10 Dec 2008) | 2 lines

  #1030250: correctly pass the dry_run option to the mkpath() function.
........
  r67725 | benjamin.peterson | 2008-12-12 22:02:20 -0600 (Fri, 12 Dec 2008) | 1 line

  fix incorrect example
........
  r67761 | benjamin.peterson | 2008-12-14 11:26:04 -0600 (Sun, 14 Dec 2008) | 1 line

  fix missing bracket
........
  r67784 | georg.brandl | 2008-12-15 02:33:58 -0600 (Mon, 15 Dec 2008) | 2 lines

  #4446: document "platforms" argument for setup().
........
  r67785 | georg.brandl | 2008-12-15 02:36:11 -0600 (Mon, 15 Dec 2008) | 2 lines

  #4611: fix typo.
........
  r67787 | georg.brandl | 2008-12-15 02:58:59 -0600 (Mon, 15 Dec 2008) | 2 lines

  #4578: fix has_key() usage in compiler package.
........
  r67788 | georg.brandl | 2008-12-15 03:07:39 -0600 (Mon, 15 Dec 2008) | 2 lines

  #4568: remove limitation in varargs callback example.
........
  r67802 | amaury.forgeotdarc | 2008-12-15 16:29:14 -0600 (Mon, 15 Dec 2008) | 4 lines

  #3632: the "pyo" macro from gdbinit can now run when the GIL is released.

  Patch by haypo.
........
  r67848 | benjamin.peterson | 2008-12-18 20:28:56 -0600 (Thu, 18 Dec 2008) | 1 line

  fix typo
........
  r67849 | benjamin.peterson | 2008-12-18 20:31:35 -0600 (Thu, 18 Dec 2008) | 1 line

  _call_method -> _callmethod and _get_value to _getvalue
........
  r67850 | raymond.hettinger | 2008-12-19 03:06:07 -0600 (Fri, 19 Dec 2008) | 9 lines

  Fix-up and clean-up docs for int.bit_length().

  * Replace dramatic footnote with in-line comment about possible round-off errors in logarithms of large numbers.
  * Add comments to the pure python code equivalent.
  * replace floor() with int() in the mathematical equivalent so the type is correct (should be an int, not a float).
  * add abs() to the mathematical equivalent so that it matches the previous line that it is supposed to be equivalent to.
  * make one combined example with a negative input.
........
  r67862 | benjamin.peterson | 2008-12-19 20:48:02 -0600 (Fri, 19 Dec 2008) | 1 line

  copy sentence from docstring
........
  r67863 | benjamin.peterson | 2008-12-19 20:51:26 -0600 (Fri, 19 Dec 2008) | 1 line

  add headings
........
  r67864 | benjamin.peterson | 2008-12-19 20:57:19 -0600 (Fri, 19 Dec 2008) | 1 line

  beef up docstring
........
  r67880 | benjamin.peterson | 2008-12-20 16:49:24 -0600 (Sat, 20 Dec 2008) | 1 line

  remove redundant sentence
........
  r67882 | benjamin.peterson | 2008-12-20 16:59:49 -0600 (Sat, 20 Dec 2008) | 1 line

  add some recent releases to the list
........

11 files changed, 113 insertions, 93 deletions

diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst
index 6e3fd3826e..7a6be8b270 100644
--- a/Doc/distutils/setupscript.rst
+++ b/Doc/distutils/setupscript.rst
@@ -561,6 +561,8 @@ This information includes:
 +----------------------+---------------------------+-----------------+--------+
 | ``classifiers``      | a list of classifiers     | list of strings | \(4)   |
 +----------------------+---------------------------+-----------------+--------+
+| ``platforms``        | a list of platforms       | list of strings |        |
++----------------------+---------------------------+-----------------+--------+
 
 Notes:
 
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index c05bcfd7d4..ef2c726f1d 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -882,7 +882,7 @@ memory and should be avoided completely. [#]_
 The advantage of borrowing over owning a reference is that you don't need to
 take care of disposing of the reference on all possible paths through the code
 --- in other words, with a borrowed reference you don't run the risk of leaking
-when a premature exit is taken.  The disadvantage of borrowing over leaking is
+when a premature exit is taken.  The disadvantage of borrowing over owning is
 that there are some subtle situations where in seemingly correct code a borrowed
 reference can be used after the owner from which it was borrowed has in fact
 disposed of it.
diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst
index 47798e9e11..1d9b42d7b6 100644
--- a/Doc/howto/functional.rst
+++ b/Doc/howto/functional.rst
@@ -677,11 +677,10 @@ indexes at which certain conditions are met::
         if line.strip() == '':
             print('Blank line at line #%i' % i)
 
-
-``sorted(iterable, [cmp=None], [key=None], [reverse=False)`` collects all the
-elements of the iterable into a list, sorts the list, and returns the sorted
-result.  The ``cmp``, ``key``, and ``reverse`` arguments are passed through to
-the constructed list's ``.sort()`` method. ::
+``sorted(iterable, [key=None], [reverse=False])`` collects all the elements of
+the iterable into a list, sorts the list, and returns the sorted result.  The
+``key``, and ``reverse`` arguments are passed through to the constructed list's
+``.sort()`` method. ::
 
     >>> import random
     >>> # Generate 8 random numbers between [0, 10000)
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 5e29b67cf2..877d9b66ec 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1172,47 +1172,64 @@ are always available.  They are listed here in alphabetical order.
       This is an advanced function that is not needed in everyday Python
       programming.
 
-   The function is invoked by the :keyword:`import` statement.  It mainly exists
-   so that you can replace it with another function that has a compatible
-   interface, in order to change the semantics of the :keyword:`import`
-   statement.  See the built-in module :mod:`imp`, which defines some useful
-   operations out of which you can build your own :func:`__import__` function.
-
-   For example, the statement ``import spam`` results in the following call:
-   ``__import__('spam', globals(), locals(), [], -1)``; the statement
-   ``from spam.ham import eggs`` results in ``__import__('spam.ham', globals(),
-   locals(), ['eggs'], -1)``.  Note that even though ``locals()`` and ``['eggs']``
-   are passed in as arguments, the :func:`__import__` function does not set the
-   local variable named ``eggs``; this is done by subsequent code that is generated
-   for the import statement.  (In fact, the standard implementation does not use
-   its *locals* argument at all, and uses its *globals* only to determine the
-   package context of the :keyword:`import` statement.)
+   This function is invoked by the :keyword:`import` statement.  It can be
+   replaced (by importing the :mod:`builtins` module and assigning to
+   ``builtins.__import__``) in order to change semantics of the
+   :keyword:`import` statement, but nowadays it is usually simpler to use import
+   hooks (see :pep:`302`).  Direct use of :func:`__import__` is rare, except in
+   cases where you want to import a module whose name is only known at runtime.
+
+   The function imports the module *name*, potentially using the given *globals*
+   and *locals* to determine how to interpret the name in a package context.
+   The *fromlist* gives the names of objects or submodules that should be
+   imported from the module given by *name*.  The standard implementation does
+   not use its *locals* argument at all, and uses its *globals* only to
+   determine the package context of the :keyword:`import` statement.
+
+   *level* specifies whether to use absolute or relative imports.  The default
+   is ``-1`` which indicates both absolute and relative imports will be
+   attempted.  ``0`` means only perform absolute imports.  Positive values for
+   *level* indicate the number of parent directories to search relative to the
+   directory of the module calling :func:`__import__`.
 
    When the *name* variable is of the form ``package.module``, normally, the
    top-level package (the name up till the first dot) is returned, *not* the
    module named by *name*.  However, when a non-empty *fromlist* argument is
-   given, the module named by *name* is returned.  This is done for
-   compatibility with the :term:`bytecode` generated for the different kinds of import
-   statement; when using ``import spam.ham.eggs``, the top-level package
-   :mod:`spam` must be placed in the importing namespace, but when using ``from
-   spam.ham import eggs``, the ``spam.ham`` subpackage must be used to find the
-   ``eggs`` variable.  As a workaround for this behavior, use :func:`getattr` to
-   extract the desired components.  For example, you could define the following
-   helper::
-
-      def my_import(name):
-          mod = __import__(name)
-          components = name.split('.')
-          for comp in components[1:]:
-              mod = getattr(mod, comp)
-          return mod
-
-   *level* specifies whether to use absolute or relative imports. The default is
-   ``-1`` which indicates both absolute and relative imports will be attempted.
-   ``0`` means only perform absolute imports. Positive values for *level* indicate
-   the number of parent directories to search relative to the directory of the
-   module calling :func:`__import__`.
+   given, the module named by *name* is returned.
 
+   For example, the statement ``import spam`` results in bytecode resembling the
+   following code::
+   
+      spam = __import__('spam', globals(), locals(), [], -1)
+
+   The statement ``import spam.ham`` results in this call::
+
+      spam = __import__('spam.ham', globals(), locals(), [], -1)
+
+   Note how :func:`__import__` returns the toplevel module here because this is
+   the object that is bound to a name by the :keyword:`import` statement.
+
+   On the other hand, the statement ``from spam.ham import eggs, sausage as
+   saus`` results in ::
+
+      _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], -1)
+      eggs = _temp.eggs
+      saus = _temp.sausage
+
+   Here, the ``spam.ham`` module is returned from :func:`__import__`.  From this
+   object, the names to import are retrieved and assigned to their respective
+   names.
+
+   If you simply want to import a module (potentially within a package) by name,
+   you can get it from :data:`sys.modules`::
+
+      >>> import sys
+      >>> name = 'foo.bar.baz'
+      >>> __import__(name)
+      <module 'foo' from ...>
+      >>> baz = sys.modules[name]
+      >>> baz
+      <module 'foo.bar.baz' from ...>
 
 .. rubric:: Footnotes
 
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 588aef33f0..1e9611e364 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -21,8 +21,9 @@ was generated in the first place.
 The following functions are provided by this module.  Except when explicitly
 noted otherwise, all return values are floats.
 
-Number-theoretic and representation functions:
 
+Number-theoretic and representation functions
+---------------------------------------------
 
 .. function:: ceil(x)
 
@@ -110,8 +111,8 @@ Number-theoretic and representation functions:
 
 .. function:: modf(x)
 
-   Return the fractional and integer parts of *x*.  Both results carry the sign of
-   *x*, and both are floats.
+   Return the fractional and integer parts of *x*.  Both results carry the sign
+   of *x* and are floats.
 
 
 .. function:: trunc(x)
@@ -131,7 +132,9 @@ Python floats typically carry no more than 53 bits of precision (the same as the
 platform C double type), in which case any float *x* with ``abs(x) >= 2**52``
 necessarily has no fractional bits.
 
-Power and logarithmic functions:
+
+Power and logarithmic functions
+-------------------------------
 
 .. function:: exp(x)
 
@@ -169,7 +172,8 @@ Power and logarithmic functions:
 
    Return the square root of *x*.
 
-Trigonometric functions:
+Trigonometric functions
+-----------------------
 
 
 .. function:: acos(x)
@@ -217,7 +221,8 @@ Trigonometric functions:
 
    Return the tangent of *x* radians.
 
-Angular conversion:
+Angular conversion
+------------------
 
 
 .. function:: degrees(x)
@@ -229,7 +234,8 @@ Angular conversion:
 
    Converts angle *x* from degrees to radians.
 
-Hyperbolic functions:
+Hyperbolic functions
+--------------------
 
 
 .. function:: acosh(x)
@@ -262,9 +268,8 @@ Hyperbolic functions:
    Return the hyperbolic tangent of *x*.
 
 
-
-The module also defines two mathematical constants:
-
+Constants
+=========
 
 .. data:: pi
 
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 1ff77dbaa3..dbaa64e248 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -1436,13 +1436,13 @@ itself.  This means, for example, that one shared object can contain a second::
 
    Proxy objects are instances of subclasses of :class:`BaseProxy`.
 
-   .. method:: _call_method(methodname[, args[, kwds]])
+   .. method:: _callmethod(methodname[, args[, kwds]])
 
       Call and return the result of a method of the proxy's referent.
 
       If ``proxy`` is a proxy whose referent is ``obj`` then the expression ::
 
-         proxy._call_method(methodname, args, kwds)
+         proxy._callmethod(methodname, args, kwds)
 
       will evaluate the expression ::
 
@@ -1455,26 +1455,26 @@ itself.  This means, for example, that one shared object can contain a second::
       argument of :meth:`BaseManager.register`.
 
       If an exception is raised by the call, then then is re-raised by
-      :meth:`_call_method`.  If some other exception is raised in the manager's
+      :meth:`_callmethod`.  If some other exception is raised in the manager's
       process then this is converted into a :exc:`RemoteError` exception and is
-      raised by :meth:`_call_method`.
+      raised by :meth:`_callmethod`.
 
       Note in particular that an exception will be raised if *methodname* has
       not been *exposed*
 
-      An example of the usage of :meth:`_call_method`::
+      An example of the usage of :meth:`_callmethod`::
 
          >>> l = manager.list(range(10))
-         >>> l._call_method('__len__')
+         >>> l._callmethod('__len__')
          10
-         >>> l._call_method('__getslice__', (2, 7))   # equiv to `l[2:7]`
+         >>> l._callmethod('__getslice__', (2, 7))   # equiv to `l[2:7]`
          [2, 3, 4, 5, 6]
-         >>> l._call_method('__getitem__', (20,))     # equiv to `l[20]`
+         >>> l._callmethod('__getitem__', (20,))     # equiv to `l[20]`
          Traceback (most recent call last):
          ...
          IndexError: list index out of range
 
-   .. method:: _get_value()
+   .. method:: _getvalue()
 
       Return a copy of the referent.
 
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index 3d8b43c3ad..7989d332da 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -1625,36 +1625,33 @@ directly).
 Nevertheless, here's a stab at a callback for an option with variable
 arguments::
 
-   def vararg_callback(option, opt_str, value, parser):
-       assert value is None
-       done = 0
-       value = []
-       rargs = parser.rargs
-       while rargs:
-           arg = rargs[0]
-
-           # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f",
-           # etc.  Note that this also stops on "-3" or "-3.0", so if
-           # your option takes numeric values, you will need to handle
-           # this.
-           if ((arg[:2] == "--" and len(arg) > 2) or
-               (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):
-               break
-           else:
-               value.append(arg)
-               del rargs[0]
-
-       setattr(parser.values, option.dest, value)
+    def vararg_callback(option, opt_str, value, parser):
+        assert value is None
+        value = []
+
+        def floatable(str):
+            try:
+                float(str)
+                return True
+            except ValueError:
+                return False
+
+        for arg in parser.rargs:
+            # stop on --foo like options
+            if arg[:2] == "--" and len(arg) > 2:
+                break
+            # stop on -a, but not on -3 or -3.0
+            if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
+                break
+            value.append(arg)
+
+        del parser.rargs[:len(value)]
+        setattr(parser.values, option.dest, value))
 
    [...]
    parser.add_option("-c", "--callback", dest="vararg_attr",
                      action="callback", callback=vararg_callback)
 
-The main weakness with this particular implementation is that negative numbers
-in the arguments following ``"-c"`` will be interpreted as further options
-(probably causing an error), rather than as arguments to ``"-c"``.  Fixing this
-is left as an exercise for the reader.
-
 
 .. _optparse-extending-optparse:
 
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index ac52ce4b03..b332d9a5cf 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -139,7 +139,7 @@ copying and removal. For operations on individual files, see also the
    Recursively move a file or directory to another location.
 
    If the destination is on the current filesystem, then simply use rename.
-   Otherwise, copy src to the dst and then remove src.
+   Otherwise, copy src (with :func:`copy2`) to the dst and then remove src.
 
 
 .. exception:: Error
diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 901229110e..5033e0e2a9 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -52,10 +52,10 @@ The variables defined in the :mod:`signal` module are:
 
 .. data:: SIG_DFL
 
-   This is one of two standard signal handling options; it will simply perform the
-   default function for the signal.  For example, on most systems the default
-   action for :const:`SIGQUIT` is to dump core and exit, while the default action
-   for :const:`SIGCLD` is to simply ignore it.
+   This is one of two standard signal handling options; it will simply perform
+   the default function for the signal.  For example, on most systems the
+   default action for :const:`SIGQUIT` is to dump core and exit, while the
+   default action for :const:`SIGCHLD` is to simply ignore it.
 
 
 .. data:: SIG_IGN
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index a1eb6886b4..de00c491e7 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -442,7 +442,7 @@ Additional Methods on Integer Types
     Equivalent to::
 
         def bit_length(self):
-            s = bin(self)       # binary representation:  bin(-37) --> '-0b100101'
+            s = bin(x)          # binary representation:  bin(-37) --> '-0b100101'
             s = s.lstrip('-0b') # remove leading zeros and minus sign
             return len(s)       # len('100101') --> 6
 
diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index 98850eabf0..d9a19935a9 100644
--- a/Doc/whatsnew/2.6.rst
+++ b/Doc/whatsnew/2.6.rst
@@ -738,7 +738,7 @@ The formatting template uses curly brackets (`{`, `}`) as special characters::
 
 Curly brackets can be escaped by doubling them::
 
-     >>> format("Empty dict: {{}}")
+     >>> "Empty dict: {{}}".format()
      "Empty dict: {}"
 
 Field names can be integers indicating positional arguments, such as