Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from

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

........
  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.
........
  r85613 | georg.brandl | 2010-10-17 11:43:35 +0200 (So, 17 Okt 2010) | 1 line

  Fix hmac docs: it takes and returns bytes, except for hexdigest().
........
  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.
........
  r85617 | georg.brandl | 2010-10-17 12:09:06 +0200 (So, 17 Okt 2010) | 1 line

  #5212: md5 weaknesses do not affect hmac, so remove the note about that.
........
  r85618 | georg.brandl | 2010-10-17 12:14:38 +0200 (So, 17 Okt 2010) | 1 line

  #9086: correct wrong terminology about linking with pythonXY.dll.
........
  r85619 | georg.brandl | 2010-10-17 12:15:50 +0200 (So, 17 Okt 2010) | 1 line

  Make file names consistent.
........
  r85620 | georg.brandl | 2010-10-17 12:22:28 +0200 (So, 17 Okt 2010) | 1 line

  Remove second parser module example; it referred to non-readily-available example files, and this kind of discovery is much better done with the AST nowadays anyway.
........
  r85621 | georg.brandl | 2010-10-17 12:24:54 +0200 (So, 17 Okt 2010) | 1 line

  #9105: move pickle warning to a bit more prominent location.
........
  r85622 | georg.brandl | 2010-10-17 12:28:04 +0200 (So, 17 Okt 2010) | 1 line

  #9112: document error() and exit() methods of ArgumentParser.
........
  r85624 | georg.brandl | 2010-10-17 12:34:28 +0200 (So, 17 Okt 2010) | 1 line

  Some markup and style fixes in argparse docs.
........
  r85626 | georg.brandl | 2010-10-17 12:38:20 +0200 (So, 17 Okt 2010) | 1 line

  #9117: fix syntax for class definition.
........
  r85627 | georg.brandl | 2010-10-17 12:44:11 +0200 (So, 17 Okt 2010) | 1 line

  #9138: reword introduction to classes in Python.
........
  r85629 | georg.brandl | 2010-10-17 12:51:45 +0200 (So, 17 Okt 2010) | 1 line

  #5962: clarify sys.exit() vs. threads.
........
  r85631 | georg.brandl | 2010-10-17 12:53:54 +0200 (So, 17 Okt 2010) | 1 line

  Fix capitalization.
........
  r85633 | georg.brandl | 2010-10-17 12:59:41 +0200 (So, 17 Okt 2010) | 1 line

  #9204: remove mentions of removed types in the types module.
........
  r85635 | georg.brandl | 2010-10-17 13:03:22 +0200 (So, 17 Okt 2010) | 1 line

  #5121: fix claims about default values leading to segfaults.
........
  r85636 | georg.brandl | 2010-10-17 13:06:14 +0200 (So, 17 Okt 2010) | 1 line

  #9237: document sys.call_tracing().
........
  r85638 | georg.brandl | 2010-10-17 13:13:37 +0200 (So, 17 Okt 2010) | 1 line

  Port changes to pickle docs apparently lost in py3k.
........
  r85639 | georg.brandl | 2010-10-17 13:23:56 +0200 (So, 17 Okt 2010) | 1 line

  Make twisted example a bit more logical.
........
  r85641 | georg.brandl | 2010-10-17 13:29:07 +0200 (So, 17 Okt 2010) | 1 line

  Fix documentation of dis.opmap direction.
........
  r85642 | georg.brandl | 2010-10-17 13:36:28 +0200 (So, 17 Okt 2010) | 1 line

  #9730: fix example.
........

13 files changed, 37 insertions, 50 deletions

diff --git a/Doc/c-api/bytearray.rst b/Doc/c-api/bytearray.rst
index 4bc5459..5e11d8a 100644
--- a/Doc/c-api/bytearray.rst
+++ b/Doc/c-api/bytearray.rst
@@ -16,7 +16,8 @@ Byte Array Objects
 .. cvar:: PyTypeObject PyByteArray_Type
 
    This instance of :ctype:`PyTypeObject` represents the Python bytearray type;
