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

[Lenard Lindstrom]

I know from experience how much more of a headache it is to 
build/distribute native extensions that depend on other native 
extensions' ABIs (numpy, specifically).


Do Pygame Surface/Sound objects support the Buffer Protocol? This 
would be a convenient way to to read and update object data without 
needing to compile against Pygame.

Pygame has better buffer support than Python 3.
To be clear, pygame Surfaces and Sound objects export their data with 
the New Buffer Protocol. The numpy specific surfarray and sndarray 
modules are wrappers for the buffer based pixelcopy module. At the time 
when I added New Buffer support to pygame, it was better developed than 
that provided by the Python 3 buffer object.


Lenard Lindstrom

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

[Lenard Lindstrom]

On 18-06-18 01:45 AM, Daniel Pope wrote:

Is this for a public C API or just internal to Pygame?
It is internal to Pygame, though if it is formalized and documented 
someone might use it in another package.




I know from experience how much more of a headache it is to 
build/distribute native extensions that depend on other native 
extensions' ABIs (numpy, specifically).


Do Pygame Surface/Sound objects support the Buffer Protocol? This 
would be a convenient way to to read and update object data without 
needing to compile against Pygame.

Pygame has better buffer support than Python 3.



On Sun, 17 Jun 2018, 12:19 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.

I would think that API changes don't belong in a 1.9.x release,
but that's not my decision. :-)

On 15 June 2018 at 23:45, Lenard Lindstrom mailto:le...@telus.net>> 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

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

[René Dudfield]

This is amazing work. Thanks a lot for doing these hard but very helpful
changes :) It should make working with pygame internals much easier and
understandable for people.

cheerio,

On Friday, June 15, 2018, Lenard Lindstrom  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
>
>
>

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

[Lenard Lindstrom]

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 > 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

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

[Leif Theden]

unless you are committed to to rewriting everything, i would leave changing
error handling alone alone...C is not forgiving and very few people (a
dozen, maybe?) use the pygame internal C code, and unless its getting in
your way and slowing down development its probably best to document the
code rather than changing it.  standardizing prefixes like "pg_" is nice.

On Mon, Jun 18, 2018 at 3:45 AM, Daniel Pope  wrote:

> Is this for a public C API or just internal to Pygame?
>
> I know from experience how much more of a headache it is to
> build/distribute native extensions that depend on other native extensions'
> ABIs (numpy, specifically).
>
> Do Pygame Surface/Sound objects support the Buffer Protocol? This would be
> a convenient way to to read and update object data without needing to
> compile against Pygame.
>
> On Sun, 17 Jun 2018, 12:19 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.
>>
>> I would think that API changes don't belong in a 1.9.x release, but
>> that's not my decision. :-)
>>
>> On 15 June 2018 at 23:45, Lenard Lindstrom  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
>>>
>>>
>>>
>>

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

[Daniel Pope]

Is this for a public C API or just internal to Pygame?

I know from experience how much more of a headache it is to
build/distribute native extensions that depend on other native extensions'
ABIs (numpy, specifically).

Do Pygame Surface/Sound objects support the Buffer Protocol? This would be
a convenient way to to read and update object data without needing to
compile against Pygame.

On Sun, 17 Jun 2018, 12:19 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.
>
> I would think that API changes don't belong in a 1.9.x release, but that's
> not my decision. :-)
>
> On 15 June 2018 at 23:45, Lenard Lindstrom  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
>>
>>
>>
>

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

[Thomas Kluyver]

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.

I would think that API changes don't belong in a 1.9.x release, but that's
not my decision. :-)

On 15 June 2018 at 23:45, Lenard Lindstrom  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
>
>
>

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

[Lenard Lindstrom]

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