[Bf-python] Re: tp_getset conversion update

[Ken Hughes]

I began this as a reply to a patch tracker update, but after it got 
lengthy thought better of it and decided maybe the collective "we" here 
should start a page on the wiki with coding practices for the API.

----------------------
Stiv's comment (on World.c tp_getset patch, #3087):

Started looking at the World stuff, got bogged down with mist. I think 
mist type implementation is problematic. Mist type is a single item that 
takes a discrete set of values: quad, linear or square. In the UI, it is 
a set of radio buttons.

Presenting mistype along with qua, lin and sqr as four separate 
attributes is confusing for the scripter. Is setting mistype enough? 
What happens when qua and lin are set together, for example?
----------------------
My comments:

This was done as part of the "make the API reflect the UI" clean-up 
discussed on the ML this summer; there are many places where the script 
writer access a "mode" or "flag" field in one module and individual 
boolean settings in others (boolean accessing one bit in a bitfield). 
My intent was that if we're trying to make the BPy API resemble Blender 
UI as much as possible, it should happen for all the buttons: where 
possible, there should be an attribute matching each UI button.  I can't 
tell you how much time I've spend trying to figure out which BPy 
attribute corresponds to which UI button, even with our fine 
documentation :-)

So "mistype" is a legacy attribute (in 2.37a) while "lin", "sqr", and 
"qua" are new attributes which will someday replace it.

If this is approach is something I've misinterpreted, that's fine.  But 
if so I think we need to document the "standard approach" on the API 
Inconsistency wiki page so that we "fix" any place in the API that's 
already doing this.  If I've not misinterpreted but have made a decision 
on my own because there is no such "standard approach", then let's 
decide what we WANT the API to do and document it on the wiki too.  I'm 
not proposing a committee here to draft a comprehensive document; maybe 
just start with some categories and put "DO" and "DON'T" under it.

BTW, can't help but notice that only four people have added anything o 
the "API Cleanup::Remove Inconsistencies" wiki page.  Maybe not everyone 
has been on a hunt for consistency problems, but is anyone even looking 
at it?

Ken

OT: the word "canon" keeps popping into my mind as I think about this: 
as in, "A secular law, rule, or code of law".  I like that; we're like a 
monk's order who keeps the holy word of the BPython API.  ANYWAY....