-   it is the same object as ``bytearray`` in the Python layer.
+   it is the same object as :class:`bytearray` in the Python layer.
+
 
 Type check macros
 ^^^^^^^^^^^^^^^^^
diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst
index b66047b..abd8744 100644
--- a/Doc/c-api/bytes.rst
+++ b/Doc/c-api/bytes.rst
@@ -18,10 +18,8 @@ called with a non-bytes parameter.
 
 .. cvar:: PyTypeObject PyBytes_Type
 
-   .. index:: single: BytesType (in module types)
-
    This instance of :ctype:`PyTypeObject` represents the Python bytes type; it
-   is the same object as ``bytes`` in the Python layer. .
+   is the same object as :class:`bytes` in the Python layer.
 
 
 .. cfunction:: int PyBytes_Check(PyObject *o)
diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
index 3508a03..0bcdf4d 100644
--- a/Doc/c-api/complex.rst
+++ b/Doc/c-api/complex.rst
@@ -82,7 +82,7 @@ Complex Numbers as Python Objects
 .. cvar:: PyTypeObject PyComplex_Type
 
    This instance of :ctype:`PyTypeObject` represents the Python complex number
-   type. It is the same object as ``complex`` and ``types.ComplexType``.
+   type. It is the same object as :class:`complex` in the Python layer.
 
 
 .. cfunction:: int PyComplex_Check(PyObject *p)
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index 5943887..5d355d1 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -15,13 +15,8 @@ Dictionary Objects
 
 .. cvar:: PyTypeObject PyDict_Type
 
-   .. index::
-      single: DictType (in module types)
-      single: DictionaryType (in module types)
-
    This instance of :ctype:`PyTypeObject` represents the Python dictionary
-   type.  This is exposed to Python programs as ``dict`` and
-   ``types.DictType``.
+   type.  This is the same object as :class:`dict` in the Python layer.
 
 
 .. cfunction:: int PyDict_Check(PyObject *p)
diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
index e2e4b73..93769aa 100644
--- a/Doc/c-api/float.rst
+++ b/Doc/c-api/float.rst
@@ -15,10 +15,8 @@ Floating Point Objects
 
 .. cvar:: PyTypeObject PyFloat_Type
 
-   .. index:: single: FloatType (in modules types)
-
    This instance of :ctype:`PyTypeObject` represents the Python floating point
-   type.  This is the same object as ``float`` and ``types.FloatType``.
+   type.  This is the same object as :class:`float` in the Python layer.
 
 
 .. cfunction:: int PyFloat_Check(PyObject *p)
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 4b67912..1708a85 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/c-api/list.rst b/Doc/c-api/list.rst
index 89f0f9d..dba0f81 100644
--- a/Doc/c-api/list.rst
+++ b/Doc/c-api/list.rst
@@ -15,8 +15,8 @@ List Objects
 
 .. cvar:: PyTypeObject PyList_Type
 
-   This instance of :ctype:`PyTypeObject` represents the Python list type.  This
-   is the same object as ``list`` in the Python layer.
+   This instance of :ctype:`PyTypeObject` represents the Python list type.
+   This is the same object as :class:`list` in the Python layer.
 
 
 .. cfunction:: int PyList_Check(PyObject *p)
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index 9a3d1f1..9f8e3c5 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -18,7 +18,7 @@ All integers are implemented as "long" integer objects of arbitrary size.
 .. cvar:: PyTypeObject PyLong_Type
 
    This instance of :ctype:`PyTypeObject` represents the Python integer type.
-   This is the same object as ``int``.
+   This is the same object as :class:`int` in the Python layer.
 
 
 .. cfunction:: int PyLong_Check(PyObject *p)
diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
index f8f2a44..f17915f 100644
--- a/Doc/c-api/slice.rst
+++ b/Doc/c-api/slice.rst
@@ -8,10 +8,8 @@ Slice Objects
 
 .. cvar:: PyTypeObject PySlice_Type
 
-   .. index:: single: SliceType (in module types)
-
-   The type object for slice objects.  This is the same as ``slice`` and
-   ``types.SliceType``.
+   The type object for slice objects.  This is the same as :class:`slice` in the
+   Python layer.
 
 
 .. cfunction:: int PySlice_Check(PyObject *ob)
diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index c1f8e12..612acc7 100644
--- a/Doc/c-api/tuple.rst
+++ b/Doc/c-api/tuple.rst
@@ -15,10 +15,8 @@ Tuple Objects
 
 .. cvar:: PyTypeObject PyTuple_Type
 
-   .. index:: single: TupleType (in module types)
-
-   This instance of :ctype:`PyTypeObject` represents the Python tuple type; it is
-   the same object as ``tuple`` and ``types.TupleType`` in the Python layer..
+   This instance of :ctype:`PyTypeObject` represents the Python tuple type; it
+   is the same object as :class:`tuple` in the Python layer.
 
 
 .. cfunction:: int PyTuple_Check(PyObject *p)
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index d0edd55..d2a5676 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -15,10 +15,8 @@ Type Objects
 
 .. cvar:: PyObject* PyType_Type
 
-   .. index:: single: TypeType (in module types)
-
-   This is the type object for type objects; it is the same object as ``type`` and
-   ``types.TypeType`` in the Python layer.
+   This is the type object for type objects; it is the same object as
+   :class:`type` in the Python layer.
 
 
 .. cfunction:: int PyType_Check(PyObject *o)
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 14d1c27..de493de 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -204,7 +204,7 @@ APIs:
 
 .. cfunction:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
 
-   Create a Unicode Object from the Py_UNICODE buffer *u* of the given size. *u*
+   Create a Unicode object from the Py_UNICODE buffer *u* of the given size. *u*
    may be *NULL* which causes the contents to be undefined. It is the user's
    responsibility to fill in the needed data.  The buffer is copied into the new
    object. If the buffer is not *NULL*, the return value might be a shared object.
@@ -214,7 +214,7 @@ APIs:
 
 .. cfunction:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
 
-   Create a Unicode Object from the char buffer *u*.  The bytes will be interpreted
+   Create a Unicode object from the char buffer *u*.  The bytes will be interpreted
    as being UTF-8 encoded.  *u* may also be *NULL* which
    causes the contents to be undefined. It is the user's responsibility to fill in
    the needed data.  The buffer is copied into the new object. If the buffer is not
diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index d716a46..66789a9 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -123,13 +123,13 @@ the same library that the Python runtime is using.
 
 .. cfunction:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
 
-   Read and execute a single statement from a file associated with an interactive
-   device according to the *flags* argument.  If *filename* is *NULL*, ``"???"`` is
-   used instead.  The user will be prompted using ``sys.ps1`` and ``sys.ps2``.
-   Returns ``0`` when the input was executed successfully, ``-1`` if there was an
-   exception, or an error code from the :file:`errcode.h` include file distributed
-   as part of Python if there was a parse error.  (Note that :file:`errcode.h` is
-   not included by :file:`Python.h`, so must be included specifically if needed.)
+   Read and execute a single statement from a file associated with an
+   interactive device according to the *flags* argument.  The user will be
+   prompted using ``sys.ps1`` and ``sys.ps2``.  Returns ``0`` when the input was
+   executed successfully, ``-1`` if there was an exception, or an error code
+   from the :file:`errcode.h` include file distributed as part of Python if
+   there was a parse error.  (Note that :file:`errcode.h` is not included by
+   :file:`Python.h`, so must be included specifically if needed.)
 
 
 .. cfunction:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)
@@ -138,11 +138,11 @@ the same library that the Python runtime is using.
    leaving *flags* set to *NULL*.
 
 
-.. cfunction:: int PyRun_InteractiveLoopFlags(FILE *fp,  const char *filename, PyCompilerFlags *flags)
+.. cfunction:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
 
    Read and execute statements from a file associated with an interactive device
-   until EOF is reached.  If *filename* is *NULL*, ``"???"`` is used instead.  The
-   user will be prompted using ``sys.ps1`` and ``sys.ps2``.  Returns ``0`` at EOF.
+   until EOF is reached.  The user will be prompted using ``sys.ps1`` and
+   ``sys.ps2``.  Returns ``0`` at EOF.
 
 
 .. cfunction:: struct _node* PyParser_SimpleParseString(const char *str, int start)