Merged revisions 59774-59783 via svnmerge from

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

........
  r59774 | georg.brandl | 2008-01-06 16:41:50 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1501: document that 0**0 == 1.
........
  r59775 | georg.brandl | 2008-01-06 16:48:20 +0100 (Sun, 06 Jan 2008) | 2 lines

  #759525: document that dir() doesn't return metaclass attrs when given a class as arg.
........
  r59776 | georg.brandl | 2008-01-06 16:55:26 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1615275: clarify return object types of different tempfile factories.
........
  r59777 | georg.brandl | 2008-01-06 17:01:26 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1727024: document that Popen.returncode is set by Popen.poll/wait.
........
  r59778 | georg.brandl | 2008-01-06 17:04:56 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1686390: add example for csv.Sniffer use.
........
  r59779 | georg.brandl | 2008-01-06 17:12:39 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1559684: document that shutil.copy* doesn't copy all metadata on Posix and Windows too.
........
  r59780 | georg.brandl | 2008-01-06 17:17:56 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1582: document __reversed__, patch by Mark Russell.
........
  r59781 | georg.brandl | 2008-01-06 17:22:56 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1499: Document compile() exceptions.
........
  r59782 | georg.brandl | 2008-01-06 17:49:50 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1325: Add docs and tests for zipimporter.archive and zipimporter.prefix.
........

10 files changed, 112 insertions, 44 deletions

diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt
index 32943bddd5..7344cf8dac 100644
--- a/Doc/ACKS.txt
+++ b/Doc/ACKS.txt
@@ -158,6 +158,7 @@ docs@python.org), and we'll be glad to correct the problem.
    * Jim Roskind
    * Guido van Rossum
    * Donald Wallace Rouse II
+   * Mark Russell
    * Nick Russo
    * Chris Ryland
    * Constantina S.
diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index 678d4d70a0..56972f4af8 100644
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -211,7 +211,6 @@ The :mod:`csv` module defines the following classes:
 
 The :class:`Sniffer` class provides two methods:
 
-
 .. method:: Sniffer.sniff(sample[, delimiters=None])
 
    Analyze the given *sample* and return a :class:`Dialect` subclass reflecting the
@@ -224,9 +223,17 @@ The :class:`Sniffer` class provides two methods:
    Analyze the sample text (presumed to be in CSV format) and return :const:`True`
    if the first row appears to be a series of column headers.
 
-The :mod:`csv` module defines the following constants:
+An example for :class:`Sniffer` use::
+
+   csvfile = open("example.csv")
+   dialect = csv.Sniffer().sniff(csvfile.read(1024))
+   csvfile.seek(0)
+   reader = csv.reader(csvfile, dialect)
+   # ... process CSV file contents here ...
 
 
+The :mod:`csv` module defines the following constants:
+
 .. data:: QUOTE_ALL
 
    Instructs :class:`writer` objects to quote all fields.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 9463ba76d5..e7add3a38c 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -232,6 +232,9 @@ available.  They are listed here in alphabetical order.
    can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
    instance in the :mod:`__future__` module.
 
+   This function raises :exc:`SyntaxError` if the compiled source is invalid,
+   and :exc:`TypeError` if the source contains null bytes.
+
 
 .. function:: complex([real[, imag]])
 
@@ -313,7 +316,8 @@ available.  They are listed here in alphabetical order.
       Because :func:`dir` is supplied primarily as a convenience for use at an
       interactive prompt, it tries to supply an interesting set of names more than it
       tries to supply a rigorously or consistently defined set of names, and its
-      detailed behavior may change across releases.
+      detailed behavior may change across releases.  For example, metaclass attributes
+      are not in the result list when the argument is a class.
 
 
 .. function:: divmod(a, b)
@@ -907,9 +911,10 @@ available.  They are listed here in alphabetical order.
 
 .. function:: reversed(seq)
 
-   Return a reverse :term:`iterator`.  *seq* must be an object which supports
-   the sequence protocol (the :meth:`__len__` method and the :meth:`__getitem__`
-   method with integer arguments starting at ``0``).
+   Return a reverse :term:`iterator`.  *seq* must be an object which has
+   a :meth:`__reversed__` method or supports the sequence protocol (the
+   :meth:`__len__` method and the :meth:`__getitem__` method with integer
+   arguments starting at ``0``).
 
 
 .. function:: round(x[, n])
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 5cdec20bf7..e5008f666d 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -180,6 +180,11 @@ attributes:
    name.  If the optional *predicate* argument is supplied, only members for which
    the predicate returns a true value are included.
 
+   .. note::
+
+      :func:`getmembers` does not return metaclass attributes when the argument
+      is a class (this behavior is inherited from the :func:`dir` function).
+
 
 .. function:: getmoduleinfo(path)
 
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 3275179c4e..f80c893180 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -17,16 +17,21 @@ copying and removal. For operations on individual files, see also the
 :mod:`os` module.
 
 .. warning::
+
+   Even the higher-level file copying functions (:func:`copy`, :func:`copy2`)
+   can't copy all file metadata.
    
