Python Coding Style Conventions

[sDos280]

Ok, As the title of the discussion say, (i think) we need to talk about adding a coding style conventions for the python example.
As you know, everyone can add (convert from c to python) an example with their own coding style but with no order(conventions) things may go out of control and get messy.

my idea is to make "Coding Style Conventions" for pyray like raylib has (https://github.com/raysan5/raylib/blob/master/CONVENTIONS.md). I personally never designed code conventions for any programing language befor, so I may need your help with that. also i though that we will may need to make to separate code conventions for the C API and the python API (because they are a bit different to use... but there may not really be a need for that)

i know that the pyray wants to be as close to the original c library so I thought to add to the conventions the idea of entry point(as a main function). (like in here https://github.com/sDos280/raylib-python-cffi/blob/master/examples/shapes/shapes_lines_bezier.py).

if you think that this idea is good please let me know🙏, i know that this will mean a big refactor to the library so if you think that is over kill i will understand 👍.

p.s. i know that with the code conventions we will need to refactor any examples that don't stands to the conventions. i will happily refactor any example that we will need to refactor.

[sDos280]

example of Coding Style Conventions for Python API:

https://github.com/sDos280/raylib-python-cffi/blob/Conventions/PYTHON_API_CONVENTIONS.md

example of Contributing Conventions for Python API:

https://github.com/sDos280/raylib-python-cffi/blob/Conventions/CONTRIBUTING.md

I tryied to make the CONTRIBUTING.md and the PYTHON_API_CONVENTIONS.md as close to the CONVENTIONS.md and the CONTRIBUTING.md in the main GitHub repository (https://github.com/raysan5/raylib/blob/master/CONVENTIONS.md, https://github.com/raysan5/raylib/blob/master/CONTRIBUTING.md)

[sDos280]

If you want to see the progress I've made so far:

https://github.com/sDos280/raylib-python-cffi/tree/Conventions

[sDos280]

ok, I updated the PYTHON_API_ CONVENTIONS.md to be closer to https://peps.python.org/pep-0008/ .

probably, next week I will try to publish the C_API_ CONVENTIONS.md file...

I need more help to refactor all of the example that use the python API to stand to the PYTHON_API_ CONVENTIONS.md . any help will be expected happily ;).

[electronstudio]

Raylib has a code style conventions because there isn't a standard style for C code. (Also, Raylib has 372 contributors. Raylib-Python-CFFI only has 13 contributors ever and not all of them worked on examples.) Python has a standard, PEP 8, so I think we can just point contributors to use that.

I agree it would be nice to make all the examples consistent in style but I don't have time to do it. If you want to tidy them up then go ahead. It's very rare for anyone to contribute examples so I'm not going to reject them just for style reasons.

Regarding the main function, I don't think this is necessary in Python. The point of examples is to be as short and clear as possible. If Raylib could write examples without a main function I'm sure they would, but they are C so they can't. If contributors submit examples using main I will still add them however.

[sDos280]

ok, I know that using a "entry point" with python doesn't really worth it, I just added that to make the examples closer to the original c example.

Actually I know of two peoples that been interested lately in pyray, and they told me that they really wanted to contribute with porting examples from c to python. they should start contribute in the next week, so knew example are in the way :).
because I want the most of the new example to stand for the python api conventions(and the c api conventions...) I told them to contribute directly to my fork in the convention branch, I am planning to make a PR with all of the current examples standing to the conventions in the next month.

[sDos280]

p.s. thanks for answering me, highly appreciated 😄.

I am mostly posting in this discussion to share the progress and ask for help...

[sDos280]

Sorry @electronstudio, this project really slipped my mind. Latetly I got really busy, I probably won't make any more changes on the conventions for any time soon, would you like me to still PR the work that I done so far? Because I don't really know what will be next time I will add stuff to the conventions...

[Axle-Ozz-i-sofT]

Hi all
I would like to continue this thread with a few questions if it is OK?
I haven't yet learned raylib or raygui and I am still a little weak with Python. I am attempting to set up raylib (with raygui included) to learn using C, FreeBASIC and Python 3 on Windows and Ubuntu with "raylib-4.2.0" and raygui-3.2. So far I have built both static and shared raylib+raygui for C and freeBASIC and have raylib example "shapes_basic_shapes" and raygui example "raygui_controls_test_suite" working in both languages on both platforms.

I am attempting to convert the 2 example to raylib-python-cffi at the moment and running into confusion with the binder and the APIs.
Looking over the docs I feel that working with the python pyray API looks like the best "pythonic" path.

Q1. When looking at the Docs, examples and tests I get some differences in naming conventions. From what I can tell the C API (raylib) follows the C naming used in raylib/gui.h and the Py API has C naming for Structures, and Py (snake_case) for functions. Is this the case or are there still some ambiguous cases?
Some of the test/example mix raylib and pyray so I'm stumbling a bit lol ...

Q3. Is it required to use raylib(cffi) to enable pyray(cffi) functionality in some cases? aka are there still parts of the pyray API that are not implemented?

Q2 Do all C structures from the raylib.h headers have to be constructed with ffi.new( ...) to use pyray(cffi) or just some and how do I tell?
The raylib uses ffi.new("struct Camera3D *" [...] and pyray uses pr.Camera3D([18.0, 16.0, 18.0], [0.0, 0.0, 0.0], [0.0, 1.0, 0.0], 45.0, 0) for example.
I am getting an error at the moment FilePathList and I can't find it in the pyray API so I guess this would be a case to use cffi.new ?
And are there more example on using ffi.new I looked at https://cffi.readthedocs.io/en/latest/ref.html#ffi-new but haven't found any other examples other than the ffi.new("struct Camera3D *" [...] I mentioned above.

Sorry if these seam like silly questions. In other scripting languages I have used the C structures are created in the module headers so I can just use the data type without constructing each one manually.

TIA
Axle

[electronstudio]

Do all C structures from the raylib.h headers have to be constructed with ffi.new( ...) to use pyray(cffi) or just some and how do I tell?
The raylib uses ffi.new("struct Camera3D *" [...] and pyray uses pr.Camera3D([18.0, 16.0, 18.0], [0.0, 0.0, 0.0], [0.0, 1.0, 0.0], 45.0, 0) for example.

pyray.Camera3D() is not really a class, it's just a helper function that in turn calls ffi.new. The intention is to have helper functions for all structs, but there could be some missing because Raylib has added more. To tell if something exists read the docs.

[Axle-Ozz-i-sofT]

@electronstudio

Thank you. Sorry for the duplication. I attempted to edit the original post and had trouble finding edit :/
As per my edit note I think my head clicked and worked it out. Bit of a rubber duck moment. I am doing the conversion from C PascalCase to snake_case atm.

With regards to @sDos280 OP
I am doing a lot of code conversions between C, FreeBASIC and Python3. I will soon be creating "rosetta code" style examples for all 3 languages using raylib/gui as well as 4 other libraries for a series of books that I am creating.

Coming from a C Win-API background I tend to use Win-API Hungarian variant for variable naming.
So in C I will often use int_myvariabe, or INT_MyVariable to denote Win-API types.
In python I have started using a similar hungarian_snake_case as it allows me to quickly differentiate between primitives and complex API data types. It also helps me trace type errors where I have forgotten to explicit typecast an input to integer etc. Some say it is not really PEP 8 conformant but it makes my life easier :)
For the raylib examples I will follow the hungarian_snake_case in python, it's not hard to remove to prefix if needed.

##pyray API##
# Variable naming = Hungarian_snake_case
# str_variable
# int_variable, int, float, complex
# list_variable, tuple, range
# dict_variable
# set_variable, frozenset
# bool_variable
# byte_variable, bytearray, memoryview
# None_variable

Changing functions from PascalCase to snake_case seams logical, Structures and other data types from the API I am not sure.

With regards to using main() I have thus far used it to keep a similar feel in my examples in C FB and Python. Although not "Required" I do find some convenience using:

def main():
    pass

if __name__ == '__main__':
    main()

I also do the same in FreeBASIC.

Again, thanks for the reply and confirmations. Much appreciated :)

[Axle-Ozz-i-sofT]

Update:

Just setting up a prefix for raylib data types. The majority are type struct which follows pyray API docs so I am prefixing with that.
example:
Vector2 viewScroll = { 0, 0 };
becomes
struct_view_scroll = Vector2( 0, 0 )

Any thoughts?

[sDos280]

that's ok, most of the python examples currently don't really have uniform conventions, so one of the things that I worked on(lately I stopped) is conventions for the pyray python API, take a look here to see how naming(and some other should) should be done(Note: the conventions are more pyray examples specific...).

[Axle-Ozz-i-sofT]

Thanks @sDos280
I had a look over it earlier and will keep it in mind as I progress with some examples :)

