Merged revisions 80030,80067,80069,80080-80081,80084,80432-80433,80465-80470,81059,81065-81067 via svnmerge from

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

........
  r80030 | georg.brandl | 2010-04-13 08:43:54 +0200 (Di, 13 Apr 2010) | 1 line

  Get rid of multi-row cells.
........
  r80067 | georg.brandl | 2010-04-14 10:53:38 +0200 (Mi, 14 Apr 2010) | 1 line

  #5341: typo.
........
  r80069 | georg.brandl | 2010-04-14 15:50:31 +0200 (Mi, 14 Apr 2010) | 1 line

  Add an x-ref to where the O_ constants are documented and move the SEEK_ constants after lseek().
........
  r80080 | georg.brandl | 2010-04-14 21:16:38 +0200 (Mi, 14 Apr 2010) | 1 line

  #8399: add note about Windows and O_BINARY.
........
  r80081 | georg.brandl | 2010-04-14 23:34:44 +0200 (Mi, 14 Apr 2010) | 1 line

  #5250: document __instancecheck__ and __subclasscheck__.  I hope the part about the class/metaclass distinction is understandable.
........
  r80084 | georg.brandl | 2010-04-14 23:46:45 +0200 (Mi, 14 Apr 2010) | 1 line

  Fix missing.
........
  r80432 | georg.brandl | 2010-04-24 10:56:58 +0200 (Sa, 24 Apr 2010) | 1 line

  Markup fixes.
........
  r80433 | georg.brandl | 2010-04-24 11:08:10 +0200 (Sa, 24 Apr 2010) | 1 line

  #7507: quote "!" in pipes.quote(); it is a special character for some shells.
........
  r80465 | georg.brandl | 2010-04-25 12:29:17 +0200 (So, 25 Apr 2010) | 1 line

  Remove LaTeXy index entry syntax.
........
  r80466 | georg.brandl | 2010-04-25 12:54:42 +0200 (So, 25 Apr 2010) | 1 line

  Patch from Tim Hatch: Better cross-referencing in socket and winreg docs.
........
  r80467 | georg.brandl | 2010-04-25 12:55:16 +0200 (So, 25 Apr 2010) | 1 line

  Patch from Tim Hatch: Remove reference to winreg being the fabled high-level registry interface.
........
  r80468 | georg.brandl | 2010-04-25 12:55:58 +0200 (So, 25 Apr 2010) | 1 line

  Patch from Tim Hatch: Minor spelling changes to _winreg docs.
........
  r80469 | georg.brandl | 2010-04-25 12:56:41 +0200 (So, 25 Apr 2010) | 1 line

  Fix code example to have valid syntax so that it can be highlighted.
........
  r80470 | georg.brandl | 2010-04-25 12:57:15 +0200 (So, 25 Apr 2010) | 1 line

  Patch from Tim Hatch: Make socket setblocking <-> settimeout examples symmetric.
........
  r81059 | georg.brandl | 2010-05-10 23:02:51 +0200 (Mo, 10 Mai 2010) | 1 line

  #8642: fix wrong function name.
........
  r81065 | georg.brandl | 2010-05-10 23:46:50 +0200 (Mo, 10 Mai 2010) | 1 line

  Fix reference direction.
........
  r81066 | georg.brandl | 2010-05-10 23:50:57 +0200 (Mo, 10 Mai 2010) | 1 line

  Consolidate deprecation messages.
........
  r81067 | georg.brandl | 2010-05-10 23:51:33 +0200 (Mo, 10 Mai 2010) | 1 line

  Fix typo.
........

12 files changed, 138 insertions, 95 deletions

diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst
index aaff852..e21c1ed 100644
--- a/Doc/library/fcntl.rst
+++ b/Doc/library/fcntl.rst
@@ -8,8 +8,8 @@
 
 
 .. index::
-   pair: UNIX@Unix; file control
-   pair: UNIX@Unix; I/O control
+   pair: UNIX; file control
+   pair: UNIX; I/O control
 
 This module performs file control and I/O control on file descriptors. It is an
 interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.
diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index 857f413..35e9ce2 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -122,7 +122,7 @@ The module defines the following items:
    The set of all exceptions (as a tuple) that methods of :class:`FTP`
    instances may raise as a result of problems with the FTP connection (as
    opposed to programming errors made by the caller).  This set includes the
-   four exceptions listed below as well as :exc:`socket.error` and
+   four exceptions listed above as well as :exc:`socket.error` and
    :exc:`IOError`.
 
 .. seealso::
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 451b33f..24db64a 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -240,7 +240,7 @@ I/O Base Classes
 
       Flush and close this stream. This method has no effect if the file is
       already closed. Once the file is closed, any operation on the file
