[Bf-python] Re: tp_getset conversion update

[Gilbert, Joseph]

(My Essay) regarding bitflags and radio buttons: :)
1. The api should model the UI in in such a way that modelers that have
never used python before will be familiar with the terminology in the
api.  Methods that are labeled similar to the labeling on the UI, makes
it easy for people wholly unfamiliar with python to do some simple
script writing. One of the purposes (imho) in choosing python as a
scripting language, is to provide some simplicity for those who have
done little coding before. We can continue that thread in our method and
variable naming.

2. As willian has pointed out we don't need to follow the UI button
layout. Things have a tendency to pop into and out of panels, menus,
etc. However there are options that clearly are either eXlusive (radio
buttons types) or inclusive (bitflags) in the UI and in the code. We can
identify when a set of options is either exclusive or inclusive and
follow such standards as we define.

3. Constant dictionaries are something that I think we have come to
through trial and error. We originally used every way possible to pass
things in and out of methods but over time I think 2 things have become
clear.
a) That what is returned from a getter() should be able to be taken by a
setter()
b) That constant dicts work better in this regard than string values.

4. Constant dicts can solve the requirements of both bitfields and radio
buttons. In the case of radio buttons as willian has stated a single
constant can be used to set the value of an eXclusive group. A list of
constants can be used to set/ and be returned from an
inclusive(bitfield) group.

5. I have some additional comments:
>object.myvar = VALS.STRVAL1
This is very nice. This fixes one problem. The problem of having
multiple get()/set() for every value in an eXclusive group. i.e.
getX()/setX()[bool]
getY()/setY()[bool]
getZ()/setZ()[bool]
is reduced to:
getExclusive()/setExclusive() [constant]

>object.myflags = FLAGS.F1 | FLAGS.F2
>object.myflags &= ~FLAGS.F3
This is something I'm not completely in agreement with for a few
reasons.
1. It's too complex for anyone other than our advanced script writers.
2. It presupposes that the value stored in the constant is numeric. (it
could be a string)

Storing numeric values as the value in the constant dict is dangerous
because it's easy to manipulate. I can just as easily write:
>object.myflags = 2 | 24
>object.myflags &= ~32
And people can start to access bits they should not.

>From my point of view the value of the constant should be an instance of
a PyObject. This way only that object can be passed into and out of an
inclusive list.  Inclusive lists can be called by:
>object.myflags = [FLAGS.F1, FLAGS.F2]
>object.myflags = object.myflags.append(FLAGS.F3)
>object.myflags = object.myflags.remove(FLAGS.F2)
if FLAGS.F2 in object.myflags:
...print 'flag set'
else:
...object.myflags.append(FLAGS.F2)

Just some ideas.

-----Original Message-----
From: bf-python-bounces at projects.blender.org
[mailto:bf-python-bounces at projects.blender.org] On Behalf Of Ken Hughes
Sent: Thursday, September 29, 2005 11:15 AM
To: Blender Foundation Python list
Subject: Re: [Bf-python] Re: tp_getset conversion update

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

_______________________________________________
Bf-python mailing list
Bf-python at projects.blender.org
http://projects.blender.org/mailman/listinfo/bf-python