Merged revisions…

Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line

  #6513: fix example code: warning categories are classes, not instances.
........
  r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line

  #6489: fix an ambiguity in getiterator() documentation.
........
  r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line

  remove docs for deprecated -p option
........
  r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line

  use bools
........
  r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line

  Fix arg types of et#.
........
  r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line

  Dont put "void" in signature for nullary functions.
........
  r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line

  #6571: add index entries for more operators.
........
  r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line

  #6593: fix link targets.
........
  r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line

  #6591: add reference to ioctl in fcntl module for platforms other than Windows.
........
  r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line

  Add a link to readline, and mention IPython and bpython.
........
  r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line

  Fix some markup and small factual glitches found by M. Markert.
........
  r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line

  Fix a few markup glitches.
........
  r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line

  Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better.
........

Doc/c-api/arg.rst

@@ -160,7 +160,7 @@ variable(s) whose address should be passed.
    In both cases, *\*buffer_length* is set to the length of the encoded data
    without the trailing NUL byte.
 
-``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
+``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
    Same as ``es#`` except that string objects are passed through without recoding
    them. Instead, the implementation assumes that the string object uses the
    encoding passed in as parameter.

Doc/c-api/float.rst

@@ -64,16 +64,16 @@ Floating Point Objects
    around the header file :file:`float.h`.
 
 
-.. cfunction:: double PyFloat_GetMax(void)
+.. cfunction:: double PyFloat_GetMax()
 
    Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`.
 
 
-.. cfunction:: double PyFloat_GetMin(void)
+.. cfunction:: double PyFloat_GetMin()
 
    Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`.
 
-.. cfunction:: int PyFloat_ClearFreeList(void)
+.. cfunction:: int PyFloat_ClearFreeList()
 
    Clear the float free list. Return the number of items that could not
    be freed.

Doc/c-api/method.rst

@@ -94,7 +94,7 @@ no longer available.
    Macro version of :cfunc:`PyMethod_Self` which avoids error checking.
 
 
-.. cfunction:: int PyMethod_ClearFreeList(void)
+.. cfunction:: int PyMethod_ClearFreeList()
 
    Clear the free list. Return the total number of freed items.
 

Doc/c-api/sys.rst

@@ -73,7 +73,7 @@ accessible to C code.  They all work with the current interpreter thread's
    case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
    on error.
 
-.. cfunction:: void PySys_ResetWarnOptions(void)
+.. cfunction:: void PySys_ResetWarnOptions()
 
    Reset :data:`sys.warnoptions` to an empty list.
 

Doc/c-api/tuple.rst

@@ -107,6 +107,6 @@ Tuple Objects
    raises :exc:`MemoryError` or :exc:`SystemError`.
 
 
-.. cfunction:: int PyTuple_ClearFreeList(void)
+.. cfunction:: int PyTuple_ClearFreeList()
 
    Clear the free list. Return the total number of freed items.

Doc/c-api/type.rst

@@ -33,7 +33,7 @@ Type Objects
    standard type object.  Return false in all other cases.
 
 
-.. cfunction:: unsigned int PyType_ClearCache(void)
+.. cfunction:: unsigned int PyType_ClearCache()
 
    Clear the internal lookup cache. Return the current version tag.
 

Doc/c-api/unicode.rst

@@ -84,10 +84,11 @@ access internal read-only data of Unicode objects:
    :ctype:`PyUnicodeObject` (not checked).
 
 
-.. cfunction:: int PyUnicode_ClearFreeList(void)
+.. cfunction:: int PyUnicode_ClearFreeList()
 
    Clear the free list. Return the total number of freed items.
 
+
 Unicode provides many different character properties. The most often needed ones
 are available through these macros which are mapped to C functions depending on
 the Python configuration.

Doc/library/2to3.rst

@@ -86,13 +86,6 @@ document could also be refactored with this option.
 The :option:`-v` option enables output of more information on the translation
 process.
 
-When the :option:`-p` is passed, the :2to3fixer:`print` fixer ``print`` as a
-function instead of a statement.  This is useful when ``from __future__ import
-print_function`` is being used.  If this option is not given, the print fixer
-will surround print calls in an extra set of parentheses because it cannot
-differentiate between the print statement with parentheses (such as ``print
-("a" + "b" + "c")``) and a true function call.
-
 
 .. _2to3-fixers:
 

Doc/library/gettext.rst