P.S. Anything to do with libraries and naming conventions always does my head in, esp when you work with mixed C/Win-API.

[Axle-Ozz-i-sofT]

Hi all
I would like to continue this thread with a few questions if it is OK?
I haven't yet learned raylib or raygui and I am still a little weak with Python. I am attempting to set up raylib (with raygui included) to learn using C, FreeBASIC and Python 3 on Windows and Ubuntu with "raylib-4.2.0" and raygui-3.2. So far I have built both static and shared raylib+raygui for C and freeBASIC and have raylib example "shapes_basic_shapes" and raygui example "raygui_controls_test_suite" working in both languages on both platforms.

I am attempting to convert the 2 example to raylib-python-cffi at the moment and running into confusion with the binder and the APIs.
Looking over the docs I feel that working with the python pyray API looks like the best "pythonic" path.

Q1. When looking at the Docs, examples and tests I get some differences in naming conventions. From what I can tell the C API (raylib) follows the C naming used in raylib/gui.h and the Py API has C naming for Structures, and Py (snake_case) for functions. Is this the case or are there still some ambiguous cases?
Some of the test/example mix raylib and pyray so I'm stumbling a bit lol ...

Q3. Is it required to use raylib(cffi) to enable pyray(cffi) functionality in some cases? aka are there still parts of the pyray API that are not implemented?

