[Python-3000-checkins] r67361 - in python/branches/py3k/Doc: c-api/arg.rst extending/extending.rst

gregory.p.smith python-3000-checkins at python.org
Mon Nov 24 00:49:16 CET 2008


Author: gregory.p.smith
Date: Mon Nov 24 00:49:16 2008
New Revision: 67361

Log:
Document PY_SSIZE_T_CLEAN use and behavior for PyArg_ParseTuple and
mention that it will become the default in a future python version.


Modified:
   python/branches/py3k/Doc/c-api/arg.rst
   python/branches/py3k/Doc/extending/extending.rst

Modified: python/branches/py3k/Doc/c-api/arg.rst
==============================================================================
--- python/branches/py3k/Doc/c-api/arg.rst	(original)
+++ python/branches/py3k/Doc/c-api/arg.rst	Mon Nov 24 00:49:16 2008
@@ -42,12 +42,18 @@
    responsible** for calling ``PyBuffer_Release`` with the structure after it
    has processed the data.
 
-``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int]
+``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.
+   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`.
 
 ``y`` (bytes object) [const char \*]
    This variant on ``s`` converts a Python bytes or bytearray object to a C

Modified: python/branches/py3k/Doc/extending/extending.rst
==============================================================================
--- python/branches/py3k/Doc/extending/extending.rst	(original)
+++ python/branches/py3k/Doc/extending/extending.rst	Mon Nov 24 00:49:16 2008
@@ -587,11 +587,16 @@
 
 Some example calls::
 
+   #define PY_SSIZE_T_CLEAN  /* Make "s#" use Py_ssize_t rather than int. */
+   #include <Python.h>
+
+::
+
    int ok;
    int i, j;
    long k, l;
    const char *s;
-   int size;
+   Py_ssize_t size;
 
    ok = PyArg_ParseTuple(args, ""); /* No arguments */
        /* Python call: f() */


More information about the Python-3000-checkins mailing list