Merged revisions 59703-59773 via svnmerge from

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

........
  r59704 | christian.heimes | 2008-01-04 04:15:05 +0100 (Fri, 04 Jan 2008) | 1 line

  Moved include "Python.h" in front of other imports to silence a warning.
........
  r59706 | raymond.hettinger | 2008-01-04 04:22:53 +0100 (Fri, 04 Jan 2008) | 10 lines

  Minor fix-ups to named tuples:

  * Make the _replace() method respect subclassing.

  * Using property() to make _fields read-only wasn't a good idea.
    It caused len(Point._fields) to fail.

  * Add note to _cast() about length checking and alternative with the star-operator.
........
  r59707 | jeffrey.yasskin | 2008-01-04 09:01:23 +0100 (Fri, 04 Jan 2008) | 3 lines

  Make math.{floor,ceil}({int,long}) return float again for backwards
  compatibility after r59671 made them return integral types.
........
  r59709 | christian.heimes | 2008-01-04 14:21:07 +0100 (Fri, 04 Jan 2008) | 1 line

  Bug #1713: posixpath.ismount() claims symlink to a mountpoint is a mountpoint.
........
  r59712 | lars.gustaebel | 2008-01-04 15:00:33 +0100 (Fri, 04 Jan 2008) | 5 lines

  Issue #1735: TarFile.extractall() now correctly sets
  directory permissions and times.

  (will backport to 2.5)
........
  r59714 | andrew.kuchling | 2008-01-04 15:47:17 +0100 (Fri, 04 Jan 2008) | 1 line

  Update links to bug/patch tracker
........
  r59716 | christian.heimes | 2008-01-04 16:23:30 +0100 (Fri, 04 Jan 2008) | 1 line

  Added interface to Windows' WSAIoctl and a simple example for a network sniffer.
........
  r59717 | christian.heimes | 2008-01-04 16:29:00 +0100 (Fri, 04 Jan 2008) | 1 line

  And here is the rest of Hirokazu Yamamoto's patch for VS6.0 support. Thanks Hiro!
........
  r59719 | christian.heimes | 2008-01-04 16:34:06 +0100 (Fri, 04 Jan 2008) | 1 line

  Reverted last transaction. It's the wrong branch.
........
  r59721 | christian.heimes | 2008-01-04 16:48:06 +0100 (Fri, 04 Jan 2008) | 1 line

  socket.ioctl is only available on Windows
........
  r59722 | andrew.kuchling | 2008-01-04 19:24:41 +0100 (Fri, 04 Jan 2008) | 1 line

  Fix markup
........
  r59723 | andrew.kuchling | 2008-01-04 19:25:05 +0100 (Fri, 04 Jan 2008) | 1 line

  Fix markup
........
  r59725 | guido.van.rossum | 2008-01-05 01:59:59 +0100 (Sat, 05 Jan 2008) | 3 lines

  Patch #1725 by Mark Dickinson, fixes incorrect conversion of -1e1000
  and adds errors for -0x.
........
  r59726 | guido.van.rossum | 2008-01-05 02:21:57 +0100 (Sat, 05 Jan 2008) | 2 lines

  Patch #1698 by Senthil: allow '@' in username when parsed by urlparse.py.
........
  r59727 | raymond.hettinger | 2008-01-05 02:35:43 +0100 (Sat, 05 Jan 2008) | 1 line

  Improve namedtuple's _cast() method with a docstring, new name, and error-checking.
........
  r59728 | raymond.hettinger | 2008-01-05 03:17:24 +0100 (Sat, 05 Jan 2008) | 1 line

  Add error-checking to namedtuple's _replace() method.
........
  r59730 | fred.drake | 2008-01-05 05:38:38 +0100 (Sat, 05 Jan 2008) | 2 lines

  clean up a comment
........
  r59731 | jeffrey.yasskin | 2008-01-05 09:47:13 +0100 (Sat, 05 Jan 2008) | 11 lines

  Continue rolling back pep-3141 changes that changed behavior from 2.5. This
  round included:
   * Revert round to its 2.6 behavior (half away from 0).
   * Because round, floor, and ceil always return float again, it's no
     longer necessary to have them delegate to __xxx___, so I've ripped
     that out of their implementations and the Real ABC. This also helps
     in implementing types that work in both 2.6 and 3.0: you return int
     from the __xxx__ methods, and let it get enabled by the version
     upgrade.
   * Make pow(-1, .5) raise a ValueError again.
