Merged revisions 58742-58816 via svnmerge from

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

........
  r58745 | georg.brandl | 2007-11-01 10:19:33 -0700 (Thu, 01 Nov 2007) | 2 lines

  #1364: os.lstat is available on Windows too, as an alias to os.stat.
........
  r58750 | christian.heimes | 2007-11-01 12:48:10 -0700 (Thu, 01 Nov 2007) | 1 line

  Backport of import tests for bug http://bugs.python.org/issue1293 and bug http://bugs.python.org/issue1342
........
  r58751 | christian.heimes | 2007-11-01 13:11:06 -0700 (Thu, 01 Nov 2007) | 1 line

  Removed non ASCII text from test as requested by Guido. Sorry :/
........
  r58753 | georg.brandl | 2007-11-01 13:37:02 -0700 (Thu, 01 Nov 2007) | 2 lines

  Fix markup glitch.
........
  r58757 | gregory.p.smith | 2007-11-01 14:08:14 -0700 (Thu, 01 Nov 2007) | 4 lines

  Fix bug introduced in revision 58385.  Database keys could no longer
  have NULL bytes in them.  Replace the errant strdup with a
  malloc+memcpy.  Adds a unit test for the correct behavior.
........
  r58758 | gregory.p.smith | 2007-11-01 14:15:36 -0700 (Thu, 01 Nov 2007) | 3 lines

  Undo revision 58533 58534 fixes.  Those were a workaround for
  a problem introduced by 58385.
........
  r58759 | gregory.p.smith | 2007-11-01 14:17:47 -0700 (Thu, 01 Nov 2007) | 2 lines

  false "fix" undone as correct problem was found and fixed.
........
  r58765 | mark.summerfield | 2007-11-02 01:24:59 -0700 (Fri, 02 Nov 2007) | 3 lines

  Added more file-handling related cross-references.
........
  r58766 | nick.coghlan | 2007-11-02 03:09:12 -0700 (Fri, 02 Nov 2007) | 1 line

  Fix for bug 1705170 - contextmanager swallowing StopIteration (2.5 backport candidate)
........
  r58784 | thomas.heller | 2007-11-02 12:10:24 -0700 (Fri, 02 Nov 2007) | 4 lines

  Issue #1292: On alpha, arm, ppc, and s390 linux systems the
  --with-system-ffi configure option defaults to "yes" because the
  bundled libffi sources are too old.
........
  r58785 | thomas.heller | 2007-11-02 12:11:23 -0700 (Fri, 02 Nov 2007) | 1 line

  Enable the full ctypes c_longdouble tests again.
........
  r58796 | georg.brandl | 2007-11-02 13:06:17 -0700 (Fri, 02 Nov 2007) | 4 lines

  Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
  I hope the concept of hashability is better understandable now.
  Thanks to Tim Hatch for pointing out the flaws here.
........

8 files changed, 43 insertions, 34 deletions

diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 87cccf6..e67c9eb 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -260,7 +260,7 @@ compared to an object of a different type, :exc:`TypeError` is raised unless the
 comparison is ``==`` or ``!=``.  The latter cases return :const:`False` or
 :const:`True`, respectively.
 
-:class:`timedelta` objects are hashable (usable as dictionary keys), support
+:class:`timedelta` objects are :term:`hashable` (usable as dictionary keys), support
 efficient pickling, and in Boolean contexts, a :class:`timedelta` object is
 considered to be true if and only if it isn't equal to ``timedelta(0)``.
 
diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst
index d3724dd..fe956b2 100644
--- a/Doc/library/difflib.rst
+++ b/Doc/library/difflib.rst
@@ -18,7 +18,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
 .. class:: SequenceMatcher
 
    This is a flexible class for comparing pairs of sequences of any type, so long
-   as the sequence elements are hashable.  The basic algorithm predates, and is a
+   as the sequence elements are :term:`hashable`.  The basic algorithm predates, and is a
    little fancier than, an algorithm published in the late 1980's by Ratcliff and
    Obershelp under the hyperbolic name "gestalt pattern matching."  The idea is to
    find the longest contiguous matching subsequence that contains no "junk"
@@ -305,7 +305,7 @@ The :class:`SequenceMatcher` class has this constructor:
    on blanks or hard tabs.
 
    The optional arguments *a* and *b* are sequences to be compared; both default to
-   empty strings.  The elements of both sequences must be hashable.
+   empty strings.  The elements of both sequences must be :term:`hashable`.
 
 :class:`SequenceMatcher` objects have the following methods:
 
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index c7e689d..63f2c33 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -747,9 +747,9 @@ available.  They are listed here in alphabetical order.
    value of ``None`` (if no newlines have been seen yet), ``'\n'``,
    ``'\r'``, ``'\r\n'``, or a tuple containing all the newline types seen.
 