-      (e.g. reading or writing) will raise an :exc:`ValueError`.
+      (e.g. reading or writing) will raise a :exc:`ValueError`.
 
       As a convenience, it is allowed to call this method more than once;
       only the first call, however, will have an effect.
diff --git a/Doc/library/json.rst b/Doc/library/json.rst
index 6ad95b2..e1f5cf2 100644
--- a/Doc/library/json.rst
+++ b/Doc/library/json.rst
@@ -209,7 +209,7 @@ Basic Usage
    specified.  Encodings that are not ASCII based (such as UCS-2) are not
    allowed and should be decoded to :class:`str` first.
 
-   The other arguments have the same meaning as in :func:`dump`.
+   The other arguments have the same meaning as in :func:`load`.
 
 
 Encoders and decoders
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 7b37629..eb48bf1 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -697,6 +697,14 @@ as internal buffering of data.
    Availability: Unix, Windows.
 
 
+.. data:: SEEK_SET
+          SEEK_CUR
+          SEEK_END
+
+   Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
+   respectively. Availability: Windows, Unix.
+
+
 .. function:: open(file, flags[, mode])
 
    Open the file *file* and set various flags according to *flags* and possibly
@@ -706,7 +714,8 @@ as internal buffering of data.
 
    For a description of the flag and mode values, see the C run-time documentation;
    flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
-   this module too (see below).
+   this module too (see :ref:`open-constants`).  In particular, on Windows adding
+   :const:`O_BINARY` is needed to open files in binary mode.
 
    Availability: Unix, Windows.
 
@@ -794,6 +803,12 @@ as internal buffering of data.
       :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
       :meth:`~file.write` method.
 
+
+.. _open-constants:
+
+``open()`` flag constants
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The following constants are options for the *flags* parameter to the
 :func:`~os.open` function.  They can be combined using the bitwise OR operator
 ``|``.  Some of them are not available on all platforms.  For descriptions of
@@ -845,14 +860,6 @@ or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Window
    the C library.
 
 
-.. data:: SEEK_SET
-          SEEK_CUR
-          SEEK_END
-
-   Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
-   respectively. Availability: Windows, Unix.
-
-
 .. _os-file-dir:
 
 Files and Directories
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index e73aefb..0e91278 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -89,8 +89,9 @@ All errors raise exceptions.  The normal exceptions for invalid argument types
 and out-of-memory conditions can be raised; errors related to socket or address
 semantics raise the error :exc:`socket.error`.
 
-Non-blocking mode is supported through :meth:`setblocking`.  A generalization of
-this based on timeouts is supported through :meth:`settimeout`.
+Non-blocking mode is supported through :meth:`~socket.setblocking`.  A
+generalization of this based on timeouts is supported through
+:meth:`~socket.settimeout`.
 
 The module :mod:`socket` exports the following constants and functions:
 
@@ -559,7 +560,9 @@ correspond to Unix system calls applicable to sockets.
    :platform: Windows
 
    The :meth:`ioctl` method is a limited interface to the WSAIoctl system
