Merged revisions...

Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r74210 | georg.brandl | 2009-07-26 16:44:23 +0200 (So, 26 Jul 2009) | 1 line

  Move member descriptions inside the classes.
........
  r74239 | georg.brandl | 2009-07-28 20:55:32 +0200 (Di, 28 Jul 2009) | 1 line

  Clarify quote_plus() usage.
........
  r74252 | georg.brandl | 2009-07-29 18:06:31 +0200 (Mi, 29 Jul 2009) | 1 line

  #6593: fix link targets.
........
  r74253 | georg.brandl | 2009-07-29 18:09:17 +0200 (Mi, 29 Jul 2009) | 1 line

  #6591: add reference to ioctl in fcntl module for platforms other than Windows.
........
  r74256 | georg.brandl | 2009-07-29 18:32:30 +0200 (Mi, 29 Jul 2009) | 1 line

  #6336: Add nb_divide.
........
  r74258 | georg.brandl | 2009-07-29 18:57:05 +0200 (Mi, 29 Jul 2009) | 1 line

  Add a link to readline, and mention IPython and bpython.
........
  r74259 | georg.brandl | 2009-07-29 19:07:21 +0200 (Mi, 29 Jul 2009) | 1 line

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

  Fix a few markup glitches.
........
  r74261 | georg.brandl | 2009-07-29 19:50:25 +0200 (Mi, 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.
........
  r74332 | georg.brandl | 2009-08-06 19:23:21 +0200 (Do, 06 Aug 2009) | 1 line

  Fix punctuation and one copy-paste error.
........
  r74333 | georg.brandl | 2009-08-06 19:43:55 +0200 (Do, 06 Aug 2009) | 1 line

  #6658: fix two typos.
........
  r74404 | georg.brandl | 2009-08-13 14:05:52 +0200 (Do, 13 Aug 2009) | 1 line

  Use locale.format_string() for more than one specifier.
........
  r74411 | georg.brandl | 2009-08-13 14:57:25 +0200 (Do, 13 Aug 2009) | 2 lines

  Remove potentially confusing sentence in __mangling description.
........
  r74445 | vinay.sajip | 2009-08-14 13:33:54 +0200 (Fr, 14 Aug 2009) | 1 line

  Added versionchanged notices for optional 'delay' parameter to file handler classes.
........
  r74465 | vinay.sajip | 2009-08-16 01:23:12 +0200 (So, 16 Aug 2009) | 1 line

  Added section on logging to one file from multiple processes.
........
  r74467 | vinay.sajip | 2009-08-16 01:34:47 +0200 (So, 16 Aug 2009) | 1 line

  Refined section on logging to one file from multiple processes.
........
  r74488 | vinay.sajip | 2009-08-17 15:14:37 +0200 (Mo, 17 Aug 2009) | 1 line

  Further refined section on logging to one file from multiple processes.
........

Doc/c-api/buffer.rst

@@ -147,7 +147,7 @@ Buffer related functions
       kind of buffer the caller is prepared to deal with and therefore what
       kind of buffer the exporter is allowed to return.  The buffer interface
       allows for complicated memory sharing possibilities, but some caller may
-      not be able to handle all the complexibity but may want to see if the
+      not be able to handle all the complexity but may want to see if the
       exporter will let them take a simpler view to its memory.
 
       Some exporters may not be able to share memory in every possible way and
@@ -255,7 +255,7 @@ Buffer related functions
 
 .. cfunction:: void PyBuffer_Release(PyObject *obj, Py_buffer *view)
 
-   Release the buffer *view* over *obj*.  This shouldd be called when the buffer
+   Release the buffer *view* over *obj*.  This should be called when the buffer
    is no longer being used as it may free memory from it.
 
 

Doc/c-api/typeobj.rst

@@ -1160,6 +1160,7 @@ Number Object Structures
             binaryfunc nb_add;
             binaryfunc nb_subtract;
             binaryfunc nb_multiply;
+            binaryfunc nb_divide;
             binaryfunc nb_remainder;
             binaryfunc nb_divmod;
             ternaryfunc nb_power;

Doc/library/gettext.rst

@@ -208,10 +208,10 @@ the built-in namespace as the function :func:`_`.
    This installs the function :func:`_` in Python's builtins namespace, based on
    *domain*, *localedir*, and *codeset* which are passed to the function
    :func:`translation`.  The *unicode* flag is passed to the resulting translation
-   object's :meth:`install` method.
+   object's :meth:`~NullTranslations.install` method.
 
    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/logging.rst

@@ -1321,6 +1321,31 @@ When this script is run, the output should look something like this::
 
 The :class:`LoggerAdapter` class was not present in previous versions.
 
+.. _multiple-processes:
+
+Logging to a single file from multiple processes
+------------------------------------------------
+
+Although logging is thread-safe, and logging to a single file from multiple
+threads in a single process *is* supported, logging to a single file from
+*multiple processes* is *not* supported, because there is no standard way to
+serialize access to a single file across multiple processes in Python. If you
+need to log to a single file from multiple processes, the best way of doing
+this is to have all the processes log to a :class:`SocketHandler`, and have a
+separate process which implements a socket server which reads from the socket
+and logs to file. (If you prefer, you can dedicate one thread in one of the
+existing processes to perform this function.) The following section documents
+this approach in more detail and includes a working socket receiver which can
+be used as a starting point for you to adapt in your own applications.
+
+If you are using a recent version of Python which includes the
+:mod:`multiprocessing` module, you can write your own handler which uses the
+:class:`Lock` class from this module to serialize access to the file from
+your processes. The existing :class:`FileHandler` and subclasses do not make
+use of :mod:`multiprocessing` at present, though they may do so in the future.
+Note that at present, the :mod:`multiprocessing` module does not provide
+working lock functionality on all platforms (see
+http://bugs.python.org/issue3770).
 
 .. _network-logging:
 
@@ -1613,6 +1638,8 @@ sends logging output to a disk file.  It inherits the output functionality from
    with that encoding.  If *delay* is true, then file opening is deferred until the
    first call to :meth:`emit`. By default, the file grows indefinitely.
 
+   .. versionchanged:: 2.6
+      *delay* was added.
 
    .. method:: close()
 
@@ -1661,6 +1688,9 @@ this value.
    with that encoding.  If *delay* is true, then file opening is deferred until the
    first call to :meth:`emit`.  By default, the file grows indefinitely.
 
+   .. versionchanged:: 2.6
+      *delay* was added.
+
 
    .. method:: emit(record)
 
@@ -1698,6 +1728,8 @@ module, supports rotation of disk log files.
    :file:`app.log.1`, :file:`app.log.2`, etc.  exist, then they are renamed to
    :file:`app.log.2`, :file:`app.log.3` etc.  respectively.
 
+   .. versionchanged:: 2.6
+      *delay* was added.
 
    .. method:: doRollover()
 
@@ -1757,6 +1789,11 @@ timed intervals.
    one is deleted. The deletion logic uses the interval to determine which
    files to delete, so changing the interval may leave old files lying around.
 
+   If *delay* is true, then file opening is deferred until the first call to
+   :meth:`emit`.
+
+   .. versionchanged:: 2.6
+      *delay* was added.
 
    .. method:: doRollover()
 

Doc/library/select.rst

@@ -307,7 +307,7 @@ http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
 
 .. attribute:: kevent.filter
 
-   Name of the kernel filter
+   Name of the kernel filter.
 
    +---------------------------+---------------------------------------------+
    | Constant                  | Meaning                                     |
@@ -316,7 +316,7 @@ http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
    |                           | there is data available to read             |
    +---------------------------+---------------------------------------------+
    | :const:`KQ_FILTER_WRITE`  | Takes a descriptor and returns whenever     |
-   |                           | there is data available to read             |
+   |                           | there is data available to write            |
    +---------------------------+---------------------------------------------+
    | :const:`KQ_FILTER_AIO`    | AIO requests                                |
    +---------------------------+---------------------------------------------+
@@ -336,7 +336,7 @@ http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
 
 .. attribute:: kevent.flags
 
-   Filter action
+   Filter action.
 
    +---------------------------+---------------------------------------------+
    | Constant                  | Meaning                                     |
@@ -365,10 +365,9 @@ http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
 
 .. attribute:: kevent.fflags
 
-   Filter specific flags
-
+   Filter specific flags.
 
-   :const:`KQ_FILTER_READ` and  :const:`KQ_FILTER_WRITE` filter flags
+   :const:`KQ_FILTER_READ` and  :const:`KQ_FILTER_WRITE` filter flags:
 
    +----------------------------+--------------------------------------------+
    | Constant                   | Meaning                                    |
@@ -376,8 +375,7 @@ http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
    | :const:`KQ_NOTE_LOWAT`     | low water mark of a socket buffer          |
    +----------------------------+--------------------------------------------+
 
-
-   :const:`KQ_FILTER_VNODE` filter flags
+   :const:`KQ_FILTER_VNODE` filter flags:
 
    +----------------------------+--------------------------------------------+
    | Constant                   | Meaning                                    |
@@ -397,8 +395,7 @@ http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
    | :const:`KQ_NOTE_REVOKE`    | access to the file was revoked             |
    +----------------------------+--------------------------------------------+
 
-
-   :const:`KQ_FILTER_PROC` filter flags
+   :const:`KQ_FILTER_PROC` filter flags:
 
    +----------------------------+--------------------------------------------+
    | Constant                   | Meaning                                    |
@@ -421,7 +418,7 @@ http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
    | :const:`KQ_NOTE_TRACKERR`  | unable to attach to a child                |
    +----------------------------+--------------------------------------------+
 
-   :const:`KQ_FILTER_NETDEV` filter flags [not available on Mac OS X]
+   :const:`KQ_FILTER_NETDEV` filter flags (not available on Mac OS X):
 
    +----------------------------+--------------------------------------------+
    | Constant                   | Meaning                                    |
@@ -436,9 +433,9 @@ http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
 
 .. attribute:: kevent.data
 
-   Filter specific data
+   Filter specific data.
 
 
 .. attribute:: kevent.udata
 
-   User defined value
+   User defined value.

Doc/library/socket.rst

@@ -604,6 +604,9 @@ 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.
+
    .. versionadded:: 2.6
 
 

Doc/library/urllib.rst

@@ -215,8 +215,9 @@ Utility functions
 .. function:: quote_plus(string[, safe])
 
    Like :func:`quote`, but also replaces spaces by plus signs, as required for
-   quoting HTML form values.  Plus signs in the original string are escaped unless
-   they are included in *safe*.  It also does not have *safe* default to ``'/'``.
+   quoting HTML form values when building up a query string to go into a URL.
+   Plus signs in the original string are escaped unless they are included in
+   *safe*.  It also does not have *safe* default to ``'/'``.
 
 
 .. function:: unquote(string)

Doc/tutorial/inputoutput.rst

@@ -127,16 +127,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')
@@ -157,7 +158,7 @@ truncates 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():
@@ -178,7 +179,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)
@@ -356,9 +357,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,6 +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.
 
+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
 
@@ -165,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

@@ -446,14 +446,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
@@ -474,16 +474,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
@@ -546,5 +546,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

@@ -61,7 +61,7 @@ formatting numbers with group separators::
    >>> x = 1234567.8
    >>> locale.format("%d", x, grouping=True)
    '1,234,567'
-   >>> locale.format("%s%.*f", (conv['currency_symbol'],
+   >>> locale.format_string("%s%.*f", (conv['currency_symbol'],
    ...                      conv['frac_digits'], x), grouping=True)
    '$1,234,567.80'
 
@@ -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