[Python-Dev] Documenting the ssize_t Python C API changes

[M.-A. Lemburg]

Martin v. Löwis wrote:
> M.-A. Lemburg wrote:
>> Interesting: A few mails ago you suggested that developers
>> do exactly what I did to get the list of changes. Now you
>> gripe about the output format of the grep.
> 
> Developers which use grep can read the output of grep. Developers
> which use other methods of searching (e.g. Visual Studio) can
> understand the output of these tools. I don't say they *should*
> search for Py_ssize_t, I said they *can* if they want to.
> 
> I still don't think anybody would *want* to read such a list.

They don't necessarily want to read it, but like Fredrik did,
use as input for their testing tools.

>> I really don't understand what your problem is with documenting
>> the work that you and others have put into this. Why is there
>> so much resistance ?
> 
> Because I think it is pointless, confusing, and redundant in a dangerous
> way. There is absolutely NO problem with API changes where a function
> consumes Py_ssize_t. Why should anybody care that 
> PyString_FromStringAndSize now consumes a Py_ssize_t? Passing an int
> works just fine, and if the int fits the length of the string, it will
> absolutely do the right thing. There is no need to touch that code,
> or worry about the change.
> 
> Putting PyString_FromStringAndSize into such a list *will* make
> developers worry, because they now think they have to change their code
> somehow, when there is absolutely for action.

Don't you think developers are capable enough to judge for
themselves ?

They might also want to change their extensions to make use
of the new possibilities, so a list of APIs taking Py_ssize_t
parameters on input would be handy to check where there's
potential for such a change in their code.

Perhaps we should have three lists:

1. Py_ssize_t output parameters (these need changes)
2. Py_ssize_t return values (these need overflow checks)
3. Py_ssize_t input parameters (these can be used to enhance
   the extension)

Here's the list for 2 (I already provided the list for 1 in the
other mail):

./dictobject.h:
-- PyAPI_FUNC(Py_ssize_t) PyDict_Size(PyObject *mp);
./tupleobject.h:
-- PyAPI_FUNC(Py_ssize_t) PyTuple_Size(PyObject *);
./stringobject.h:
-- PyAPI_FUNC(Py_ssize_t) PyString_Size(PyObject *);
./longobject.h:
-- PyAPI_FUNC(Py_ssize_t) _PyLong_AsSsize_t(PyObject *);
./intobject.h:
-- PyAPI_FUNC(Py_ssize_t) PyInt_AsSsize_t(PyObject *);
./abstract.h:
--      PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
--      PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);
--      PyAPI_FUNC(Py_ssize_t) _PyObject_LengthHint(PyObject *o);
--      PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
--      PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);
--      PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
--      PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
./unicodeobject.h:
-- PyAPI_FUNC(Py_ssize_t) PyUnicode_GetSize(
--     PyObject *unicode                /* Unicode object */
--     );
-- PyAPI_FUNC(Py_ssize_t) PyUnicode_AsWideChar(
--     PyUnicodeObject *unicode,   /* Unicode object */
--     register wchar_t *w,        /* wchar_t buffer */
--     Py_ssize_t size             /* size of buffer */
--     );
-- PyAPI_FUNC(Py_ssize_t) PyUnicode_Tailmatch(
--     PyObject *str,           /* String */
--     PyObject *substr,                /* Prefix or Suffix string */
--     Py_ssize_t start,                /* Start index */
--     Py_ssize_t end,          /* Stop index */
--     int direction            /* Tail end: -1 prefix, +1 suffix */
--     );
-- PyAPI_FUNC(Py_ssize_t) PyUnicode_Find(
--     PyObject *str,           /* String */
--     PyObject *substr,                /* Substring to find */
--     Py_ssize_t start,                /* Start index */
--     Py_ssize_t end,          /* Stop index */
--     int direction            /* Find direction: +1 forward, -1
backward */
--     );
-- PyAPI_FUNC(Py_ssize_t) PyUnicode_Count(
--     PyObject *str,           /* String */
--     PyObject *substr,                /* Substring to count */
--     Py_ssize_t start,                /* Start index */
--     Py_ssize_t end           /* Stop index */
--     );
./listobject.h:
-- PyAPI_FUNC(Py_ssize_t) PyList_Size(PyObject *);

> Furthermore, it is redundant because there are now *four* places where
> the signature of the API is mentioned: in the header, in the
> implementation, in the API docs, and in the PEP. The compiler watches
> for consistency of the first two; consistency of the others is a manual
> process, and thus error-prone.

It's a one-time operation, documenting the changes between
Python 2.4 and 2.5 - much like the grand renaming in the C API
a few years ago.

You'd only create the lists once in the PEP, namely when Python 2.5
is released.

-- 
Marc-Andre Lemburg
eGenix.com

Professional Python Services directly from the Source  (#1, Mar 21 2006)
>>> Python/Zope Consulting and Support ...        http://www.egenix.com/
>>> mxODBC.Zope.Database.Adapter ...             http://zope.egenix.com/
>>> mxODBC, mxDateTime, mxTextTools ...        http://python.egenix.com/
________________________________________________________________________

::: Try mxODBC.Zope.DA for Windows,Linux,Solaris,FreeBSD for free ! ::::