-   See also the :mod:`fileinput` module, the file-related functions in the
-   :mod:`os` module, and the :mod:`os.path` module.
-
+   Python provides many file handling modules including
+   :mod:`fileinput`, :mod:`os`, :mod:`os.path`, :mod:`tempfile`, and
+   :mod:`shutil`.
 
 .. function:: ord(c)
 
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index e627498..a550739 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -11,7 +11,9 @@ functionality than importing a operating system dependent built-in module like
 :mod:`posix` or :mod:`nt`. If you just want to read or write a file see
 :func:`open`, if you want to manipulate paths, see the :mod:`os.path`
 module, and if you want to read all the lines in all the files on the
-command line see the :mod:`fileinput` module.
+command line see the :mod:`fileinput` module. For creating temporary
+files and directories see the :mod:`tempfile` module, and for high-level
+file and directory handling see the :mod:`shutil` module.
 
 This module searches for an operating system dependent built-in module like
 :mod:`mac` or :mod:`posix` and exports the same functions and data as found
@@ -800,8 +802,9 @@ Files and Directories
 
 .. function:: lstat(path)
 
-   Like :func:`stat`, but do not follow symbolic links. Availability: Macintosh,
-   Unix.
+   Like :func:`stat`, but do not follow symbolic links.  This is an alias for
+   :func:`stat` on platforms that do not support symbolic links, such as
+   Windows.
 
 
 .. function:: mkfifo(path[, mode])
@@ -852,6 +855,9 @@ Files and Directories
    ``0777`` (octal).  On some systems, *mode* is ignored.  Where it is used, the
    current umask value is first masked out. Availability: Macintosh, Unix, Windows.
 
+   It is also possible to create temporary directories; see the
+   :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
+
 
 .. function:: makedirs(path[, mode])
 
diff --git a/Doc/library/random.rst b/Doc/library/random.rst
index 4d58e13..f0d5d12 100644
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -54,7 +54,7 @@ Bookkeeping functions:
 .. function:: seed([x])
 
    Initialize the basic random number generator. Optional argument *x* can be any
-   hashable object. If *x* is omitted or ``None``, current system time is used;
+   :term:`hashable` object. If *x* is omitted or ``None``, current system time is used;
    current system time is also used to initialize the generator when the module is
    first imported.  If randomness sources are provided by the operating system,
    they are used instead of the system time (see the :func:`os.urandom` function
@@ -140,7 +140,7 @@ Functions for sequences:
    (the sample) to be partitioned into grand prize and second place winners (the
    subslices).
 
-   Members of the population need not be hashable or unique.  If the population
+   Members of the population need not be :term:`hashable` or unique.  If the population
    contains repeats, then each occurrence is a possible selection in the sample.
 
    To choose a sample from a range of integers, use an :func:`range` object as an
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 927ddb0..3fdaa1f 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -15,7 +15,8 @@
 
 The :mod:`shutil` module offers a number of high-level operations on files and
 collections of files.  In particular, functions are provided  which support file
-copying and removal.
+copying and removal. For operations on individual files, see also the
+:mod:`os` module.
 
 .. warning::
    
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index fb278fa..f557b1f 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -874,7 +874,7 @@ functions based on regular expressions.
    specified, then there is no limit on the number of splits (all possible
    splits are made).
 
-   If *sep is given, consecutive delimiters are not grouped together and are
+   If *sep* is given, consecutive delimiters are not grouped together and are
    deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns
    ``['1', '', '2']``).  The *sep* argument may consist of multiple characters
    (for example, ``'1<>2<>3'.split('<>')`` returns ``['1', '2', '3']``).
@@ -1371,7 +1371,7 @@ Set Types --- :class:`set`, :class:`frozenset`
 
 .. index:: object: set
 
-A :dfn:`set` object is an unordered collection of distinct hashable objects.
+A :dfn:`set` object is an unordered collection of distinct :term:`hashable` objects.
 Common uses include membership testing, removing duplicates from a sequence, and
 computing mathematical operations such as intersection, union, difference, and
 symmetric difference.
@@ -1387,7 +1387,7 @@ There are currently two builtin set types, :class:`set` and :class:`frozenset`.
 The :class:`set` type is mutable --- the contents can be changed using methods
 like :meth:`add` and :meth:`remove`.  Since it is mutable, it has no hash value
 and cannot be used as either a dictionary key or as an element of another set.
