Merged revisions 62350-62355,62358-62359,62364-62365,62370,62372-62375,62378-62379,62381 via svnmerge from

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

........
  r62350 | nick.coghlan | 2008-04-15 12:25:31 +0200 (Tue, 15 Apr 2008) | 1 line

  Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)
........
  r62351 | nick.coghlan | 2008-04-15 12:28:14 +0200 (Tue, 15 Apr 2008) | 1 line

  Add test file missing from rev 62350
........
  r62352 | benjamin.peterson | 2008-04-15 13:58:46 +0200 (Tue, 15 Apr 2008) | 2 lines

  Add myself to Doc/ACKS.txt
........
  r62353 | andrew.kuchling | 2008-04-15 15:10:07 +0200 (Tue, 15 Apr 2008) | 6 lines

  Add *,**,@ to index, as suggested by
  http://farmdev.com/thoughts/24/what-does-the-def-star-variable-or-def-asterisk-parameter-syntax-do-in-python-/

  The right entry type to use isn't clear; operator seems wrong, because *,**,@
  aren't being used in expressions here.  I put them as 'statement'; 'syntax'
  might be better.
........
  r62354 | andrew.kuchling | 2008-04-15 15:10:41 +0200 (Tue, 15 Apr 2008) | 1 line

  Typo fix
........
  r62355 | mark.dickinson | 2008-04-15 22:51:18 +0200 (Tue, 15 Apr 2008) | 3 lines

  Fix for possible signed overflow:  the behaviour of -LONG_MIN is
  undefined in ANSI C.
........
  r62358 | jeroen.ruigrok | 2008-04-16 14:47:01 +0200 (Wed, 16 Apr 2008) | 2 lines

  Reformat to 80 columns prior to adding documentation.
........
  r62359 | jeroen.ruigrok | 2008-04-16 14:57:43 +0200 (Wed, 16 Apr 2008) | 2 lines

  Add details about the return value for mmap.flush().
........
  r62364 | raymond.hettinger | 2008-04-17 12:48:31 +0200 (Thu, 17 Apr 2008) | 1 line

  Issue 2648: Add leading zero to money format recipe in the docs.
........
  r62365 | jeroen.ruigrok | 2008-04-17 14:39:45 +0200 (Thu, 17 Apr 2008) | 2 lines

  Be consistent in the use of read-only.
........
  r62370 | andrew.kuchling | 2008-04-17 22:44:06 +0200 (Thu, 17 Apr 2008) | 1 line

  Typo fixes
........
  r62372 | andrew.kuchling | 2008-04-18 04:40:47 +0200 (Fri, 18 Apr 2008) | 1 line

  Use correct parameter name
........
  r62373 | andrew.kuchling | 2008-04-18 18:53:09 +0200 (Fri, 18 Apr 2008) | 1 line

  #2654: fix typo
........
  r62374 | andrew.kuchling | 2008-04-18 20:28:23 +0200 (Fri, 18 Apr 2008) | 4 lines

  Remove personal note from Jim Roskind; it no longer applies, and the
  e-mail address is for a previous employer.

  Can we move the big long copyright statement into a sidebar or something?
........
  r62375 | andrew.kuchling | 2008-04-18 20:39:55 +0200 (Fri, 18 Apr 2008) | 1 line

  Rewrite introductory section, and remove old section.  (It was already commented-out, but why keep it?)
........
  r62378 | skip.montanaro | 2008-04-18 22:35:46 +0200 (Fri, 18 Apr 2008) | 1 line

  resolve issue 2014
........
  r62379 | benjamin.peterson | 2008-04-18 22:45:33 +0200 (Fri, 18 Apr 2008) | 2 lines

  Fix indentation in sysmodule.c
........
  r62381 | amaury.forgeotdarc | 2008-04-19 01:31:33 +0200 (Sat, 19 Apr 2008) | 3 lines

  Some tests did not pass on repeated calls (regrtest -R::)
  Perform additional cleanup, mostly deleting from sys.modules, or clearing the warnings registry.
........

1 files changed, 97 insertions, 87 deletions

diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst
index 8ec9885..0361320 100644
--- a/Doc/library/mmap.rst
+++ b/Doc/library/mmap.rst
@@ -8,54 +8,55 @@
 
 Memory-mapped file objects behave like both strings and like file objects.
 Unlike normal string objects, however, these are mutable.  You can use mmap