-   On MacOS, the resource fork and other metadata are not used.  For file copies,
-   this means that resources will be lost and  file type and creator codes will
-   not be correct.
+   On POSIX platforms, this means that file owner and group are lost as well
+   as ACLs.  On MacOS, the resource fork and other metadata are not used.
+   This means that resources will be lost and file type and creator codes will
+   not be correct. On Windows, file owners, ACLs and alternate data streams
+   are not copied.
 
 
 .. function:: copyfile(src, dst)
 
-   Copy the contents of the file named *src* to a file named *dst*.  The
-   destination location must be writable; otherwise,  an :exc:`IOError` exception
+   Copy the contents (no metadata) of the file named *src* to a file named *dst*.
+   The destination location must be writable; otherwise,  an :exc:`IOError` exception
    will be raised. If *dst* already exists, it will be replaced.   Special files
    such as character or block devices and pipes cannot be copied with this
    function.  *src* and *dst* are path names given as strings.
@@ -106,13 +111,13 @@ 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 our current filesystem, then simply use rename.
+   If the destination is on the current filesystem, then simply use rename.
    Otherwise, copy src to the dst and then remove src.
 
 
 .. exception:: Error
 
-   This exception collects exceptions that raised during a mult-file operation. For
+   This exception collects exceptions that raised during a multi-file operation. For
    :func:`copytree`, the exception argument is a list of 3-tuples (*srcname*,
    *dstname*, *exception*).
 
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 92183a4883..fc96f45ec8 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -314,9 +314,9 @@ numeric operations have a higher priority than comparison operations):
 +---------------------+---------------------------------+-------+--------------------+
 | ``divmod(x, y)``    | the pair ``(x // y, x % y)``    | \(2)  | :func:`divmod`     |
 +---------------------+---------------------------------+-------+--------------------+
-| ``pow(x, y)``       | *x* to the power *y*            |       | :func:`pow`        |
+| ``pow(x, y)``       | *x* to the power *y*            | (7)   | :func:`pow`        |
 +---------------------+---------------------------------+-------+--------------------+
-| ``x ** y``          | *x* to the power *y*            |       |                    |
+| ``x ** y``          | *x* to the power *y*            | (7)   |                    |
 +---------------------+---------------------------------+-------+--------------------+
 
 .. index::
@@ -350,6 +350,11 @@ Notes:
 (6)
    float also accepts the strings "nan" and "inf" with an optional prefix "+" 
    or "-" for Not a Number (NaN) and positive or negative infinity.
+
+(7)
+   Python defines ``pow(0, 0)`` and ``0 ** 0`` to be ``1``, as is common for
+   programming languages.
+
    
 
 All :class:`numbers.Real` types (:class:`int` and
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index d2604738ae..c876efe4f5 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -172,12 +172,14 @@ Instances of the :class:`Popen` class have the following methods:
 
 .. method:: Popen.poll()
 
-   Check if child process has terminated.  Returns returncode attribute.
+   Check if child process has terminated.  Set and return :attr:`returncode`
+   attribute.
 
 
 .. method:: Popen.wait()
 
-   Wait for child process to terminate.  Returns returncode attribute.
+   Wait for child process to terminate.  Set and return :attr:`returncode`
+   attribute.
 
 
 .. method:: Popen.communicate(input=None)
@@ -187,20 +189,20 @@ Instances of the :class:`Popen` class have the following methods:
    *input* argument should be a string to be sent to the child process, or
    ``None``, if no data should be sent to the child.
 
-   communicate() returns a tuple (stdout, stderr).
+   :meth:`communicate` returns a tuple ``(stdout, stderr)``.
 
    Note that if you want to send data to the process's stdin, you need to create
    the Popen object with ``stdin=PIPE``.  Similarly, to get anything other than
    ``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or
    ``stderr=PIPE`` too.
 
-.. note::
+   .. note::
 
-      The data read is buffered in memory, so do not use this method if the data size
-      is large or unlimited.
+      The data read is buffered in memory, so do not use this method if the data
+      size is large or unlimited.
 
-The following attributes are also available:
 
+The following attributes are also available:
 
 .. attribute:: Popen.stdin
 
@@ -227,9 +229,12 @@ The following attributes are also available:
 
 .. attribute:: Popen.returncode
 
-   The child return code.  A ``None`` value indicates that the process hasn't
-   terminated yet.  A negative value -N indicates that the child was terminated by
-   signal N (Unix only).
+   The child return code, set by :meth:`poll` and :meth:`wait` (and indirectly
+   by :meth:`communicate`).  A ``None`` value indicates that the process
+   hasn't terminated yet.
+   
+   A negative value ``-N`` indicates that the child was terminated by signal
+   ``N`` (Unix only).
 
 
 Replacing Older Functions with the subprocess Module
diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst
index 74c032ff27..e38dbab1cb 100644
--- a/Doc/library/tempfile.rst
+++ b/Doc/library/tempfile.rst
@@ -34,7 +34,7 @@ The module defines the following user-callable functions:
 
 .. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]])
 
-   Return a file (or file-like) object that can be used as a temporary storage
+   Return a file-like object that can be used as a temporary storage
    area.  The file is created using :func:`mkstemp`. It will be destroyed as soon
    as it is closed (including an implicit close when the object is garbage
    collected).  Under Unix, the directory entry for the file is removed immediately