@@ -194,7 +194,7 @@ class can also install themselves in the built-in namespace as the function
    :func:`translation`.
 
    For the *names* parameter, please see the description of the translation
-   object's :meth:`install` method.
+   object's :meth:`~NullTranslations.install` method.
 
    As seen below, you usually mark the strings in your application that are
    candidates for translation, by wrapping them in a call to the :func:`_`

Doc/library/socket.rst

@@ -555,6 +555,8 @@ correspond to Unix system calls applicable to sockets.
    The :meth:`ioctl` method is a limited interface to the WSAIoctl system
    interface. Please refer to the MSDN documentation for more information.
 
+   On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl`
+   functions may be used; they accept a socket object as their first argument.
 
 .. method:: socket.listen(backlog)
 

Doc/library/stdtypes.rst

@@ -120,25 +120,24 @@ Notes:
 Comparisons
 ===========
 
-.. index:: pair: chaining; comparisons
-
-There are eight comparison operations in Python.  They all have the same
-priority (which is higher than that of the Boolean operations).  Comparisons can
-be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and
-y <= z``, except that *y* is evaluated only once (but in both cases *z* is not
-evaluated at all when ``x < y`` is found to be false).
-
 .. index::
+   pair: chaining; comparisons
    pair: operator; comparison
    operator: ==
    operator: <
-   operator: >
    operator: <=
+   operator: >
    operator: >=
    operator: !=
    operator: is
    operator: is not
 
+There are eight comparison operations in Python.  They all have the same
+priority (which is higher than that of the Boolean operations).  Comparisons can
+be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and
+y <= z``, except that *y* is evaluated only once (but in both cases *z* is not
+evaluated at all when ``x < y`` is found to be false).
+
 This table summarizes the comparison operations:
 
 +------------+-------------------------+
@@ -248,6 +247,13 @@ and imaginary parts.
    builtin: int
    builtin: float
    builtin: complex
+   operator: +
+   operator: -
+   operator: *
+   operator: /
+   operator: //
+   operator: %
+   operator: **
 
 Python fully supports mixed arithmetic: when a binary arithmetic operator has
 operands of different numeric types, the operand with the "narrower" type is
@@ -368,7 +374,15 @@ modules.
 Bit-string Operations on Integer Types
 --------------------------------------
 
-.. _bit-string-operations:
+.. index::
+   triple: operations on; integer; types
+   pair: bit-string; operations
+   pair: shifting; operations
+   pair: masking; operations
+   operator: ^
+   operator: &
+   operator: <<
+   operator: >>
 
 Integers support additional operations that make sense only for bit-strings.
 Negative numbers are treated as their 2's complement value (this assumes a
@@ -400,12 +414,6 @@ This table lists the bit-string operations sorted in ascending priority
 | ``~x``     | the bits of *x* inverted       |          |
 +------------+--------------------------------+----------+
 
-.. index::
-   triple: operations on; integer; types
-   pair: bit-string; operations
-   pair: shifting; operations
-   pair: masking; operations
-
 Notes:
 
 (1)

Doc/library/warnings.rst

@@ -206,7 +206,7 @@ check::
         fxn()
         # Verify some things
         assert len(w) == 1
-        assert isinstance(w[-1].category, DeprecationWarning)
+        assert issubclass(w[-1].category, DeprecationWarning)
         assert "deprecated" in str(w[-1].message)
 
 One can also cause all warnings to be exceptions by using ``error`` instead of

Doc/library/webbrowser.rst

@@ -46,14 +46,14 @@ The following exception is defined:
 The following functions are defined:
 
 
-.. function:: open(url[, new=0[, autoraise=1]])
+.. function:: open(url[, new=0[, autoraise=True]])
 
-   Display *url* using the default browser. If *new* is 0, the *url* is opened in
-   the same browser window if possible.  If *new* is 1, a new browser window is
-   opened if possible.  If *new* is 2, a new browser page ("tab") is opened if
-   possible.  If *autoraise* is true, the window is raised if possible (note that
-   under many window managers this will occur regardless of the setting of this
-   variable).
+   Display *url* using the default browser. If *new* is 0, the *url* is opened
+   in the same browser window if possible.  If *new* is 1, a new browser window
+   is opened if possible.  If *new* is 2, a new browser page ("tab") is opened
+   if possible.  If *autoraise* is ``True``, the window is raised if possible
+   (note that under many window managers this will occur regardless of the
+   setting of this variable).
 
    Note that on some platforms, trying to open a filename using this function,
    may work and start the operating system's associated program.  However, this
@@ -175,7 +175,7 @@ Browser controllers provide these methods which parallel three of the
 module-level convenience functions:
 
 
-.. method:: controller.open(url[, new[, autoraise=1]])
+.. method:: controller.open(url[, new[, autoraise=True]])
 
    Display *url* using the browser handled by this controller. If *new* is 1, a new
    browser window is opened if possible. If *new* is 2, a new browser page ("tab")

Doc/library/xml.etree.elementtree.rst

@@ -262,9 +262,9 @@ The following methods work on the element's children (subelements).
 .. method:: Element.getiterator([tag=None])
 
    Creates a tree iterator with the current element as the root.   The iterator
-   iterates over this element and all elements below it  that match the given tag.
-   If tag is ``None`` or ``'*'`` then all elements are iterated over. Returns an
-   iterable that provides element objects in document (depth first) order.
+   iterates over this element and all elements below it, in document (depth first)
+   order.  If *tag* is not ``None`` or ``'*'``, only elements whose tag equals
+   *tag* are returned from the iterator.
 
 
 .. method:: Element.insert(index, element)

Doc/tutorial/inputoutput.rst

@@ -130,16 +130,17 @@ Basic usage of the :meth:`str.format` method looks like this::
    We are the knights who say "Ni!"
 
 The brackets and characters within them (called format fields) are replaced with
-the objects passed into the format method.  The number in the brackets refers to
-the position of the object passed into the format method. ::
+the objects passed into the :meth:`~str.format` method.  The number in the
+brackets refers to the position of the object passed into the
+:meth:`~str.format` method. ::
 
    >>> print('{0} and {1}'.format('spam', 'eggs'))
    spam and eggs
    >>> print('{1} and {0}'.format('spam', 'eggs'))
    eggs and spam
 
-If keyword arguments are used in the format method, their values are referred to
-by using the name of the argument. ::
+If keyword arguments are used in the :meth:`~str.format` method, their values
+are referred to by using the name of the argument. ::
 
    >>> print('This {food} is {adjective}.'.format(
    ...       food='spam', adjective='absolutely horrible'))
@@ -160,7 +161,7 @@ truncates the Pi to three places after the decimal.
    The value of PI is approximately 3.142.
 
 Passing an integer after the ``':'`` will cause that field to be a minimum
-number of characters wide.  This is useful for making tables pretty.::
+number of characters wide.  This is useful for making tables pretty. ::
 
    >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
    >>> for name, phone in table.items():
@@ -181,7 +182,7 @@ square brackets ``'[]'`` to access the keys ::
    Jack: 4098; Sjoerd: 4127; Dcab: 8637678
 
 This could also be done by passing the table as keyword arguments with the '**'
-notation.::
+notation. ::
 
    >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
    >>> print('Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab: {Dcab:d}'.format(**table))
@@ -374,9 +375,9 @@ shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
     >>> f.closed
     True
 
-File objects have some additional methods, such as :meth:`isatty` and
-:meth:`truncate` which are less frequently used; consult the Library Reference
-for a complete guide to file objects.
+File objects have some additional methods, such as :meth:`~file.isatty` and
+:meth:`~file.truncate` which are less frequently used; consult the Library
+Reference for a complete guide to file objects.
 
 
 .. _tut-pickle:

Doc/tutorial/interactive.rst

@@ -6,8 +6,8 @@ Interactive Input Editing and History Substitution
 
 Some versions of the Python interpreter support editing of the current input
 line and history substitution, similar to facilities found in the Korn shell and
-the GNU Bash shell.  This is implemented using the *GNU Readline* library, which
-supports Emacs-style and vi-style editing.  This library has its own
+the GNU Bash shell.  This is implemented using the `GNU Readline`_ library,
+which supports Emacs-style and vi-style editing.  This library has its own
 documentation which I won't duplicate here; however, the basics are easily
 explained.  The interactive editing and history described here are optionally
 available in the Unix and Cygwin versions of the interpreter.
@@ -148,8 +148,8 @@ interpreter. ::
 
 .. _tut-commentary:
 
-Commentary
-==========
+Alternatives to the Interactive Interpreter
+===========================================
 
 This facility is an enormous step forward compared to earlier versions of the
 interpreter; however, some wishes are left: It would be nice if the proper
@@ -158,8 +158,12 @@ token is required next).  The completion mechanism might use the interpreter's
 symbol table.  A command to check (or even suggest) matching parentheses,
 quotes, etc., would also be useful.
 
-.. %
-   Do we mention IPython? DUBOIS
+One alternative enhanced interactive interpreter that has been around for quite
+some time is `IPython`_, which features tab completion, object exploration and
+advanced history management.  It can also be thoroughly customized and embedded
+into other applications.  Another similar enhanced interactive environment is
+`bpython`_.
+
 
 .. rubric:: Footnotes
 
@@ -167,3 +171,7 @@ quotes, etc., would also be useful.
    :envvar:`PYTHONSTARTUP` environment variable when you start an interactive
    interpreter.
 
+
+.. _GNU Readline: http://tiswww.case.edu/php/chet/readline/rltop.html
+.. _IPython: http://ipython.scipy.org/
+.. _bpython: http://www.bpython-interpreter.org/

Doc/tutorial/modules.rst

@@ -448,14 +448,14 @@ one would hope that this somehow goes out to the filesystem, finds which
 submodules are present in the package, and imports them all.  Unfortunately,
 this operation does not work very well on Windows platforms, where the
 filesystem does not always have accurate information about the case of a
-filename!  On these platforms, there is no guaranteed way to know whether a file
+filename.  On these platforms, there is no guaranteed way to know whether a file
 :file:`ECHO.PY` should be imported as a module :mod:`echo`, :mod:`Echo` or
 :mod:`ECHO`.  (For example, Windows 95 has the annoying practice of showing all
 file names with a capitalized first letter.)  The DOS 8+3 filename restriction
 adds another interesting problem for long module names.
 
 The only solution is for the package author to provide an explicit index of the
-package.  The import statement uses the following convention: if a package's
+package.  The :keyword:`import` statement uses the following convention: if a package's
 :file:`__init__.py` code defines a list named ``__all__``, it is taken to be the
 list of module names that should be imported when ``from package import *`` is
 encountered.  It is up to the package author to keep this list up-to-date when a
@@ -476,16 +476,16 @@ been imported (possibly running any initialization code in :file:`__init__.py`)
 and then imports whatever names are defined in the package.  This includes any
 names defined (and submodules explicitly loaded) by :file:`__init__.py`.  It
 also includes any submodules of the package that were explicitly loaded by
-previous import statements.  Consider this code::
+previous :keyword:`import` statements.  Consider this code::
 
    import sound.effects.echo
    import sound.effects.surround
    from sound.effects import *
 
-In this example, the echo and surround modules are imported in the current
-namespace because they are defined in the :mod:`sound.effects` package when the
-``from...import`` statement is executed.  (This also works when ``__all__`` is
-defined.)
+In this example, the :mod:`echo` and :mod:`surround` modules are imported in the
+current namespace because they are defined in the :mod:`sound.effects` package
+when the ``from...import`` statement is executed.  (This also works when
+``__all__`` is defined.)
 
 Note that in general the practice of importing ``*`` from a module or package is
 frowned upon, since it often causes poorly readable code. However, it is okay to
@@ -537,5 +537,6 @@ modules found in a package.
 .. rubric:: Footnotes
 
 .. [#] In fact function definitions are also 'statements' that are 'executed'; the
-   execution enters the function name in the module's global symbol table.
+   execution of a module-level function enters the function name in the module's
+   global symbol table.
 

Doc/tutorial/stdlib2.rst

@@ -347,12 +347,15 @@ Decimal Floating Point Arithmetic
 
 The :mod:`decimal` module offers a :class:`Decimal` datatype for decimal
 floating point arithmetic.  Compared to the built-in :class:`float`
-implementation of binary floating point, the new class is especially helpful for
-financial applications and other uses which require exact decimal
-representation, control over precision, control over rounding to meet legal or
-regulatory requirements, tracking of significant decimal places, or for
-applications where the user expects the results to match calculations done by
-hand.
+implementation of binary floating point, the class is especially helpful for
+
+* financial applications and other uses which require exact decimal
+  representation,
+* control over precision,
+* control over rounding to meet legal or regulatory requirements,
+* tracking of significant decimal places, or
+* applications where the user expects the results to match calculations done by
+  hand.
 
 For example, calculating a 5% tax on a 70 cent phone charge gives different
 results in decimal floating point and binary floating point. The difference