Merged revisions 85548,85572-85573,85606,85609-85612,85614-85616 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r85548 | georg.brandl | 2010-10-15 21:46:19 +0200 (Fr, 15 Okt 2010) | 1 line

  #10072: assume a bit less knowledge of the FTP protocol in the ftplib docs.
........
  r85572 | georg.brandl | 2010-10-16 20:51:05 +0200 (Sa, 16 Okt 2010) | 1 line

  #10122: typo fix.
........
  r85573 | georg.brandl | 2010-10-16 20:53:08 +0200 (Sa, 16 Okt 2010) | 1 line

  #10124: typo fix.
........
  r85606 | georg.brandl | 2010-10-17 08:32:59 +0200 (So, 17 Okt 2010) | 1 line

  #10058: tweak wording about exception returns.
........
  r85609 | georg.brandl | 2010-10-17 11:19:03 +0200 (So, 17 Okt 2010) | 1 line

  #8556: use less confusing mapping key in example.
........
  r85610 | georg.brandl | 2010-10-17 11:23:05 +0200 (So, 17 Okt 2010) | 1 line

  #8686: remove potentially confusing wording that does not add any value.
........
  r85611 | georg.brandl | 2010-10-17 11:33:24 +0200 (So, 17 Okt 2010) | 1 line

  #8811: small fixes to sqlite3 docs.
........
  r85612 | georg.brandl | 2010-10-17 11:37:54 +0200 (So, 17 Okt 2010) | 1 line

  #8855: add shelve security warning.
........
  r85614 | georg.brandl | 2010-10-17 11:46:11 +0200 (So, 17 Okt 2010) | 1 line

  #8968: add actual name of token constants.
........
  r85615 | georg.brandl | 2010-10-17 12:05:13 +0200 (So, 17 Okt 2010) | 1 line

  #459007: merge info from PC/getpathp.c and using/windows.rst to document the forming of sys.path under Windows.
........
  r85616 | georg.brandl | 2010-10-17 12:07:29 +0200 (So, 17 Okt 2010) | 1 line

  Fix copy-paste error in example.
........

11 files changed, 157 insertions, 69 deletions

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 5ea6dd303c..b2e9e0a0d1 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -361,15 +361,16 @@ traceback.
 
 .. index:: single: PyErr_Occurred()
 
-For C programmers, however, error checking always has to be explicit.   All
-functions in the Python/C API can raise exceptions, unless an  explicit claim is
-made otherwise in a function's documentation.  In  general, when a function
-encounters an error, it sets an exception,  discards any object references that
-it owns, and returns an  error indicator --- usually *NULL* or ``-1``.  A few
-functions  return a Boolean true/false result, with false indicating an error.
-Very few functions return no explicit error indicator or have an  ambiguous
-return value, and require explicit testing for errors with
-:cfunc:`PyErr_Occurred`.
+For C programmers, however, error checking always has to be explicit.  All
+functions in the Python/C API can raise exceptions, unless an explicit claim is
+made otherwise in a function's documentation.  In general, when a function
+encounters an error, it sets an exception, discards any object references that
+it owns, and returns an error indicator.  If not documented otherwise, this
+indicator is either *NULL* or ``-1``, depending on the function's return type.
+A few functions return a Boolean true/false result, with false indicating an
+error.  Very few functions return no explicit error indicator or have an
+ambiguous return value, and require explicit testing for errors with
+:cfunc:`PyErr_Occurred`.  These exceptions are always explicitly documented.
 
 .. index::
    single: PyErr_SetString()
diff --git a/Doc/howto/cporting.rst b/Doc/howto/cporting.rst
index c0b59338ba..8030f136de 100644
--- a/Doc/howto/cporting.rst
+++ b/Doc/howto/cporting.rst
@@ -48,9 +48,9 @@ Python 3.0's :func:`str` (``PyString_*`` functions in C) type is equivalent to
 compatibility with 3.0, :ctype:`PyUnicode` should be used for textual data and
 :ctype:`PyBytes` for binary data.  It's also important to remember that
 :ctype:`PyBytes` and :ctype:`PyUnicode` in 3.0 are not interchangeable like
-:ctype:`PyString` and :ctype:`PyString` are in 2.x.  The following example shows
-best practices with regards to :ctype:`PyUnicode`, :ctype:`PyString`, and
-:ctype:`PyBytes`. ::
+:ctype:`PyString` and :ctype:`PyUnicode` are in 2.x.  The following example
+shows best practices with regards to :ctype:`PyUnicode`, :ctype:`PyString`,
+and :ctype:`PyBytes`. ::
 
    #include "stdlib.h"
    #include "Python.h"
