Merged revisions 67531-67532,67538,67553-67554,67556-67557,67571,67574-67575,67579-67580,67591,67597,67608,67631 via svnmerge from

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

........
  r67531 | georg.brandl | 2008-12-04 19:54:05 +0100 (Thu, 04 Dec 2008) | 2 lines

  Add reference to enumerate() to indices example.
........
  r67532 | georg.brandl | 2008-12-04 19:59:16 +0100 (Thu, 04 Dec 2008) | 2 lines

  Add another heapq example.
........
  r67538 | georg.brandl | 2008-12-04 22:28:16 +0100 (Thu, 04 Dec 2008) | 2 lines

  Clarification to avoid confusing output with file descriptors.
........
  r67553 | georg.brandl | 2008-12-05 08:49:49 +0100 (Fri, 05 Dec 2008) | 2 lines

  #4408: document regex.groups.
........
  r67554 | georg.brandl | 2008-12-05 08:52:26 +0100 (Fri, 05 Dec 2008) | 2 lines

  #4409: fix asterisks looking like footnotes.
........
  r67556 | georg.brandl | 2008-12-05 09:02:17 +0100 (Fri, 05 Dec 2008) | 2 lines

  #4441: improve doc for os.open() flags.
........
  r67557 | georg.brandl | 2008-12-05 09:06:57 +0100 (Fri, 05 Dec 2008) | 2 lines

  Add an index entry for "subclassing immutable types".
........
  r67571 | georg.brandl | 2008-12-05 10:13:45 +0100 (Fri, 05 Dec 2008) | 2 lines

  Use markup.
........
  r67574 | georg.brandl | 2008-12-05 10:25:32 +0100 (Fri, 05 Dec 2008) | 2 lines

  #4441 followup: Add link to open() docs for Windows.
........
  r67575 | georg.brandl | 2008-12-05 12:34:51 +0100 (Fri, 05 Dec 2008) | 2 lines

  #4544: add `dedent` to textwrap.__all__.
........
  r67579 | georg.brandl | 2008-12-05 16:29:39 +0100 (Fri, 05 Dec 2008) | 2 lines

  #4517: add "special method" glossary entry and clarify when __getattribute__ is bypassed.
........
  r67580 | georg.brandl | 2008-12-05 16:32:29 +0100 (Fri, 05 Dec 2008) | 2 lines

  #4478: document that copyfile() can raise Error.
........
  r67591 | georg.brandl | 2008-12-05 19:00:06 +0100 (Fri, 05 Dec 2008) | 2 lines

  Followup to #4511: add link from decorator glossary entry to definition.
........
  r67597 | georg.brandl | 2008-12-05 20:03:19 +0100 (Fri, 05 Dec 2008) | 2 lines

  Remove confusing sentence part.
........
  r67608 | georg.brandl | 2008-12-06 12:57:12 +0100 (Sat, 06 Dec 2008) | 2 lines

  Follow-up to #4488: document PIPE and STDOUT properly.
........
  r67631 | georg.brandl | 2008-12-07 12:54:07 +0100 (Sun, 07 Dec 2008) | 2 lines

  Add link to the favicon to the docs.
........

6 files changed, 67 insertions, 34 deletions

diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst
index 4bf5bef..94ba90e 100644
--- a/Doc/library/getopt.rst
+++ b/Doc/library/getopt.rst
@@ -63,8 +63,8 @@ exception:
    non-option argument is encountered.
 
    If the first character of the option string is '+', or if the environment
-   variable POSIXLY_CORRECT is set, then option processing stops as soon as a
-   non-option argument is encountered.
+   variable :envvar:`POSIXLY_CORRECT` is set, then option processing stops as
+   soon as a non-option argument is encountered.
 
 
 .. exception:: GetoptError
diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst
index 8e5ce95..5138c83 100644
--- a/Doc/library/heapq.rst
+++ b/Doc/library/heapq.rst
@@ -86,6 +86,21 @@ Example of use:
    >>> data == ordered
    True
 
+Using a heap to insert items at the correct place in a priority queue:
+
+   >>> heap = []
+   >>> data = [(1, 'J'), (4, 'N'), (3, 'H'), (2, 'O')]
+   >>> for item in data:
+   ...     heappush(heap, item)
+   ...
+   >>> while heap:
+   ...     print(heappop(heap)[1])
+   J
+   O
+   H
+   N
+
+   
 The module also offers three general purpose functions based on heaps.
 
 
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 3cc77bc..1c69e25 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -567,10 +567,11 @@ by file descriptors.
       :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its :meth:`write`
       method.
 