-   interface. Please refer to the MSDN documentation for more information.
+   interface.  Please refer to the `Win32 documentation
+   <http://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ 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.
@@ -662,7 +665,7 @@ correspond to Unix system calls applicable to sockets.
    blocking mode.  In non-blocking mode, if a :meth:`recv` call doesn't find any
    data, or if a :meth:`send` call can't immediately dispose of the data, a
    :exc:`error` exception is raised; in blocking mode, the calls block until they
-   can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0)``;
+   can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0.0)``;
    ``s.setblocking(1)`` is equivalent to ``s.settimeout(None)``.
 
 
@@ -691,21 +694,21 @@ the system returns an error (such as connection timed out).  In
 non-blocking mode, operations fail (with an error that is unfortunately
 system-dependent) if they cannot be completed immediately.  In timeout mode,
 operations fail if they cannot be completed within the timeout specified for the
-socket or if the system returns an error.  The :meth:`setblocking` method is simply
-a shorthand for certain :meth:`settimeout` calls.
+socket or if the system returns an error.  The :meth:`~socket.setblocking`
+method is simply a shorthand for certain :meth:`~socket.settimeout` calls.
 
 Timeout mode internally sets the socket in non-blocking mode.  The blocking and
 timeout modes are shared between file descriptors and socket objects that refer
 to the same network endpoint.  A consequence of this is that file objects
-returned by the :meth:`makefile` method must only be used when the socket is in
-blocking mode; in timeout or non-blocking mode file operations that cannot be
-completed immediately will fail.
+returned by the :meth:`~socket.makefile` method must only be used when the
+socket is in blocking mode; in timeout or non-blocking mode file operations
+that cannot be completed immediately will fail.
 
-Note that the :meth:`connect` operation is subject to the timeout setting, and
-in general it is recommended to call :meth:`settimeout` before calling
-:meth:`connect` or pass a timeout parameter to :meth:`create_connection`.
-The system network stack may return a connection timeout error
-of its own regardless of any Python socket timeout setting.
+Note that the :meth:`~socket.connect` operation is subject to the timeout
+setting, and in general it is recommended to call :meth:`~socket.settimeout`
+before calling :meth:`~socket.connect` or pass a timeout parameter to
+:meth:`create_connection`.  The system network stack may return a connection
+timeout error of its own regardless of any Python socket timeout setting.
 
 
 .. method:: socket.setsockopt(level, optname, value)
@@ -727,8 +730,8 @@ of its own regardless of any Python socket timeout setting.
    are disallowed.  If *how* is :const:`SHUT_RDWR`, further sends and receives are
    disallowed.
 
-Note that there are no methods :meth:`read` or :meth:`write`; use :meth:`recv`
-and :meth:`send` without *flags* argument instead.
+Note that there are no methods :meth:`read` or :meth:`write`; use
+:meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead.
 
 Socket objects also have these (read-only) attributes that correspond to the
 values given to the :class:`socket` constructor.
@@ -757,11 +760,12 @@ Example
 Here are four minimal example programs using the TCP/IP protocol: a server that
 echoes all data that it receives back (servicing only one client), and a client
 using it.  Note that a server must perform the sequence :func:`socket`,
-:meth:`bind`, :meth:`listen`, :meth:`accept` (possibly repeating the
-:meth:`accept` to service more than one client), while a client only needs the
-sequence :func:`socket`, :meth:`connect`.  Also note that the server does not
-:meth:`send`/:meth:`recv` on the  socket it is listening on but on the new
-socket returned by :meth:`accept`.
+:meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly
+repeating the :meth:`~socket.accept` to service more than one client), while a
+client only needs the sequence :func:`socket`, :meth:`~socket.connect`.  Also
+note that the server does not :meth:`~socket.send`/:meth:`~socket.recv` on the
+socket it is listening on but on the new socket returned by
+:meth:`~socket.accept`.
 
 The first two examples support IPv4 only. ::
 
diff --git a/Doc/library/syslog.rst b/Doc/library/syslog.rst
index c25ed41..a3b374a 100644
--- a/Doc/library/syslog.rst
+++ b/Doc/library/syslog.rst
@@ -10,66 +10,63 @@ This module provides an interface to the Unix ``syslog`` library routines.
 Refer to the Unix manual pages for a detailed description of the ``syslog``
 facility.
 
-This module wraps the system ``syslog`` module.  A pure Python
-library that can speak to a syslog server is available in
-the :mod:`logging.handlers` module as :class:`SysLogHandler`.
+This module wraps the system ``syslog`` family of routines.  A pure Python
+library that can speak to a syslog server is available in the
+:mod:`logging.handlers` module as :class:`SysLogHandler`.
 
 The module defines the following functions:
 
 
 .. function:: syslog([priority,] message)
 
-   Send the string *message* to the system logger.  A trailing newline is
-   added if necessary.  Each message is tagged with a priority composed
-   of a *facility* and a *level*.  The optional *priority* argument, which
-   defaults to :const:`LOG_INFO`, determines the message priority.  If the
-   facility is not encoded in *priority* using logical-or (``LOG_INFO |
-   LOG_USER``), the value given in the :func:`openlog` call is used.
+   Send the string *message* to the system logger.  A trailing newline is added
+   if necessary.  Each message is tagged with a priority composed of a
+   *facility* and a *level*.  The optional *priority* argument, which defaults
+   to :const:`LOG_INFO`, determines the message priority.  If the facility is
+   not encoded in *priority* using logical-or (``LOG_INFO | LOG_USER``), the
+   value given in the :func:`openlog` call is used.
 
-   If :func:`openlog` has not been called prior to the call to
-   :func:'syslog', ``openlog()`` will be called with no arguments.
+   If :func:`openlog` has not been called prior to the call to :func:`syslog`,
+   ``openlog()`` will be called with no arguments.
 
 
 .. function:: openlog([ident[, logopt[, facility]]])
 
-   Logging options of subsequent :func:`syslog` calls can be set by
-   calling :func:`openlog`.  :func:`syslog` will call :func:`openlog`
-   with no arguments if the log is not currently open.
+   Logging options of subsequent :func:`syslog` calls can be set by calling
+   :func:`openlog`.  :func:`syslog` will call :func:`openlog` with no arguments
+   if the log is not currently open.
 
-   The optional *ident* keyword argument is a string which is prepended
-   to every message, and defaults to ''sys.argv[0]'' with leading
-   path components stripped.  The optional *logopt* keyword argument
-   (default=0) is a bit field - see below for possible values to combine.
-   The optional *facility* keyword argument (default=:const:`LOG_USER`)
-   sets the default facility for messages which do not have a facility
-   explicitly encoded.
+   The optional *ident* keyword argument is a string which is prepended to every
+   message, and defaults to ``sys.argv[0]`` with leading path components
+   stripped.  The optional *logopt* keyword argument (default is 0) is a bit
+   field -- see below for possible values to combine.  The optional *facility*
+   keyword argument (default is :const:`LOG_USER`) sets the default facility for
+   messages which do not have a facility explicitly encoded.
 
-   .. versionchanged::3.2
-      In previous versions, keyword arguments were not allowed, and *ident*
-      was required.  The default for *ident* was dependent on the system
-      libraries, and often was ''python'' instead of the name of the
-      python program file.
+   .. versionchanged:: 3.2
+      In previous versions, keyword arguments were not allowed, and *ident* was
+      required.  The default for *ident* was dependent on the system libraries,
+      and often was ``python`` instead of the name of the python program file.
 
 
 .. function:: closelog()
 
-   Reset the syslog module values and call the system library
-   ''closelog()''.
+   Reset the syslog module values and call the system library ``closelog()``.
 
-   This causes the module to behave as it does when initially imported.
-   For example, :func:'openlog' will be called on the first :func:'syslog'
-   call (if :func:'openlog' hasn't already been called), and *ident*
-   and other :func:'openlog' parameters are reset to defaults.
+   This causes the module to behave as it does when initially imported.  For
+   example, :func:`openlog` will be called on the first :func:`syslog` call (if
+   :func:`openlog` hasn't already been called), and *ident* and other
+   :func:`openlog` parameters are reset to defaults.
 
 
 .. function:: setlogmask(maskpri)
 
-   Set the priority mask to *maskpri* and return the previous mask value.
-   Calls to :func:`syslog` with a priority level not set in *maskpri*
-   are ignored.  The default is to log all priorities.  The function
-   ``LOG_MASK(pri)`` calculates the mask for the individual priority
-   *pri*.  The function ``LOG_UPTO(pri)`` calculates the mask for all
-   priorities up to and including *pri*.
+   Set the priority mask to *maskpri* and return the previous mask value.  Calls
+   to :func:`syslog` with a priority level not set in *maskpri* are ignored.
+   The default is to log all priorities.  The function ``LOG_MASK(pri)``
+   calculates the mask for the individual priority *pri*.  The function
+   ``LOG_UPTO(pri)`` calculates the mask for all priorities up to and including
+   *pri*.
 
 The module defines the following constants:
 
@@ -100,11 +97,11 @@ A simple set of examples::
 
    syslog.syslog('Processing started')
    if error:
-      syslog.syslog(syslog.LOG_ERR, 'Processing started')
+       syslog.syslog(syslog.LOG_ERR, 'Processing started')
 
-An example of setting some log options, these would include the process ID
-in logged messages, and write the messages to the destination facility
-used for mail logging::
+An example of setting some log options, these would include the process ID in
+logged messages, and write the messages to the destination facility used for
+mail logging::
 
    syslog.openlog(logopt=syslog.LOG_PID, facility=syslog.LOG_MAIL)
    syslog.syslog('E-mail processing initiated...')
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index edf0ebf..1cb4124 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -773,8 +773,7 @@ Test cases
       will be *msg* if given, otherwise it will be :const:`None`.
 
       .. deprecated:: 3.1
-         :meth:`failUnless`; use one of the ``assert`` variants.
-         :meth:`assert_`; use :meth:`assertTrue`.
+         :meth:`failUnless` and :meth:`assert_`; use :meth:`assertTrue`.
 
 
    .. method:: assertEqual(first, second, msg=None)
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 5af615d..06aa0f9 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1587,6 +1587,46 @@ the new type and it saves the ordered dictionary keys in an attribute
 called *members*.
 
 
+Customizing instance and subclass checks
+----------------------------------------
+
+The following methods are used to override the default behavior of the
+:func:`isinstance` and :func:`issubclass` built-in functions.
+
+In particular, the metaclass :class:`abc.ABCMeta` implements these methods in
+order to allow the addition of Abstract Base Classes (ABCs) as "virtual base
+classes" to any class or type (including built-in types), and including to other
+ABCs.
+
+.. method:: class.__instancecheck__(self, instance)
+
+   Return true if *instance* should be considered a (direct or indirect)
+   instance of *class*. If defined, called to implement ``isinstance(instance,
+   class)``.
+
+
+.. method:: class.__subclasscheck__(self, subclass)
+
+   Return true if *subclass* should be considered a (direct or indirect)
+   subclass of *class*.  If defined, called to implement ``issubclass(subclass,
+   class)``.
+
+
+Note that these methods are looked up on the type (metaclass) of a class.  They
+cannot be defined as class methods in the actual class.  This is consistent with
+the lookup of special methods that are called on instances, only that in this
+case the instance is itself a class.
+
+.. seealso::
+
+   :pep:`3119` - Introducing Abstract Base Classes
+      Includes the specification for customizing :func:`isinstance` and
+      :func:`issubclass` behavior through :meth:`__instancecheck__` and
+      :meth:`__subclasscheck__`, with motivation for this functionality in the
+      context of adding Abstract Base Classes (see the :mod:`abc` module) to the
+      language.
+
+
 .. _callable-types:
 
 Emulating callable objects
diff --git a/Lib/pipes.py b/Lib/pipes.py
index deab815..51666a8 100644
--- a/Lib/pipes.py
+++ b/Lib/pipes.py
@@ -249,11 +249,11 @@ def makepipeline(infile, steps, outfile):
 
 # Reliably quote a string as a single argument for /bin/sh
 
-_safechars = string.ascii_letters + string.digits + '!@%_-+=:,./' # Safe unquoted
-_funnychars = '"`$\\'                           # Unsafe inside "double quotes"
+# Safe unquoted
+_safechars = frozenset(string.ascii_letters + string.digits + '@%_-+=:,./')
 
 def quote(file):