diff --git a/Doc/library/audioop.rst b/Doc/library/audioop.rst
index b497e1f8e0..29c3914e12 100644
--- a/Doc/library/audioop.rst
+++ b/Doc/library/audioop.rst
@@ -236,8 +236,8 @@ and recombined later.  Here is an example of how to do that::
    def mul_stereo(sample, width, lfactor, rfactor):
        lsample = audioop.tomono(sample, width, 1, 0)
        rsample = audioop.tomono(sample, width, 0, 1)
-       lsample = audioop.mul(sample, width, lfactor)
-       rsample = audioop.mul(sample, width, rfactor)
+       lsample = audioop.mul(lsample, width, lfactor)
+       rsample = audioop.mul(rsample, width, rfactor)
        lsample = audioop.tostereo(lsample, width, 1, 0)
        rsample = audioop.tostereo(rsample, width, 0, 1)
        return audioop.add(lsample, rsample, width)
diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst
index 899d7e5231..d51e230f69 100644
--- a/Doc/library/difflib.rst
+++ b/Doc/library/difflib.rst
@@ -528,16 +528,11 @@ The :class:`SequenceMatcher` class has this constructor:
 
       Return an upper bound on :meth:`ratio` relatively quickly.
 
-      This isn't defined beyond that it is an upper bound on :meth:`ratio`, and
-      is faster to compute.
-
 
    .. method:: real_quick_ratio()
 
       Return an upper bound on :meth:`ratio` very quickly.
 
-      This isn't defined beyond that it is an upper bound on :meth:`ratio`, and
-      is faster to compute than either :meth:`ratio` or :meth:`quick_ratio`.
 
 The three methods that return the ratio of matching to total characters can give
 different results due to differing levels of approximation, although
diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index 4b25d85d96..b6db98371f 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -91,18 +91,21 @@ The module defines the following items:
 
 .. exception:: error_temp
 
-   Exception raised when an error code in the range 400--499 is received.
+   Exception raised when an error code signifying a temporary error (response
+   codes in the range 400--499) is received.
 
 
 .. exception:: error_perm
 
-   Exception raised when an error code in the range 500--599 is received.
+   Exception raised when an error code signifying a permanent error (response
+   codes in the range 500--599) is received.
 
 
 .. exception:: error_proto
 
-   Exception raised when a reply is received from the server that does not
-   begin with a digit in the range 1--5.
+   Exception raised when a reply is received from the server that does not fit
+   the response specifications of the File Transfer Protocol, i.e. begin with a
+   digit in the range 1--5.
 
 
 .. data:: all_errors
@@ -198,9 +201,9 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
 
 .. method:: FTP.voidcmd(command)
 
-   Send a simple command string to the server and handle the response. Return
-   nothing if a response code in the range 200--299 is received. Raise an exception
-   otherwise.
+   Send a simple command string to the server and handle the response.  Return
+   nothing if a response code corresponding to success (codes in the range
+   200--299) is received.  Raise :exc:`error_reply` otherwise.
 
 
 .. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
@@ -220,9 +223,11 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
    Retrieve a file or directory listing in ASCII transfer mode.  *command*
    should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or a
    command such as ``LIST``, ``NLST`` or ``MLSD`` (usually just the string
-   ``'LIST'``).  The *callback* function is called for each line with a
-   string argument containing the line with the trailing CRLF stripped.
-   The default *callback* prints the line to ``sys.stdout``.
+   ``'LIST'``).  ``LIST`` retrieves a list of files and information about those files.
+   ``NLST`` retrieves a list of file names.  On some servers, ``MLSD`` retrieves
+   a machine readable list of files and information about those files.  The *callback*
+   function is called for each line with a string argument containing the line with
+   the trailing CRLF stripped.  The default *callback* prints the line to ``sys.stdout``.
 
 
 .. method:: FTP.set_pasv(boolean)
@@ -293,10 +298,10 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
 
 .. method:: FTP.nlst(argument[, ...])
 
-   Return a list of files as returned by the ``NLST`` command.  The optional
-   *argument* is a directory to list (default is the current server directory).
-   Multiple arguments can be used to pass non-standard options to the ``NLST``
-   command.
+   Return a list of file names as returned by the ``NLST`` command.  The
+   optional *argument* is a directory to list (default is the current server
+   directory).  Multiple arguments can be used to pass non-standard options to
+   the ``NLST`` command.
 
 
 .. method:: FTP.dir(argument[, ...])
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 34e1dbe93f..4b63c9f70e 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -514,7 +514,7 @@ available.  They are listed here in alphabetical order.
 
 .. function:: getattr(object, name[, default])
 
