[Bf-committers] Issues reaching 'Stable PyAPI' for Blender2.5

[Campbell Barton]

This was posted as an item for last meeting, attempted to reply but
better make this a new topic.

> - Agreed was that Martin and Campbell would summarize this topic to
> mailing list, and especially about what is considered good py api
> design! What's more or less 'stable' and what not?

We didn't end up discussing this topic yet, however I had an offer for
help yesterday and attempted to gather tasks people can help with but
failed.

Splitting the API TODO's into 4 groups.

1) extending the existing APIs, Add Mathutils.Color(...) class, make
Euler rotation orders work. Expose animation system functions.
Generally make the API's more complete and fill in the gaps.

2) fixing 'gotchas', functions that are not useful without some
argument, missing update functions which are ok with the UI but may
mess up python. rna attributes which cant be accessed usefully from
python. Operators that cant be used from python. Operators that also
need to be accessed as RNA functions.

3) API design, choosing conventions for such things as function names
(currently a mess), class naming, standardize on how items are removed
from a collection (also a mess).

4) internal api, managing rna-python wrapping and managing memory.
registering etc, wouldn't suggest people start here.

---

So who can do these?
#1 - could be worked on be experienced devs who contributed to 2.4x or
devs with experience with other projects.
#2 - this is probably the area we can use most help, all we need is
people to port simple scripts who also are ok about looking into
rna_*.c files.
#3 - IMHO existing blender devs can handle this, though some research
is needed, much of it isnt that time consuming, just need to come to
some decision and go ahead with them.
#4 - existing devs can do.

More on #2
this IMHO is where a lot of the problem is, whenever I use the API for
something new I find problems it seems, yesterday I tried to save an
image and reload, this ended up being complicated because modifying
the image filename (needed to save to a new path) ran an update
function that cleared the image data I had just created. adding
mplayer preset also needed some api addition.

This is a bit catch22, we cant say the api as stable until its tested,
but people hold off porting until its stable.

Ton also doesn't want scripts in blender which have bugs (racking up
items in the tracker), this is tricky since its hard to write totally
bug free scripts when the api is giving problems or doest expose
needed data & functions.

I don't see any quick fix, just a matter of writing scripts which use
the api and then fix problems as they are found.
If developers are able to help look over existing scripts and improve
the api to avoid workarounds and hacks that'd be great, as well as
porting simple scripts to test the api and make fixes where possible.

However this is still a big IF, mostly this isnt being worked on, Im
only fixing things as I need them.

I don't see that changing, so I'd forecast the python/rna api wont be
stable for a fair while, 5-10 months at least. Maybe this is ok, but
this is my explanation as to why we cant write something we call
stable in a short time.

PS: Note on what I mean by stable API...
Excludes obscure api use cases which can get fixed in the course of
normal development, common things are adding/removing data, saving
files, loading images, running macros, api used for renderfarm and
generally editing data in the scene. - all working in a way we can say
wont need to change in 2 months.

-- 
- Campbell