-objects in most places where strings are expected; for example, you can use the
-:mod:`re` module to search through a memory-mapped file.  Since they're mutable,
-you can change a single character by doing ``obj[index] = 'a'``, or change a
-substring by assigning to a slice: ``obj[i1:i2] = '...'``.  You can also read
-and write data starting at the current file position, and :meth:`seek` through
-the file to different positions.
-
-A memory-mapped file is created by the :class:`mmap` constructor, which is different
-on Unix and on Windows.  In either case you must provide a file descriptor for a
-file opened for update. If you wish to map an existing Python file object, use
-its :meth:`fileno` method to obtain the correct value for the *fileno*
-parameter.  Otherwise, you can open the file using the :func:`os.open` function,
-which returns a file descriptor directly (the file still needs to be closed when
-done).
+objects in most places where strings are expected; for example, you can use
+the :mod:`re` module to search through a memory-mapped file.  Since they're
+mutable, you can change a single character by doing ``obj[index] = 'a'``, or
+change a substring by assigning to a slice: ``obj[i1:i2] = '...'``.  You can
+also read and write data starting at the current file position, and
+:meth:`seek` through the file to different positions.
+
+A memory-mapped file is created by the :class:`mmap` constructor, which is
+different on Unix and on Windows.  In either case you must provide a file
+descriptor for a file opened for update. If you wish to map an existing Python
+file object, use its :meth:`fileno` method to obtain the correct value for the
+*fileno* parameter.  Otherwise, you can open the file using the
+:func:`os.open` function, which returns a file descriptor directly (the file
+still needs to be closed when done).
 
 For both the Unix and Windows versions of the constructor, *access* may be
 specified as an optional keyword parameter. *access* accepts one of three