Q2 Do all C structures from the raylib.h headers have to be constructed with ffi.new( ...) to use pyray(cffi) or just some and how do I tell?
The raylib uses ffi.new("struct Camera3D *" [...] and pyray uses pr.Camera3D([18.0, 16.0, 18.0], [0.0, 0.0, 0.0], [0.0, 1.0, 0.0], 45.0, 0) for example.
I am getting an error at the moment FilePathList and I can't find it in the pyray API so I guess this would be a case to use cffi.new ?
And are there more example on using ffi.new I looked at https://cffi.readthedocs.io/en/latest/ref.html#ffi-new but haven't found any other examples other than the ffi.new("struct Camera3D *" [...] I mentioned above.

Sorry if these seam like silly questions. In other scripting languages I have used the C structures are created in the module headers so I can just use the data type without constructing each one manually.

TIA
Axle

Update:
I worked it out lol
droppedFiles = FilePathList (I was attempting droppedFiles = FilePathList(0,0,"") etc.
and
SetTargetFPS() becomes set_target_fps() not settargetfps()

embarrassed Pikachu face

[sDos280]

Answer for question three:
In python there isn't really an initialization of a module, when you import a module in python his __init__.py file will run.

The pyray module is more of a wrapper for the raylib(cffi) module...
the thing that pyray doesn't really implement is the use of pointer(and all of the stuff that is more C related).

[sDos280]

Answer for question two:
That really depends on what you are trying to do, if you want to use pointer to structure use the ffi.new(..), if you just want to use the structure class use the pyray.struct(...).
In general, I am still a bit confused by the ideal case to use any of the above ways, that is one of the reasons that I am trying to create new python bindings using the ctypes(which should be much easier to use then cffi)

p.s. electronstudio if you see this I just want to clarify that I am not trying to replace you binding with mine, i just trying to create binding that will be more suitable to use pointer in python. I think you binding is awesome and I will still use them in any case that i won't need mine. So thanks for making your binding easy to use and understand, you binding was the major inspiration to me while making my binding

[sDos280]

One thing that I will say in favor of using cffi is that linking an uncomplicated c course(or an header file) to use in python is much easier then to do it with ctypes(also I think that it impossible to do that with ctypes)

[electronstudio]

No problem, just bear in mind that there are already raylib ctypes bindings available and I created cffi bindings only because I wasn't happy with them. The main issue I think is that they are a lot more work to create and also to maintain, so they don't stay up to date. That may not be such an issue in future if Raylib doesnt release so often.

[Axle-Ozz-i-sofT]

Hi @sDos280
Thanks for the responses. Very much appreciated. I wont duplicate so if you wish see my reply to @electronstudio for info on how I am approaching the examples.

[sDos280]

Continuation of #87 (reply in thread)

yeah, that's why one of the most important things I tried to do in my wrapper(it is less of a binding, at least for me) is to automate almost everything I can. for now, that worked really well, and if I don't screw I will probably try to add those things into pyray, but one of the most challenging things that I need to fix is the auto conversion from c types(int, float, double*, etc...) to ctypes types(c_int, c_float, etc...) for now I just have a large dictionary with all the c type string as a key and the corresponding ctypes type as value(with pointer and array as an exemption), but that really hard to maintain it that way...

although cffi and ctypes are different modules it seems like the cffi module relies on ctypes types for its internal functionality, I just looked at #53 and It seems like the idea of using ffi.typeof is really neat, I will try to see if there a good way of using it only with ctypes(the reason that I want to use it only with ctypes is that as I checked it, the ctypes functions wrapping way can result in a 2X faster function execution if used right)...

p.s. for benchmarking I just used the bunnymark example, I know that this isn't really the way for doing that so I you have any idea for a better benchmark please let me know.

[sDos280]

Hi @electronstudio, I sent a PR for the conventions work

I would really like if you could review it

#100