@@ -49,6 +49,10 @@ The module defines the following user-callable functions:
 
    The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`.
 
+   The returned object is a true file object on POSIX platforms.  On other
+   platforms, it is a file-like object whose :attr:`file` attribute is the
+   underlying true file object.
+
 
 .. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir[, delete]]]]]])
 
@@ -59,6 +63,8 @@ The module defines the following user-callable functions:
    the file a second time, while the named temporary file is still open, varies
    across platforms (it can be so used on Unix; it cannot on Windows NT or later).
    If *delete* is true (the default), the file is deleted as soon as it is closed.
+   The returned object is always a file-like object whose :attr:`file` attribute
+   is the underlying true file object.
 
 
 .. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]]])
@@ -71,6 +77,10 @@ The module defines the following user-callable functions:
    The resulting file has one additional method, :func:`rollover`, which causes the
    file to roll over to an on-disk file regardless of its size.
 
+   The returned object is a file-like object whose :attr:`_file` attribute
+   is either a :class:`StringIO` object or a true file object, depending on
+   whether :func:`rollover` has been called.
+
 
 .. function:: mkstemp([suffix[, prefix[, dir[, text]]]])
 
diff --git a/Doc/library/zipimport.rst b/Doc/library/zipimport.rst
index 6845bf7a43..ed9c631469 100644
--- a/Doc/library/zipimport.rst
+++ b/Doc/library/zipimport.rst
@@ -27,21 +27,6 @@ Any files may be present in the ZIP archive, but only files :file:`.py` and
 corresponding :file:`.pyc` or :file:`.pyo` file, meaning that if a ZIP archive
 doesn't contain :file:`.pyc` files, importing may be rather slow.
 
-The available attributes of this module are:
-
-
-.. exception:: ZipImportError
-
-   Exception raised by zipimporter objects. It's a subclass of :exc:`ImportError`,
-   so it can be caught as :exc:`ImportError`, too.
-
-
-.. class:: zipimporter
-
-   The class for importing ZIP files.  See section :ref:`zipimporter-objects`
-   for constructor details.
-
-
 .. seealso::
 
    `PKZIP Application Note <http://www.pkware.com/business_and_developers/developer/appnote/>`_
@@ -57,18 +42,33 @@ The available attributes of this module are:
       The PEP to add the import hooks that help this module work.
 
 
+This module defines an exception:
+
+.. exception:: ZipImportError
+
+   Exception raised by zipimporter objects. It's a subclass of :exc:`ImportError`,
+   so it can be caught as :exc:`ImportError`, too.
+
+
 .. _zipimporter-objects:
 
 zipimporter Objects
 -------------------
 
+:class:`zipimporter` is the class for importing ZIP files.
 
 .. class:: zipimporter(archivepath)
 
-   Create a new zipimporter instance. *archivepath* must be a path to a zipfile.
+   Create a new zipimporter instance. *archivepath* must be a path to a ZIP file.
    :exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP
    archive.
 
+   *archivepath* can also contain a path within the ZIP file -- the importer
+   object will then look under that path instead of the ZIP file root.  For
+   example, an *archivepath* of :file:`foo/bar.zip/lib` will look for modules
+   in the :file:`lib` directory inside the ZIP file :file:`foo/bar.zip`
+   (provided that it exists).
+
 
 .. method:: zipimporter.find_module(fullname[, path])
 
@@ -110,11 +110,22 @@ zipimporter Objects
    :exc:`ZipImportError` if it wasn't found.
 
 
-Examples
---------
+.. attribute:: zipimporter.archive
+
+   The file name of the importer's associated ZIP file.
+
+
+.. attribute:: zipimporter.prefix
+
+   The path within the ZIP file where modules are searched; see
+   :class:`zipimporter` for details.
+
 
 .. _zipimport-examples:
 
+Examples
+--------
+
 Here is an example that imports a module from a ZIP archive - note that the
 :mod:`zipimport` module is not explicitly used. ::
 
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 6acd25a760..9c2d7cd584 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1688,6 +1688,20 @@ container; for mappings, :meth:`__iter__` should be the same as
    Iterator objects also need to implement this method; they are required to return
    themselves.  For more information on iterator objects, see :ref:`typeiter`.
 
+
+.. method:: object.__reversed__(self)
+
+   Called (if present) by the :func:`reversed` builtin to implement
+   reverse iteration.  It should return a new iterator object that iterates
+   over all the objects in the container in reverse order.
+
+   If the :meth:`__reversed__` method is not provided, the
+   :func:`reversed` builtin will fall back to using the sequence protocol
+   (:meth:`__len__` and :meth:`__getitem__`).  Objects should normally
+   only provide :meth:`__reversed__` if they do not support the sequence
+   protocol and an efficient implementation of reverse iteration is possible.
+
+
 The membership test operators (:keyword:`in` and :keyword:`not in`) are normally
 implemented as an iteration through a sequence.  However, container objects can
 supply the following special method with a more efficient implementation, which