Merged revisions 82805-82806,83523-83527,83536,83538,83542,83546-83548,83550-83555,83558,83560 via svnmerge from

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

........
  r82805 | georg.brandl | 2010-07-11 11:42:10 +0200 (So, 11 Jul 2010) | 1 line

  #7935: cross-reference to ast.literal_eval() from eval() docs.
........
  r82806 | georg.brandl | 2010-07-11 12:22:44 +0200 (So, 11 Jul 2010) | 1 line

  #9223: link to Command class reference, and move Command interface docs nearer to class docs.
........
  r83523 | georg.brandl | 2010-08-02 14:06:18 +0200 (Mo, 02 Aug 2010) | 1 line

  #9209 and #7781: fix two crashes in pstats interactive browser.
........
  r83524 | georg.brandl | 2010-08-02 14:20:23 +0200 (Mo, 02 Aug 2010) | 1 line

  #9428: fix running scripts from profile/cProfile with their own name and the right namespace.  Same fix as for trace.py in #1690103.
........
  r83525 | georg.brandl | 2010-08-02 14:36:24 +0200 (Mo, 02 Aug 2010) | 1 line

  Get rid of spurious "threading" entries in trace output.
........
  r83526 | georg.brandl | 2010-08-02 14:40:22 +0200 (Mo, 02 Aug 2010) | 1 line

  Fix softspace relic.
........
  r83527 | georg.brandl | 2010-08-02 14:48:46 +0200 (Mo, 02 Aug 2010) | 1 line

  #3821: beginnings of a trace.py unittest.
........
  r83536 | georg.brandl | 2010-08-02 19:49:25 +0200 (Mo, 02 Aug 2010) | 1 line

  #8578: mention danger of not incref'ing weak referenced object.
........
  r83538 | georg.brandl | 2010-08-02 20:10:13 +0200 (Mo, 02 Aug 2010) | 1 line

  #6928: fix class docs w.r.t. new metaclasses.
........
  r83542 | georg.brandl | 2010-08-02 20:56:54 +0200 (Mo, 02 Aug 2010) | 1 line

  Move test_SimpleHTTPServer into test_httpservers.
........
  r83546 | georg.brandl | 2010-08-02 21:16:34 +0200 (Mo, 02 Aug 2010) | 1 line

  #7973: Fix distutils options spelling.
........
  r83547 | georg.brandl | 2010-08-02 21:19:26 +0200 (Mo, 02 Aug 2010) | 1 line

  #7386: add example that shows that trailing path separators are stripped.
........
  r83548 | georg.brandl | 2010-08-02 21:23:34 +0200 (Mo, 02 Aug 2010) | 1 line

  #8172: how does one use a property?
........
  r83550 | georg.brandl | 2010-08-02 21:32:43 +0200 (Mo, 02 Aug 2010) | 1 line

  #9451: strengthen warning about __*__ special name usage.
........
  r83551 | georg.brandl | 2010-08-02 21:35:06 +0200 (Mo, 02 Aug 2010) | 1 line

  Remove XXX comment that was displayed.
........
  r83552 | georg.brandl | 2010-08-02 21:36:36 +0200 (Mo, 02 Aug 2010) | 1 line

  #9438: clarify that constant names also cannot be assigned as attributes.
........
  r83553 | georg.brandl | 2010-08-02 21:39:17 +0200 (Mo, 02 Aug 2010) | 1 line

  Remove redundant information.
........
  r83554 | georg.brandl | 2010-08-02 21:43:05 +0200 (Mo, 02 Aug 2010) | 1 line

  #7280: note about nasmw.exe.
........
  r83555 | georg.brandl | 2010-08-02 21:44:48 +0200 (Mo, 02 Aug 2010) | 1 line

  #8861: remove unused variable.
........
  r83558 | georg.brandl | 2010-08-02 22:05:19 +0200 (Mo, 02 Aug 2010) | 1 line

  #8648: document UTF-7 codec functions.
........
  r83560 | georg.brandl | 2010-08-02 22:16:18 +0200 (Mo, 02 Aug 2010) | 1 line

  #9087: update json docstrings -- unicode and long do not exist anymore.
........

2 files changed, 40 insertions, 1 deletions

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 32a7ca9..4db7671 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -641,6 +641,38 @@ These are the UTF-16 codec APIs:
    Return *NULL* if an exception was raised by the codec.
 
 
+UTF-7 Codecs
+""""""""""""
+
+These are the UTF-7 codec APIs:
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)
+
+   Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string
+   *s*.  Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
+
+   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF7`.  If
+   *consumed* is not *NULL*, trailing incomplete UTF-7 base-64 sections will not
+   be treated as an error.  Those bytes will not be decoded and the number of
+   bytes that have been decoded will be stored in *consumed*.
+
+
+.. cfunction:: PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)
+
+   Encode the :ctype:`Py_UNICODE` buffer of the given size using UTF-7 and
+   return a Python bytes object.  Return *NULL* if an exception was raised by
+   the codec.
+
+   If *base64SetO* is nonzero, "Set O" (punctuation that has no otherwise
+   special meaning) will be encoded in base-64.  If *base64WhiteSpace* is
+   nonzero, whitespace will be encoded in base-64.  Both are set to zero for the
+   Python "utf-7" codec.
+
+
 Unicode-Escape Codecs
 """""""""""""""""""""
 
diff --git a/Doc/c-api/weakref.rst b/Doc/c-api/weakref.rst
index 081419d..8a36110 100644
--- a/Doc/c-api/weakref.rst
+++ b/Doc/c-api/weakref.rst
@@ -53,7 +53,14 @@ as much as it can.
 .. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref)
 
    Return the referenced object from a weak reference, *ref*.  If the referent is
-   no longer live, returns ``None``.
+   no longer live, returns :const:`Py_None`.
+
+   .. warning::
+
+      This function returns a **borrowed reference** to the referenced object.
+      This means that you should always call :cfunc:`Py_INCREF` on the object
+      except if you know that it cannot be destroyed while you are still
+      using it.
 
 
 .. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)