-   Return the value of the named attributed of *object*.  *name* must be a string.
+   Return the value of the named attribute of *object*.  *name* must be a string.
    If the string is the name of one of the object's attributes, the result is the
    value of that attribute.  For example, ``getattr(x, 'foobar')`` is equivalent to
    ``x.foobar``.  If the named attribute does not exist, *default* is returned if
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index 3616724319..4f2d94be75 100644
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -50,6 +50,11 @@ lots of shared  sub-objects.  The keys are ordinary strings.
       :meth:`close` explicitly when you don't need it any more, or use a
       :keyword:`with` statement with :func:`contextlib.closing`.
 
+.. warning::
+
+   Because the :mod:`shelve` module is backed by :mod:`pickle`, it is insecure
+   to load a shelf from an untrusted source.  Like with pickle, loading a shelf
+   can execute arbitrary code.
 
 Shelf objects support all methods supported by dictionaries.  This eases the
 transition from dictionary based scripts to those requiring persistent storage.
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index cf2e678cb6..59ed0971be 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -258,22 +258,21 @@ Connection Objects
 .. method:: Connection.execute(sql, [parameters])
 
    This is a nonstandard shortcut that creates an intermediate cursor object by
-   calling the cursor method, then calls the cursor's
-   :meth:`execute<Cursor.execute>` method with the parameters given.
+   calling the cursor method, then calls the cursor's :meth:`execute
+   <Cursor.execute>` method with the parameters given.
 
 
 .. method:: Connection.executemany(sql, [parameters])
 
    This is a nonstandard shortcut that creates an intermediate cursor object by
-   calling the cursor method, then calls the cursor's
-   :meth:`executemany<Cursor.executemany>` method with the parameters given.
+   calling the cursor method, then calls the cursor's :meth:`executemany
+   <Cursor.executemany>` method with the parameters given.
 
 .. method:: Connection.executescript(sql_script)
 
    This is a nonstandard shortcut that creates an intermediate cursor object by
-   calling the cursor method, then calls the cursor's
-   :meth:`executescript<Cursor.executescript>` method with the parameters
-   given.
+   calling the cursor method, then calls the cursor's :meth:`executescript
+   <Cursor.executescript>` method with the parameters given.
 
 
 .. method:: Connection.create_function(name, num_params, func)
@@ -374,7 +373,7 @@ Connection Objects
 
    This routine allows/disallows the SQLite engine to load SQLite extensions
    from shared libraries.  SQLite extensions can define new functions,
-   aggregates or whole new virtual table implementations. One well-known
+   aggregates or whole new virtual table implementations.  One well-known
    extension is the fulltext-search extension distributed with SQLite.
 
    .. literalinclude:: ../includes/sqlite3/load_extension.py
@@ -383,9 +382,9 @@ Connection Objects
 
    .. versionadded:: 2.7
 
-   This routine loads a SQLite extension from a shared library. You have to
-   enable extension loading with ``enable_load_extension`` before you can use
-   this routine.
+   This routine loads a SQLite extension from a shared library.  You have to
+   enable extension loading with :meth:`enable_load_extension` before you can
+   use this routine.
 
 .. attribute:: Connection.row_factory
 
@@ -458,9 +457,9 @@ Connection Objects
 Cursor Objects
 --------------
 
-A :class:`Cursor` instance has the following attributes and methods:
+.. class:: Cursor
 
-   A SQLite database cursor has the following attributes and methods:
+   A :class:`Cursor` instance has the following attributes and methods.
 
 .. method:: Cursor.execute(sql, [parameters])
 
@@ -894,4 +893,3 @@ threads. If you still try to do so, you will get an exception at runtime.
 
 The only exception is calling the :meth:`~Connection.interrupt` method, which
 only makes sense to call from a different thread.
-
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 7cb92ee19f..d99d18489b 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1356,8 +1356,8 @@ formats in the string *must* include a parenthesised mapping key into that
 dictionary inserted immediately after the ``'%'`` character. The mapping key
 selects the value to be formatted from the mapping.  For example:
 
-   >>> print '%(language)s has %(#)03d quote types.' % \
-   ...       {'language': "Python", "#": 2}
+   >>> print '%(language)s has %(number)03d quote types.' % \
+   ...       {"language": "Python", "number": 2}
    Python has 002 quote types.
 
 In this case no ``*`` specifiers may occur in a format (since they require a
diff --git a/Doc/library/token.rst b/Doc/library/token.rst
index 5bf0ea80e2..00972b096e 100644
--- a/Doc/library/token.rst
+++ b/Doc/library/token.rst
@@ -13,8 +13,8 @@ in the Python distribution for the definitions of the names in the context of
 the language grammar.  The specific numeric values which the names map to may
 change between Python versions.
 
-This module also provides one data object and some functions.  The functions
-mirror definitions in the Python C header files.
+The module also provides a mapping from numeric codes to names and some
+functions.  The functions mirror definitions in the Python C header files.
 
 
 .. data:: tok_name
@@ -39,6 +39,65 @@ mirror definitions in the Python C header files.
    Return true if *x* is the marker indicating the end of input.
 
 
+The token constants are:
+
+.. data:: ENDMARKER
+          NAME
+          NUMBER
+          STRING
+          NEWLINE
+          INDENT
+          DEDENT
+          LPAR
+          RPAR
+          LSQB
+          RSQB
+          COLON
+          COMMA
+          SEMI
+          PLUS
+          MINUS
+          STAR
+          SLASH
+          VBAR
+          AMPER
+          LESS
+          GREATER
+          EQUAL
+          DOT
+          PERCENT
+          BACKQUOTE
+          LBRACE
+          RBRACE
+          EQEQUAL
+          NOTEQUAL
+          LESSEQUAL
+          GREATEREQUAL
+          TILDE
+          CIRCUMFLEX
+          LEFTSHIFT
+          RIGHTSHIFT
+          DOUBLESTAR
+          PLUSEQUAL
+          MINEQUAL
+          STAREQUAL
+          SLASHEQUAL
+          PERCENTEQUAL
+          AMPEREQUAL
+          VBAREQUAL
+          CIRCUMFLEXEQUAL
+          LEFTSHIFTEQUAL
+          RIGHTSHIFTEQUAL
+          DOUBLESTAREQUAL
+          DOUBLESLASH
+          DOUBLESLASHEQUAL
+          AT
+          OP
+          ERRORTOKEN
+          N_TOKENS
+          NT_OFFSET
+
+
 .. seealso::
 
    Module :mod:`parser`
diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst
index 52349d78b4..8a91ef7f00 100644
--- a/Doc/using/windows.rst
+++ b/Doc/using/windows.rst
@@ -158,23 +158,48 @@ installation directory.  So, if you had installed Python to
 :file:`C:\\Python\\Lib\\` and third-party modules should be stored in
 :file:`C:\\Python\\Lib\\site-packages\\`.
 
-.. `` this fixes syntax highlighting errors in some editors due to the \\ hackery
-
-You can add folders to your search path to make Python's import mechanism search
-in these directories as well.  Use :envvar:`PYTHONPATH`, as described in
-:ref:`using-on-envvars`, to modify :data:`sys.path`.  On Windows, paths are
-separated by semicolons, though, to distinguish them from drive identifiers
-(:file:`C:\\` etc.).
-
-.. ``
-
-Modifying the module search path can also be done through the Windows registry
-under the key :file:`HKLM\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath`.
-Subkeys which have semicolon-delimited path strings as their default value will
-cause each path to be searched.  Multiple subkeys can be created and are
-appended to the path in alphabetical order.  A convenient registry editor is
-:program:`regedit` (start it by typing "regedit" into :menuselection:`Start -->
-Run`).
+This is how :data:`sys.path` is populated on Windows:
+
+* An empty entry is added at the start, which corresponds to the current
+  directory.
+
+* If the environment variable :envvar:`PYTHONPATH` exists, as described in
+  :ref:`using-on-envvars`, its entries are added next.  Note that on Windows,
+  paths in this variable must be separated by semicolons, to distinguish them
+  from the colon used in drive identifiers (``C:\`` etc.).
+
+* Additional "application paths" can be added in the registry as subkeys of
+  :samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the
+  ``HKEY_CURRENT_USER`` and ``HKEY_LOCAL_MACHINE`` hives.  Subkeys which have
+  semicolon-delimited path strings as their default value will cause each path
+  to be added to :data:`sys.path`.  (Note that all known installers only use
+  HKLM, so HKCU is typically empty.)
+
+* If the environment variable :envvar:`PYTHONHOME` is set, it is assumed as
+  "Python Home".  Otherwise, the path of the main Python executable is used to
+  locate a "landmark file" (``Lib\os.py``) to deduce the "Python Home".  If a
+  Python home is found, the relevant sub-directories added to :data:`sys.path`
+  (``Lib``, ``plat-win``, etc) are based on that folder.  Otherwise, the core
+  Python path is constructed from the PythonPath stored in the registry.
+
+* If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in
+  the environment, and no registry entries can be found, a default path with
+  relative entries is used (e.g. ``.\Lib;.\plat-win``, etc).
+
+The end result of all this is:
+
+* When running :file:`python.exe`, or any other .exe in the main Python
+  directory (either an installed version, or directly from the PCbuild
+  directory), the core path is deduced, and the core paths in the registry are
+  ignored.  Other "application paths" in the registry are always read.
+
+* When Python is hosted in another .exe (different directory, embedded via COM,
+  etc), the "Python Home" will not be deduced, so the core path from the
+  registry is used.  Other "application paths" in the registry are always read.
+
+* If Python can't find its home and there is no registry (eg, frozen .exe, some
+  very strange installation setup) you get a path with some default, but
+  relative, paths.
 
 
 Executing scripts