........
  r59736 | andrew.kuchling | 2008-01-05 16:13:49 +0100 (Sat, 05 Jan 2008) | 1 line

  Fix comment typo
........
  r59738 | thomas.heller | 2008-01-05 18:15:44 +0100 (Sat, 05 Jan 2008) | 1 line

  Add myself.
........
  r59739 | georg.brandl | 2008-01-05 18:49:17 +0100 (Sat, 05 Jan 2008) | 2 lines

  Fix C++-style comment.
........
  r59742 | georg.brandl | 2008-01-05 20:28:16 +0100 (Sat, 05 Jan 2008) | 2 lines

  Remove with_statement future imports from 2.6 docs.
........
  r59743 | georg.brandl | 2008-01-05 20:29:45 +0100 (Sat, 05 Jan 2008) | 2 lines

  Simplify index entries; fix #1712.
........
  r59744 | georg.brandl | 2008-01-05 20:44:22 +0100 (Sat, 05 Jan 2008) | 2 lines

  Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
........
  r59749 | georg.brandl | 2008-01-05 21:29:13 +0100 (Sat, 05 Jan 2008) | 2 lines

  Revert socket.rst to unix-eol.
........
  r59750 | georg.brandl | 2008-01-05 21:33:46 +0100 (Sat, 05 Jan 2008) | 2 lines

  Set native svn:eol-style property for text files.
........
  r59752 | georg.brandl | 2008-01-05 21:46:29 +0100 (Sat, 05 Jan 2008) | 2 lines

  #1719: capitalization error in "UuidCreate".
........
  r59753 | georg.brandl | 2008-01-05 22:02:25 +0100 (Sat, 05 Jan 2008) | 2 lines

  Repair markup.
........
  r59754 | georg.brandl | 2008-01-05 22:10:50 +0100 (Sat, 05 Jan 2008) | 2 lines

  Use markup.
........
  r59757 | christian.heimes | 2008-01-05 22:35:52 +0100 (Sat, 05 Jan 2008) | 1 line

  Final adjustments for #1601
........
  r59758 | guido.van.rossum | 2008-01-05 23:19:06 +0100 (Sat, 05 Jan 2008) | 3 lines

  Patch #1637: fix urlparse for URLs like 'http://x.com?arg=/foo'.
  Fix by John Nagle.
