Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
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.
........
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.
........
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.
........
r83563 | georg.brandl | 2010-08-02 22:21:21 +0200 (Mo, 02 Aug 2010) | 1 line
#9037: add example how to raise custom exceptions from C code.
........
r83565 | georg.brandl | 2010-08-02 22:27:20 +0200 (Mo, 02 Aug 2010) | 1 line
#9111: document that do_help() looks at docstrings.
........
r83571 | georg.brandl | 2010-08-02 22:44:34 +0200 (Mo, 02 Aug 2010) | 1 line
Clarify that abs() is not a namespace.
........
r83574 | georg.brandl | 2010-08-02 22:47:56 +0200 (Mo, 02 Aug 2010) | 1 line
#6867: epoll.register() returns None.
........
r83575 | georg.brandl | 2010-08-02 22:52:10 +0200 (Mo, 02 Aug 2010) | 1 line
#9238: zipfile does handle archive comments.
........
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 7fce170..0288271 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -567,6 +567,38 @@
*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 80ebf82..226ec38 100644
--- a/Doc/c-api/weakref.rst
+++ b/Doc/c-api/weakref.rst
@@ -63,10 +63,17 @@
.. 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`.
.. versionadded:: 2.2
+ .. 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)