-    ''' return a shell-escaped version of the file string '''
+    """Return a shell-escaped version of the file string."""
     for c in file:
         if c not in _safechars:
             break
@@ -261,11 +261,6 @@ def quote(file):
         if not file:
             return "''"
         return file
-    if '\'' not in file:
-        return '\'' + file + '\''
-    res = ''
-    for c in file:
-        if c in _funnychars:
-            c = '\\' + c
-        res = res + c
-    return '"' + res + '"'
+    # use single quotes, and put single quotes into double quotes
+    # the string $'b is then quoted as '$'"'"'b'
+    return "'" + file.replace("'", "'\"'\"'") + "'"
diff --git a/Lib/test/test_pipes.py b/Lib/test/test_pipes.py
index 9ce137e..3d31fce 100644
--- a/Lib/test/test_pipes.py
+++ b/Lib/test/test_pipes.py
@@ -70,9 +70,10 @@ class SimplePipeTests(unittest.TestCase):
         self.assertEqual(open(TESTFN).read(), d)
 
     def testQuoting(self):
-        safeunquoted = string.ascii_letters + string.digits + '!@%_-+=:,./'
-        unsafe = '"`$\\'
+        safeunquoted = string.ascii_letters + string.digits + '@%_-+=:,./'
+        unsafe = '"`$\\!'
 
+        self.assertEqual(pipes.quote(''), "''")
         self.assertEqual(pipes.quote(safeunquoted), safeunquoted)
         self.assertEqual(pipes.quote('test file name'), "'test file name'")
         for u in unsafe:
@@ -80,9 +81,7 @@ class SimplePipeTests(unittest.TestCase):
                               "'test%sname'" % u)
         for u in unsafe:
             self.assertEqual(pipes.quote("test%s'name'" % u),
-                              '"test\\%s\'name\'"' % u)
-
-        self.assertEqual(pipes.quote(''), "''")
+                             "'test%s'\"'\"'name'\"'\"''" % u)
 
     def testRepr(self):
         t = pipes.Template()
diff --git a/Misc/NEWS b/Misc/NEWS
index e68e5da..68bebe9 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -38,6 +38,8 @@ Core and Builtins
   PyUnicode_FromString() to support surrogates in the filename and use the
   right encoding
 
+- Issue #7507: Quote "!" in pipes.quote(); it is special to some shells.
+
 - PyUnicode_DecodeFSDefaultAndSize() uses surrogateescape error handler
 
 - Issue #8419: Prevent the dict constructor from accepting non-string keyword