Merged revisions 67348,67355,67359,67362,67364-67365,67367-67368,67398,67423-67424,67432,67440-67441,67444-67445,67454-67455,67457-67458 via svnmerge from

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

........
  r67348 | benjamin.peterson | 2008-11-22 20:09:41 -0600 (Sat, 22 Nov 2008) | 1 line

  raise a better error
........
  r67355 | georg.brandl | 2008-11-23 13:17:25 -0600 (Sun, 23 Nov 2008) | 2 lines

  #4392: fix parameter name.
........
  r67359 | georg.brandl | 2008-11-23 15:57:30 -0600 (Sun, 23 Nov 2008) | 2 lines

  #4399: fix typo.
........
  r67362 | gregory.p.smith | 2008-11-23 18:41:43 -0600 (Sun, 23 Nov 2008) | 2 lines

  Document PY_SSIZE_T_CLEAN for PyArg_ParseTuple.
........
  r67364 | benjamin.peterson | 2008-11-23 19:16:29 -0600 (Sun, 23 Nov 2008) | 2 lines

  replace reference to debugger-hooks
........
  r67365 | benjamin.peterson | 2008-11-23 22:09:03 -0600 (Sun, 23 Nov 2008) | 1 line

  #4396 make the parser module correctly validate the with syntax
........
  r67367 | georg.brandl | 2008-11-24 10:16:07 -0600 (Mon, 24 Nov 2008) | 2 lines

  Fix typo.
........
  r67368 | georg.brandl | 2008-11-24 13:56:47 -0600 (Mon, 24 Nov 2008) | 2 lines

  #4404: make clear what "path" is.
........
  r67398 | benjamin.peterson | 2008-11-26 11:39:17 -0600 (Wed, 26 Nov 2008) | 1 line

  fix typo in sqlite3 docs
........
  r67423 | jesse.noller | 2008-11-28 12:59:35 -0600 (Fri, 28 Nov 2008) | 2 lines

  issue4238: bsd support for cpu_count
........
  r67424 | christian.heimes | 2008-11-28 13:33:33 -0600 (Fri, 28 Nov 2008) | 1 line

  Retain copyright of processing examples. This was requested by a Debian maintainer during packaging of the multiprocessing package for 2.4/2.5
........
  r67432 | benjamin.peterson | 2008-11-28 17:18:46 -0600 (Fri, 28 Nov 2008) | 1 line

  SVN format 9 is the same it seems
........
  r67440 | jeremy.hylton | 2008-11-28 17:42:59 -0600 (Fri, 28 Nov 2008) | 4 lines

  Move definition int sval into branch of ifdef where it is used.

  Otherwise, you get a warning about an undefined variable.
........
  r67441 | jeremy.hylton | 2008-11-28 18:09:16 -0600 (Fri, 28 Nov 2008) | 2 lines

  Reflow long lines.
........
  r67444 | amaury.forgeotdarc | 2008-11-28 20:03:32 -0600 (Fri, 28 Nov 2008) | 2 lines

  Fix a small typo in docstring
........
  r67445 | benjamin.peterson | 2008-11-29 21:07:33 -0600 (Sat, 29 Nov 2008) | 1 line

  StringIO.close() stops you from using the buffer, too
........
  r67454 | benjamin.peterson | 2008-11-30 08:43:23 -0600 (Sun, 30 Nov 2008) | 1 line

  note the version that works
........
  r67455 | martin.v.loewis | 2008-11-30 13:28:27 -0600 (Sun, 30 Nov 2008) | 1 line

  Issue #4365: Add crtassem.h constants to the msvcrt module.
........
  r67457 | christian.heimes | 2008-11-30 15:16:28 -0600 (Sun, 30 Nov 2008) | 1 line

  w# requires Py_ssize_t
........
  r67458 | benjamin.peterson | 2008-11-30 15:46:16 -0600 (Sun, 30 Nov 2008) | 1 line

  fix pyspecific extensions that were broken by Sphinx's grand renaming
........

1 files changed, 17 insertions, 9 deletions

diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index e4b91b9..d64cc5c 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -32,6 +32,11 @@ variable(s) whose address should be passed.
    converted to C strings using the default encoding.  If this conversion fails, a
    :exc:`UnicodeError` is raised.
 
+   Starting with Python 2.5 the type of the length argument can be
+   controlled by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before
+   including :file:`Python.h`.  If the macro is defined, length is a
+   :ctype:`Py_ssize_t` rather than an int.
+
 ``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer \*]
    This is similar to ``s``, but the code fills a :ctype:`Py_buffer` structure
    provided by the caller.  In this case the Python string may contain embedded
@@ -43,17 +48,20 @@ variable(s) whose address should be passed.
    has processed the data.
 
 ``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int or :ctype:`Py_ssize_t`]
-   This variant on ``s*`` stores into two C variables, the first one a pointer
-   to a character string, the second one its length.  All other read-buffer
-   compatible objects pass back a reference to the raw internal data
-   representation.  Since this format doesn't allow writable buffer compatible
-   objects like byte arrays, ``s*`` is to be preferred.  The type of
-   the length argument (int or :ctype:`Py_ssize_t`) is controlled by
+   This variant on ``s`` stores into two C variables, the first one a pointer to
+   a character string, the second one its length.  In this case the Python
+   string may contain embedded null bytes.  Unicode objects pass back a pointer
+   to the default encoded string version of the object if such a conversion is
+   possible.  All other read-buffer compatible objects pass back a reference to
+   the raw internal data representation.  Since this format doesn't allow writable buffer compatible objects like byte
+   arrays, ``s*`` is to be preferred.
+
+   The type of the length argument (int or :ctype:`Py_ssize_t`) is controlled by
    defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before including
    :file:`Python.h`.  If the macro was defined, length is a :ctype:`Py_ssize_t`
-   rather than an int.  This behavior will change in a future Python
-   version to only support :ctype:`Py_ssize_t` and drop int support.
-   It is best to always define :cmacro:`PY_SSIZE_T_CLEAN`.
+   rather than an int.  This behavior will change in a future Python version to
+   only support :ctype:`Py_ssize_t` and drop int support.  It is best to always
+   define :cmacro:`PY_SSIZE_T_CLEAN`.
 
 ``y`` (bytes object) [const char \*]
    This variant on ``s`` converts a Python bytes or bytearray object to a C