[Python-3000] Eliminating PY_SSIZE_T_CLEAN

[Gregory P. Smith]

On Sat, Nov 22, 2008 at 11:51 AM, Brett Cannon <brett at python.org> wrote:

> On Sat, Nov 22, 2008 at 06:29, Barry Warsaw <barry at python.org> wrote:
> > -----BEGIN PGP SIGNED MESSAGE-----
> > Hash: SHA1
> >
> > On Nov 22, 2008, at 4:05 AM, Martin v. Löwis wrote:
> >
> >> I just noticed that the Python 3 C API still contains PY_SSIZE_T_CLEAN.
> >>
> >> This macro was a transition mechanism, to allow extensions to use
> >> Py_ssize_t in PyArg_ParseTuple, while allowing other module continue
> >> to use int.
> >>
> >> In Python 3, I would like the mechanism, making Py_ssize_t the only
> >> valid data type for size in, say, s# parsers.
> >>
> >> Is it ok to still change that?
> >
> > Given that we just released the last planned candidate, I'd say it was
> too
> > late to change this for Python 3.0.
> >
>
> But we can at least document that the macro is a gone as soon as 3.0
> final is out the door.
>
> -Brett


I'll commit the following update to the py3k docs if nobody objects.  As it
is now, the only mention of PY_SSIZE_T_CLEAR at all is in whatsnew/2.5.rst.
This officially documents it and mentions that it is going away to be always
on in the future.  I'm assuming in 3.1 but I just left it as "a future
version" to not commit to that.  At least the py3k docs encourage use of s*
rather than s#.

-gps


Index: Doc/extending/extending.rst
===================================================================
--- Doc/extending/extending.rst (revision 67360)
+++ Doc/extending/extending.rst (working copy)
@@ -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() */
Index: Doc/c-api/arg.rst
===================================================================
--- Doc/c-api/arg.rst   (revision 67360)
+++ Doc/c-api/arg.rst   (working copy)
@@ -42,12 +42,19 @@
    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, the output will be 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-3000/attachments/20081123/decb5652/attachment.htm>