-The :class:`frozenset` type is immutable and hashable --- its contents cannot be
+The :class:`frozenset` type is immutable and :term:`hashable` --- its contents cannot be
 altered after it is created; it can therefore be used as a dictionary key or as
 an element of another set.
 
@@ -1487,8 +1487,7 @@ or ``a>b``. Accordingly, sets do not implement the :meth:`__cmp__` method.
 Since sets only define partial ordering (subset relationships), the output of
 the :meth:`list.sort` method is undefined for lists of sets.
 
-Set elements are like dictionary keys; they need to define both :meth:`__hash__`
-and :meth:`__eq__` methods.
+Set elements, like dictionary keys, must be :term:`hashable`.
 
 Binary operations that mix :class:`set` instances with :class:`frozenset` return
 the type of the first operand.  For example: ``frozenset('ab') | set('bc')``
@@ -1559,20 +1558,20 @@ Mapping Types --- :class:`dict`
    statement: del
    builtin: len
 
-A :dfn:`mapping` object maps immutable values to arbitrary objects.  Mappings
-are mutable objects.  There is currently only one standard mapping type, the
-:dfn:`dictionary`.
-(For other containers see the built in :class:`list`,
-:class:`set`, and :class:`tuple` classes, and the :mod:`collections`
-module.)
-
-A dictionary's keys are *almost* arbitrary values.  Only values containing
-lists, dictionaries or other mutable types (that are compared by value rather
-than by object identity) may not be used as keys.  Numeric types used for keys
-obey the normal rules for numeric comparison: if two numbers compare equal (such
-as ``1`` and ``1.0``) then they can be used interchangeably to index the same
-dictionary entry. (Note however, that since computers store floating-point
-numbers as approximations it is usually unwise to use them as dictionary keys.)
+A :dfn:`mapping` object maps :term:`hashable` values to arbitrary objects.
+Mappings are mutable objects.  There is currently only one standard mapping
+type, the :dfn:`dictionary`.  (For other containers see the built in
+:class:`list`, :class:`set`, and :class:`tuple` classes, and the
+:mod:`collections` module.)
+
+A dictionary's keys are *almost* arbitrary values.  Values that are not
+:term:`hashable`, that is, values containing lists, dictionaries or other
+mutable types (that are compared by value rather than by object identity) may
+not be used as keys.  Numeric types used for keys obey the normal rules for
+numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``)
+then they can be used interchangeably to index the same dictionary entry.  (Note
+however, that since computers store floating-point numbers as approximations it
+is usually unwise to use them as dictionary keys.)
 
 Dictionaries can be created by placing a comma-separated list of ``key: value``
 pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
@@ -1821,7 +1820,10 @@ created with the built-in :func:`file` and (more usually) :func:`open`
 constructors described in the :ref:`built-in-funcs` section. [#]_ File
 objects are also returned by some other built-in functions and methods,
 such as :func:`os.popen` and :func:`os.fdopen` and the :meth:`makefile`
-method of socket objects.
+method of socket objects. Temporary files can be created using the
+:mod:`tempfile` module, and high-level file operations such as copying,
+moving, and deleting files and directories can be achieved with the
+:mod:`shutil` module.
 
 When a file operation fails for an I/O-related reason, the exception
 :exc:`IOError` is raised.  This includes situations where the operation is not
diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
index 6c7c919..3adf318 100644
--- a/Doc/library/weakref.rst
+++ b/Doc/library/weakref.rst
@@ -85,7 +85,7 @@ Extension types can easily be made to support weak references; see
    but cannot be propagated; they are handled in exactly the same way as exceptions
    raised from an object's :meth:`__del__` method.
 
-   Weak references are hashable if the *object* is hashable.  They will maintain
+   Weak references are :term:`hashable` if the *object* is hashable.  They will maintain
    their hash value even after the *object* was deleted.  If :func:`hash` is called
    the first time only after the *object* was deleted, the call will raise
    :exc:`TypeError`.
@@ -104,7 +104,7 @@ Extension types can easily be made to support weak references; see
    the proxy in most contexts instead of requiring the explicit dereferencing used
    with weak reference objects.  The returned object will have a type of either
    ``ProxyType`` or ``CallableProxyType``, depending on whether *object* is
-   callable.  Proxy objects are not hashable regardless of the referent; this
+   callable.  Proxy objects are not :term:`hashable` regardless of the referent; this
    avoids a number of problems related to their fundamentally mutable nature, and
    prevent their use as dictionary keys.  *callback* is the same as the parameter
    of the same name to the :func:`ref` function.