........
  r59759 | guido.van.rossum | 2008-01-05 23:20:01 +0100 (Sat, 05 Jan 2008) | 2 lines

  Add John Nagle (of issue #1637).
........
  r59765 | raymond.hettinger | 2008-01-06 10:02:24 +0100 (Sun, 06 Jan 2008) | 1 line

  Small code simplification.  Forgot that classmethods can be called from intances.
........
  r59766 | martin.v.loewis | 2008-01-06 11:09:48 +0100 (Sun, 06 Jan 2008) | 2 lines

  Use vcbuild for VS 2009.
........
  r59767 | martin.v.loewis | 2008-01-06 12:03:43 +0100 (Sun, 06 Jan 2008) | 2 lines

  Package using VS 2008.
........
  r59768 | martin.v.loewis | 2008-01-06 12:13:16 +0100 (Sun, 06 Jan 2008) | 2 lines

  Don't try to package msvcr90 for the moment.
........
  r59769 | georg.brandl | 2008-01-06 15:17:36 +0100 (Sun, 06 Jan 2008) | 4 lines

  #1696393: don't check for '.' and '..' in ntpath.walk since
  they aren't returned from os.listdir anymore.
  Reported by Michael Haggerty.
........
  r59770 | georg.brandl | 2008-01-06 15:27:15 +0100 (Sun, 06 Jan 2008) | 3 lines

  #1742: don't raise exception on os.path.relpath("a", "a"), but return os.curdir.
  Reported by Jesse Towner.
........
  r59771 | georg.brandl | 2008-01-06 15:33:52 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1591: Clarify docstring of Popen3.
........
  r59772 | georg.brandl | 2008-01-06 16:30:34 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1680: fix context manager example function name.
........
  r59773 | georg.brandl | 2008-01-06 16:34:57 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1755097: document default values for [].sort() and sorted().
........

4 files changed, 108 insertions, 62 deletions

diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index 927930a..ffd7423 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -78,7 +78,10 @@ on a separate line for clarity.
 The :keyword:`if` statement
 ===========================
 
-.. index:: statement: if
+.. index::
+   statement: if
+   keyword: elif
+   keyword: else
            keyword: elif
            keyword: else
 
@@ -105,6 +108,7 @@ The :keyword:`while` statement
    statement: while
    keyword: else
    pair: loop; statement
+   keyword: else
 
 The :keyword:`while` statement is used for repeated execution as long as an
 expression is true:
@@ -139,6 +143,9 @@ The :keyword:`for` statement
    keyword: else
    pair: target; list
    pair: loop; statement
+   keyword: in
+   keyword: else
+   pair: target; list
    object: sequence
 
 The :keyword:`for` statement is used to iterate over the elements of a sequence
@@ -208,7 +215,10 @@ returns the list ``[0, 1, 2]``.
 The :keyword:`try` statement
 ============================
 
-.. index:: statement: try
+.. index::
+   statement: try
+   keyword: except
+   keyword: finally
 .. index:: keyword: except
 
 The :keyword:`try` statement specifies exception handlers and/or cleanup code
@@ -223,7 +233,8 @@ for a group of statements:
    try2_stmt: "try" ":" `suite`
             : "finally" ":" `suite`
 
-The :keyword:`except` clause(s) specify one or more exception handlers.  When no
+
+The :keyword:`except` clause(s) specify one or more exception handlers. When no
 exception occurs in the :keyword:`try` clause, no exception handler is executed.
 When an exception occurs in the :keyword:`try` suite, a search for an exception
 handler is started.  This search inspects the except clauses in turn until one
@@ -379,6 +390,10 @@ The execution of the :keyword:`with` statement proceeds as follows:
    location for the kind of exit that was taken.
 
 
+   In Python 2.5, the :keyword:`with` statement is only allowed when the
+   ``with_statement`` feature has been enabled.  It is always enabled in
+   Python 2.6.
+
 .. seealso::
 
    :pep:`0343` - The "with" statement
@@ -393,8 +408,10 @@ Function definitions
 ====================
 
 .. index::
-   pair: function; definition
    statement: def
+   pair: function; definition
+   pair: function; name
+   pair: name; binding
    object: user-defined function
    object: function
    pair: function; name
@@ -513,13 +530,13 @@ Class definitions
 =================
 
 .. index::
-   pair: class; definition
-   statement: class
    object: class
-   single: inheritance
+   statement: class
+   pair: class; definition
    pair: class; name
    pair: name; binding
    pair: execution; frame
+   single: inheritance
 
 A class definition defines a class object (see section :ref:`types`):
 
@@ -554,13 +571,13 @@ is equivalent to ::
    Foo = f1(arg)(f2(Foo))
 
 **Programmer's note:** Variables defined in the class definition are class
-variables; they are shared by all instances.  To define instance variables, they
-must be given a value in the :meth:`__init__` method or in another method.  Both
-class and instance variables are accessible through the notation
-"``self.name``", and an instance variable hides a class variable with the same
-name when accessed in this way.  Class variables with immutable values can be
-used as defaults for instance variables.  Descriptors can be used to create
-instance variables with different implementation details.
+can be set in a method with ``self.name = value``.  Both class and instance
+variables are accessible through the notation "``self.name``", and an instance
+variable hides a class variable with the same name when accessed in this way.
+Class variables can be used as defaults for instance variables, but using
+mutable values there can lead to unexpected results.  For :term:`new-style
+class`\es, descriptors can be used to create instance variables with different
+implementation details.
 
 .. XXX add link to descriptor docs above
 
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 3c7f8e6..6acd25a 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1011,16 +1011,17 @@ implemented before for compatibility concerns, like the method resolution order
 in case of multiple inheritance.
 
 This manual is not up-to-date with respect to new-style classes.  For now,
-please see http://www.python.org/doc/newstyle.html for more information.
+please see http://www.python.org/doc/newstyle/ for more information.
 
 .. index::
-   single: class
-   single: class
-   single: class
+   single: class; new-style
+   single: class; classic
+   single: class; old-style
 
 The plan is to eventually drop old-style classes, leaving only the semantics of
 new-style classes.  This change will probably only be feasible in Python 3.0.
-new-style classic old-style
+
+XXX Remove old style classes from docs
 
 
 .. _specialnames:
@@ -1902,6 +1903,18 @@ For more information on context managers, see :ref:`typecontextmanager`.
 
 .. rubric:: Footnotes
 
+.. [#] Since Python 2.2, a gradual merging of types and classes has been started that
+   makes this and a few other assertions made in this manual not 100% accurate and
+   complete: for example, it *is* now possible in some cases to change an object's
+   type, under certain controlled conditions.  Until this manual undergoes
+   extensive revision, it must now be taken as authoritative only regarding
+   "classic classes", that are still the default, for compatibility purposes, in
+   Python 2.2 and 2.3.  For more information, see
+   http://www.python.org/doc/newstyle/.
+
+.. [#] This, and other statements, are only roughly true for instances of new-style
+   classes.
+
 .. [#] A descriptor can define any combination of :meth:`__get__`,
    :meth:`__set__` and :meth:`__delete__`.  If it does not define :meth:`__get__`,
    then accessing the attribute even on an instance will return the descriptor
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index cf95636..380d265 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -769,7 +769,7 @@ float result is delivered. For example, ``10**2`` returns ``100``, but
 
 Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`.
 Raising a negative number to a fractional power results in a :class:`complex`
-number. (Since Python 2.6. In earlier versions it raised a :exc:`ValueError`.)
+number. (In earlier versions it raised a :exc:`ValueError`.)
 
 
 .. _unary:
@@ -779,9 +779,9 @@ Unary arithmetic operations
 
 .. index::
    triple: unary; arithmetic; operation
-   triple: unary; bit-wise; operation
+   triple: unary; bitwise; operation
 
-All unary arithmetic (and bit-wise) operations have the same priority:
+All unary arithmetic (and bitwise) operations have the same priority:
 
 .. productionlist::
    u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr`
@@ -798,9 +798,10 @@ The unary ``+`` (plus) operator yields its numeric argument unchanged.
 
 .. index:: single: inversion
 
-The unary ``~`` (invert) operator yields the bit-wise inversion of its integer
-argument.  The bit-wise inversion of ``x`` is defined as ``-(x+1)``.  It only
-applies to integral numbers.
+
+The unary ``~`` (invert) operator yields the bitwise inversion of its plain or
+long integer argument.  The bitwise inversion of ``x`` is defined as
+``-(x+1)``.  It only applies to integral numbers.
 
 .. index:: exception: TypeError
 
@@ -905,10 +906,10 @@ by *n* bits is defined as multiplication with ``pow(2,n)``.
 
 .. _bitwise:
 
-Binary bit-wise operations
-==========================
+Binary bitwise operations
+=========================
 
-.. index:: triple: binary; bit-wise; operation
+.. index:: triple: binary; bitwise; operation
 
 Each of the three bitwise operations has a different priority level:
 
@@ -917,20 +918,20 @@ Each of the three bitwise operations has a different priority level:
    xor_expr: `and_expr` | `xor_expr` "^" `and_expr`
    or_expr: `xor_expr` | `or_expr` "|" `xor_expr`
 
-.. index:: pair: bit-wise; and
+.. index:: pair: bitwise; and
 
 The ``&`` operator yields the bitwise AND of its arguments, which must be
 integers.
 
 .. index::
-   pair: bit-wise; xor
+   pair: bitwise; xor
    pair: exclusive; or
 
 The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which
 must be integers.
 
 .. index::
-   pair: bit-wise; or
+   pair: bitwise; or
    pair: inclusive; or
 
 The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index a822006..1dc49f3 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -33,7 +33,9 @@ simple statements is:
 Expression statements
 =====================
 
-.. index:: pair: expression; statement
+.. index::
+   pair: expression; statement
+   pair: expression; list
 .. index:: pair: expression; list
 
 Expression statements are used (mostly interactively) to compute and write a
@@ -327,7 +329,9 @@ is determined when the interpreter starts.
 The :keyword:`pass` statement
 =============================
 
-.. index:: statement: pass
+.. index::
+   statement: pass
+   pair: null; operation
            pair: null; operation
 
 .. productionlist::
@@ -347,9 +351,10 @@ code needs to be executed, for example::
 The :keyword:`del` statement
 ============================
 
-.. index:: statement: del
-           pair: deletion; target
-           triple: deletion; target; list
+.. index::
+   statement: del
+   pair: deletion; target
+   triple: deletion; target; list
 
 .. productionlist::
    del_stmt: "del" `target_list`
@@ -386,9 +391,10 @@ the sliced object).
 The :keyword:`return` statement
 ===============================
 
-.. index:: statement: return
-           pair: function; definition
-           pair: class; definition
+.. index::
+   statement: return
+   pair: function; definition
+   pair: class; definition
 
 .. productionlist::
    return_stmt: "return" [`expression_list`]
@@ -418,23 +424,34 @@ raised.
 The :keyword:`yield` statement
 ==============================
 
+.. index::
+   statement: yield
+   single: generator; function
+   single: generator; iterator
+   single: function; generator
+   exception: StopIteration
+
 .. productionlist::
    yield_stmt: `yield_expression`
 
-The yield statement is nothing but a yield expression used as a statement,
-see :ref:`yieldexpr`.
-
+The :keyword:`yield` statement is only used when defining a generator function,
+and is only used in the body of the generator function. Using a :keyword:`yield`
+statement in a function definition is sufficient to cause that definition to
+create a generator function instead of a normal function.
+>>>>>>> .merge-right.r59773
 
 .. _raise:
 
 The :keyword:`raise` statement
 ==============================
 
-.. index:: statement: raise
-           pair: raising; exception
+.. index::
+   statement: raise
+   single: exception
+   pair: raising; exception
 
 .. productionlist::
-   raise_stmt: "raise" [`expression` ["from" `expression`]]
+   raise_stmt: "raise" [`expression` ["," `expression` ["," `expression`]]]
 
 If no expressions are present, :keyword:`raise` re-raises the last exception
 that was active in the current scope.  If no exception is active in the current
@@ -476,10 +493,11 @@ and information about handling exceptions is in section :ref:`try`.
 The :keyword:`break` statement
 ==============================
 
-.. index:: statement: break
-           statement: for
-           statement: while
-           pair: loop; statement
+.. index::
+   statement: break
+   statement: for
+   statement: while
+   pair: loop; statement
 
 .. productionlist::
    break_stmt: "break"
@@ -509,11 +527,12 @@ really leaving the loop.
 The :keyword:`continue` statement
 =================================
 
-.. index:: statement: continue
-           statement: for
-           statement: while
-           pair: loop; statement
-           keyword: finally
+.. index::
+   statement: continue
+   statement: for
+   statement: while
+   pair: loop; statement
+   keyword: finally
 
 .. productionlist::
    continue_stmt: "continue"
@@ -631,6 +650,7 @@ raise a :exc:`SyntaxError`.
 
 .. index::
    keyword: from
+   statement: from
    triple: hierarchical; module; names
    single: packages
    single: __init__.py
@@ -731,13 +751,13 @@ after the script is executed.
 The :keyword:`global` statement
 ===============================
 
-.. index:: statement: global
+.. index::
+   statement: global
+   triple: global; name; binding
 
 .. productionlist::
    global_stmt: "global" `identifier` ("," `identifier`)*
 
-.. index:: triple: global; name; binding
-
 The :keyword:`global` statement is a declaration which holds for the entire
 current code block.  It means that the listed identifiers are to be interpreted
 as globals.  It would be impossible to assign to a global variable without
@@ -789,11 +809,6 @@ because the default behavior for binding is to search the local namespace
 first.  The statement allows encapsulated code to rebind variables outside of
 the local scope besides the global (module) scope.
 
-.. note::
-
-   The outer scope for :keyword:`nonlocal` statements cannot be the module
-   scope.
-
 .. XXX not implemented
    The :keyword:`nonlocal` statement may prepend an assignment or augmented
    assignment, but not an expression.