[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

Re: [pygame] Documenting the pygame C API and making the API consistent

Hi Thomas,

On 18-06-17 03:17 AM, Thomas Kluyver wrote:
I'm not really familiar with C APIs, but I thought that the 0/-1 inconsistency was necessary because 0 may be a valid return value in some contexts, and there is no -1 if you're using a unsigned integer type. Looking quickly at the Python docs, the pattern seems to be that functions returning a pointer return NULL on error, and the rest use -1 to indicate an error - though I don't know if that's always followed.
The most obvious example I found of returning 0 on failure are the Python function argument parsing functions, such as int PyArg_ParseTupleAndKeywords(...), which return true on success, or raise a Python exception and return false. This is contrary to many other functions, such as int PyObject_SetAttr(...), which returns 0 on success, -1 on failure. But yes, numeric version functions, such as double PyFloat_AsDouble(...) and Py_ssize_t PyNumber_AsSsize_t (...) also return -1 on failure.
I would think that API changes don't belong in a 1.9.x release, but that's not my decision. :-)
I am in no rush to change the pygame C API. If changes are made, they can wait until pygame 2. 

Lenard Lindstrom
On 15 June 2018 at 23:45, Lenard Lindstrom <len-l@xxxxxxxxx <mailto:len-l@xxxxxxxxx>> wrote: 

    Hi everyone,

    A part of the preparation for pygame 2 I have documented the
    functions and types exported by various pygame extension modules.
    For instance, the pygame.surface module exports C functions for
    creating and accessing pygame.Surface instances. These are used in
    other modules, such as pygame.display and pygame.image, where
    surfaces are created. In total, twelve extension modules make C
    functions available for use in other extension modules.

    While documenting the C API I renamed C types, functions, and
    variables to be consistent with Python's PEP 7. Names starting
    with 'Py' and 'Pg' were changed to use the 'pg' prefix. This
    avoids conflicts with possible future Python C functions as well
    as make the pygame naming convention consistent. I have also found
    other inconsistencies in the pygame C API. Functions that return a
    Python object are consistent in returning NULL to indicate an
    error. However, for functions that return an error code, some may
    use -1 to indicate an error, while others use 0. Should I make an
    effort to make pygame error handling consistent within the C API?
    Would it make sense to do this before pygame 1.9.4 is released, or
    wait until pygame 2? Python is not much help since it has mixed
    error codes within its C API.

    Lenard Lindstrom