-The following data items are available for use in constructing the *flags*
-parameter to the :func:`open` function.  Some items will not be available on all
-platforms.  For descriptions of their availability and use, consult
-:manpage:`open(2)`.
+The following constants are options for the *flags* parameter to the
+:func:`open` function.  They can be combined using the bitwise OR operator
+``|``.  Some of them are not available on all platforms.  For descriptions of
+their availability and use, consult the :manpage:`open(2)` manual page on Unix
+or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>` on Windows.
 
 
 .. data:: O_RDONLY
@@ -581,8 +582,7 @@ platforms.  For descriptions of their availability and use, consult
           O_EXCL
           O_TRUNC
 
-   Options for the *flag* argument to the :func:`open` function. These can be
-   combined using the bitwise OR operator ``|``. Availability: Unix, Windows.
+   These constants are available on Unix and Windows.
 
 
 .. data:: O_DSYNC
@@ -594,8 +594,7 @@ platforms.  For descriptions of their availability and use, consult
           O_SHLOCK
           O_EXLOCK
 
-   More options for the *flag* argument to the :func:`open` function. Availability:
-   Unix.
+   These constants are only available on Unix.
 
 
 .. data:: O_BINARY
@@ -606,8 +605,7 @@ platforms.  For descriptions of their availability and use, consult
           O_SEQUENTIAL
           O_TEXT
 
-   Options for the *flag* argument to the :func:`open` function. These can be
-   combined using the bitwise OR operator ``|``. Availability: Windows.
+   These constants are only available on Windows.
 
 
 .. data:: O_ASYNC
@@ -616,8 +614,8 @@ platforms.  For descriptions of their availability and use, consult
           O_NOFOLLOW
           O_NOATIME
 
-   Options for the *flag* argument to the :func:`open` function. These are
-   GNU extensions and not present if they are not defined by the C library.
+   These constants are GNU extensions and not present if they are not defined by
+   the C library.
 
 
 .. data:: SEEK_SET
diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index 2020577..ce52185 100644
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -770,6 +770,11 @@ attributes:
    were provided.
 
 
+.. attribute:: RegexObject.groups
+
+   The number of capturing groups in the pattern.
+
+
 .. attribute:: RegexObject.groupindex
 
    A dictionary mapping any symbolic group names defined by ``(?P<id>)`` to group
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index c4b97a0..ac52ce4 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -43,7 +43,8 @@ copying and removal. For operations on individual files, see also the
 
    Copy the contents (no metadata) of the file named *src* to a file named *dst*.
    *dst* must be the complete target file name; look at :func:`copy` for a copy that
-   accepts a target directory path.
+   accepts a target directory path.  If *src* and *dst* are the same files,
+   :exc:`Error` is raised.
    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
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 68f8bfc..6aff816 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -68,13 +68,13 @@ This module defines one class called :class:`Popen`:
    specified by the :envvar:`COMSPEC` environment variable.
 
    *stdin*, *stdout* and *stderr* specify the executed programs' standard input,
-   standard output and standard error file handles, respectively.  Valid values are
-   ``PIPE``, an existing file descriptor (a positive integer), an existing file
-   object, and ``None``.  ``PIPE`` indicates that a new pipe to the child should be
-   created.  With ``None``, no redirection will occur; the child's file handles
-   will be inherited from the parent.  Additionally, *stderr* can be ``STDOUT``,
-   which indicates that the stderr data from the applications should be captured
-   into the same file handle as for stdout.
+   standard output and standard error file handles, respectively.  Valid values
+   are :data:`PIPE`, an existing file descriptor (a positive integer), an
+   existing file object, and ``None``.  :data:`PIPE` indicates that a new pipe
+   to the child should be created.  With ``None``, no redirection will occur;
+   the child's file handles will be inherited from the parent.  Additionally,
+   *stderr* can be :data:`STDOUT`, which indicates that the stderr data from the
+   applications should be captured into the same file handle as for stdout.
 
    If *preexec_fn* is set to a callable object, this object will be called in the
    child process just before the child is executed. (Unix only)
@@ -114,6 +114,20 @@ This module defines one class called :class:`Popen`:
    of the main window and priority for the new process.  (Windows only)
 
 
+.. data:: PIPE
+
+   Special value that can be used as the *stdin*, *stdout* or *stderr* argument
+   to :class:`Popen` and indicates that a pipe to the standard stream should be
+   opened.
+
+
+.. data:: STDOUT
+
+   Special value that can be used as the *stderr* argument to :class:`Popen` and
+   indicates that standard error should go into the same handle as standard
+   output.
+   
+
 Convenience Functions
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -229,7 +243,7 @@ Instances of the :class:`Popen` class have the following methods:
    *input* argument should be a byte string to be sent to the child process, or
    ``None``, if no data should be sent to the child.
 
-   :meth:`communicate` returns a tuple ``(stdout, stderr)``.
+   :meth:`communicate` returns a tuple ``(stdoutdata, stderrdata)``.
 
    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
@@ -277,20 +291,21 @@ The following attributes are also available:
 
 .. attribute:: Popen.stdin
 
-   If the *stdin* argument is ``PIPE``, this attribute is a file object that
-   provides input to the child process.  Otherwise, it is ``None``.
+   If the *stdin* argument was :data:`PIPE`, this attribute is a file object
+   that provides input to the child process.  Otherwise, it is ``None``.
 
 
 .. attribute:: Popen.stdout
 
-   If the *stdout* argument is ``PIPE``, this attribute is a file object that
-   provides output from the child process.  Otherwise, it is ``None``.
+   If the *stdout* argument was :data:`PIPE`, this attribute is a file object
+   that provides output from the child process.  Otherwise, it is ``None``.
 
 
 .. attribute:: Popen.stderr
 
-   If the *stderr* argument is ``PIPE``, this attribute is file object that
-   provides error output from the child process.  Otherwise, it is ``None``.
+   If the *stderr* argument was :data:`PIPE`, this attribute is a file object
+   that provides error output from the child process.  Otherwise, it is
+   ``None``.
 
 
 .. attribute:: Popen.pid
@@ -374,8 +389,8 @@ A more realistic example would look like this::
        print("Execution failed:", e, file=sys.stderr)
 
 
-Replacing os.spawn\*
-^^^^^^^^^^^^^^^^^^^^
+Replacing the os.spawn family
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 P_NOWAIT example::
 
@@ -402,8 +417,8 @@ Environment example::
    Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
 
 
-Replacing os.popen\*
-^^^^^^^^^^^^^^^^^^^^
+Replacing os.popen
+^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -416,4 +431,3 @@ Replacing os.popen\*
    pipe = os.popen(cmd, 'w', bufsize)
    ==>
    pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin
-