-values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to
-specify readonly, write-through or copy-on-write memory respectively. *access*
-can be used on both Unix and Windows.  If *access* is not specified, Windows
-mmap returns a write-through mapping.  The initial memory values for all three
-access types are taken from the specified file.  Assignment to an
-:const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception.  Assignment
-to an :const:`ACCESS_WRITE` memory map affects both memory and the underlying
-file.  Assignment to an :const:`ACCESS_COPY` memory map affects memory but does
-not update the underlying file.
+values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY`
+to specify read-only, write-through or copy-on-write memory respectively.
+*access* can be used on both Unix and Windows.  If *access* is not specified,
+Windows mmap returns a write-through mapping.  The initial memory values for
+all three access types are taken from the specified file.  Assignment to an
+:const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception.
+Assignment to an :const:`ACCESS_WRITE` memory map affects both memory and the
+underlying file.  Assignment to an :const:`ACCESS_COPY` memory map affects
+memory but does not update the underlying file.
 
 To map anonymous memory, -1 should be passed as the fileno along with the length.
 
 .. class:: mmap(fileno, length[, tagname[, access[, offset]]])
 
-   **(Windows version)** Maps *length* bytes from the file specified by the file
-   handle *fileno*, and creates a mmap object.  If *length* is larger than the
-   current size of the file, the file is extended to contain *length* bytes.  If
-   *length* is ``0``, the maximum length of the map is the current size of the
-   file, except that if the file is empty Windows raises an exception (you cannot
-   create an empty mapping on Windows).
+   **(Windows version)** Maps *length* bytes from the file specified by the
+   file handle *fileno*, and creates a mmap object.  If *length* is larger
+   than the current size of the file, the file is extended to contain *length*
+   bytes.  If *length* is ``0``, the maximum length of the map is the current
+   size of the file, except that if the file is empty Windows raises an
+   exception (you cannot create an empty mapping on Windows).
 
-   *tagname*, if specified and not ``None``, is a string giving a tag name for the
-   mapping.  Windows allows you to have many different mappings against the same
-   file.  If you specify the name of an existing tag, that tag is opened, otherwise
-   a new tag of this name is created.  If this parameter is omitted or ``None``,
-   the mapping is created without a name.  Avoiding the use of the tag parameter
-   will assist in keeping your code portable between Unix and Windows.
+   *tagname*, if specified and not ``None``, is a string giving a tag name for
+   the mapping.  Windows allows you to have many different mappings against
+   the same file.  If you specify the name of an existing tag, that tag is
+   opened, otherwise a new tag of this name is created.  If this parameter is
+   omitted or ``None``, the mapping is created without a name.  Avoiding the
+   use of the tag parameter will assist in keeping your code portable between
+   Unix and Windows.
 
-   *offset* may be specified as a non-negative integer offset. mmap references will 
-   be relative to the offset from the beginning of the file. *offset* defaults to 0.
-   *offset* must be a multiple of the ALLOCATIONGRANULARITY.
+   *offset* may be specified as a non-negative integer offset. mmap references
+   will be relative to the offset from the beginning of the file. *offset*
+   defaults to 0.  *offset* must be a multiple of the ALLOCATIONGRANULARITY.
 
 
 .. class:: mmap(fileno, length[, flags[, prot[, access[, offset]]]])
@@ -63,26 +64,29 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
 
    **(Unix version)** Maps *length* bytes from the file specified by the file
    descriptor *fileno*, and returns a mmap object.  If *length* is ``0``, the
-   maximum length of the map will be the current size of the file when :class:`mmap`
-   is called.
+   maximum length of the map will be the current size of the file when
+   :class:`mmap` is called.
 
    *flags* specifies the nature of the mapping. :const:`MAP_PRIVATE` creates a
-   private copy-on-write mapping, so changes to the contents of the mmap object
-   will be private to this process, and :const:`MAP_SHARED` creates a mapping
-   that's shared with all other processes mapping the same areas of the file.  The
-   default value is :const:`MAP_SHARED`.
-
-   *prot*, if specified, gives the desired memory protection; the two most useful
-   values are :const:`PROT_READ` and :const:`PROT_WRITE`, to specify that the pages
-   may be read or written.  *prot* defaults to :const:`PROT_READ \| PROT_WRITE`.
-
-   *access* may be specified in lieu of *flags* and *prot* as an optional keyword
-   parameter.  It is an error to specify both *flags*, *prot* and *access*.  See
-   the description of *access* above for information on how to use this parameter.
-
-   *offset* may be specified as a non-negative integer offset. mmap references will 
-   be relative to the offset from the beginning of the file. *offset* defaults to 0.
-   *offset* must be a multiple of the PAGESIZE or ALLOCATIONGRANULARITY.
+   private copy-on-write mapping, so changes to the contents of the mmap
+   object will be private to this process, and :const:`MAP_SHARED` creates a
+   mapping that's shared with all other processes mapping the same areas of
+   the file.  The default value is :const:`MAP_SHARED`.
+
+   *prot*, if specified, gives the desired memory protection; the two most
+   useful values are :const:`PROT_READ` and :const:`PROT_WRITE`, to specify
+   that the pages may be read or written.  *prot* defaults to
+   :const:`PROT_READ \| PROT_WRITE`.
+
+   *access* may be specified in lieu of *flags* and *prot* as an optional
+   keyword parameter.  It is an error to specify both *flags*, *prot* and
+   *access*.  See the description of *access* above for information on how to
+   use this parameter.
+
+   *offset* may be specified as a non-negative integer offset. mmap references
+   will be relative to the offset from the beginning of the file. *offset*
+   defaults to 0.  *offset* must be a multiple of the PAGESIZE or
+   ALLOCATIONGRANULARITY.
    
    This example shows a simple way of using :class:`mmap`::
 
@@ -132,32 +136,38 @@ Memory-mapped file objects support the following methods:
 
 .. method:: mmap.close()
 
-   Close the file.  Subsequent calls to other methods of the object will result in
-   an exception being raised.
+   Close the file.  Subsequent calls to other methods of the object will
+   result in an exception being raised.
 
 
 .. method:: mmap.find(string[, start[, end]])
 
-   Returns the lowest index in the object where the substring *string* is found,
-   such that *string* is contained in the range [*start*, *end*]. Optional
-   arguments *start* and *end* are interpreted as in slice notation.
+   Returns the lowest index in the object where the substring *string* is
+   found, such that *string* is contained in the range [*start*, *end*].
+   Optional arguments *start* and *end* are interpreted as in slice notation.
    Returns ``-1`` on failure.
 
 
 .. method:: mmap.flush([offset, size])
 
-   Flushes changes made to the in-memory copy of a file back to disk. Without use
-   of this call there is no guarantee that changes are written back before the
-   object is destroyed.  If *offset* and *size* are specified, only changes to the
-   given range of bytes will be flushed to disk; otherwise, the whole extent of the
-   mapping is flushed.
+   Flushes changes made to the in-memory copy of a file back to disk. Without
+   use of this call there is no guarantee that changes are written back before
+   the object is destroyed.  If *offset* and *size* are specified, only
+   changes to the given range of bytes will be flushed to disk; otherwise, the
+   whole extent of the mapping is flushed.
+
+   **(Windows version)** A nonzero value returned indicates success; zero
+   indicates failure.
+
+   **(Unix version)** A zero value is returned to indicate success. An
+   exception is raised when the call failed.
 
 
 .. method:: mmap.move(dest, src, count)
 
-   Copy the *count* bytes starting at offset *src* to the destination index *dest*.
-   If the mmap was created with :const:`ACCESS_READ`, then calls to move will throw
-   a :exc:`TypeError` exception.
+   Copy the *count* bytes starting at offset *src* to the destination index
+   *dest*.  If the mmap was created with :const:`ACCESS_READ`, then calls to
+   move will throw a :exc:`TypeError` exception.
 
 
 .. method:: mmap.read(num)
@@ -175,31 +185,31 @@ Memory-mapped file objects support the following methods:
 
 .. method:: mmap.readline()
 
-   Returns a single line, starting at the current file position and up to the next
-   newline.
+   Returns a single line, starting at the current file position and up to the
+   next newline.
 
 
 .. method:: mmap.resize(newsize)
 
-   Resizes the map and the underlying file, if any. If the mmap was created with
-   :const:`ACCESS_READ` or :const:`ACCESS_COPY`, resizing the map will throw a
-   :exc:`TypeError` exception.
+   Resizes the map and the underlying file, if any. If the mmap was created
+   with :const:`ACCESS_READ` or :const:`ACCESS_COPY`, resizing the map will
+   throw a :exc:`TypeError` exception.
 
 
 .. method:: mmap.rfind(string[, start[, end]])
 
    Returns the highest index in the object where the substring *string* is
-   found, such that *string* is contained in the range [*start*,
-   *end*]. Optional arguments *start* and *end* are interpreted as in slice
-   notation.  Returns ``-1`` on failure.
+   found, such that *string* is contained in the range [*start*, *end*].
+   Optional arguments *start* and *end* are interpreted as in slice notation.
+   Returns ``-1`` on failure.
 
 
 .. method:: mmap.seek(pos[, whence])
 
-   Set the file's current position.  *whence* argument is optional and defaults to
-   ``os.SEEK_SET`` or ``0`` (absolute file positioning); other values are
-   ``os.SEEK_CUR`` or ``1`` (seek relative to the current position) and
-   ``os.SEEK_END`` or ``2`` (seek relative to the file's end).
+   Set the file's current position.  *whence* argument is optional and
+   defaults to ``os.SEEK_SET`` or ``0`` (absolute file positioning); other
+   values are ``os.SEEK_CUR`` or ``1`` (seek relative to the current position)
+   and ``os.SEEK_END`` or ``2`` (seek relative to the file's end).
 
 
 .. method:: mmap.size()
@@ -217,15 +227,15 @@ Memory-mapped file objects support the following methods:
 
    Write the bytes in *string* into memory at the current position of the file
    pointer; the file position is updated to point after the bytes that were
-   written. If the mmap was created with :const:`ACCESS_READ`, then writing to it
-   will throw a :exc:`TypeError` exception.
+   written. If the mmap was created with :const:`ACCESS_READ`, then writing to
+   it will throw a :exc:`TypeError` exception.
 
 
 .. method:: mmap.write_byte(byte)
 
-   Write the single-character string *byte* into memory at the current position of
-   the file pointer; the file position is advanced by ``1``. If the mmap was
-   created with :const:`ACCESS_READ`, then writing to it will throw a
-   :exc:`TypeError` exception.
+   Write the single-character string *byte* into memory at the current
+   position of the file pointer; the file position is advanced by ``1``. If
+   the mmap was created with :const:`ACCESS_READ`, then writing to it will
+   throw a :exc:`TypeError` exception.