methods vs. properties, and tests and code reference (Re: [Bf-python] API overhaul - irc meeting?)

[Toni Alatalo]

On Sunday 08 January 2006 15:43, Michael Reimpell wrote:
> some tests (aka "use cases"). For example, take the Key module. You have

if we get the api to be complete, these tests would in a way work as tests for 
blender itself too. except that as things are refactoring the c parts just 
breaks the py api, but well, at least the tests would point that out.. :/

but i am all for test driven development, first time did it last summer in the 
ipython notebook project and it was beneficial, especially for refactoring

> make life easier. That is, although the BPy class attributes are limited to
> the C-struct elements, there can (and should) be getters or setters for
> derived values. For example an armature bone could have a setter
> setTransformation(matrix) which changes the head, tail and roll values

i dont think the bpy instance attributes should be limited to the c struct 
elements. instead of bone.setTransformation(matrix), why would we not have a 
modifiable bone.matrix? it is still a thin wrapper (manipulating bpy bone 
matrix actually modifies the internal rotation things), just via a different 
interface (which is friendlier to e.g. importers).

> value" has the same information as no documentation at all. C developers
> may even start to look into the BPy documentation to see what the C struct
> elements mean.

i think the bpy api code may even work as a reference to the c code, like: how 
to create a new ipo in blender in c? look at bpy Ipo constructor/initializer 
to see! at least i tend to do that :)

> Also, I don't understand the "attributes above methods" philosophy. Don't
> let a language dictate your design. In the proposed design attributes have
> a clear meaning  as Blender's internal data, and this meaning fits very
> well with Blender's data driven design.

aha, so you object bone.matrix because Blender does not have it internally. 
ok, i promise to consider that point seriously. hmhm.

the reason why attributes/properties are usually preferred is that it .. well, 
they are standard. if an object has an attribute, the standard way to set it 
by using the Python setting operator, '='. you dont have to remember a 
special method for setting the attribute, you just use the normal operator.

the reason why in some other languages, like Java (and C++ i suppose), there 
are so-called 'setter' and 'getter' methods is that if some attribute 
requires some special code, like getting the value of it from a database or 
calculating it based on some other internal attributes, it has to be called 
as a method for it to be able to include the code to do that. Python does not 
anymore have that limitation so all necessary values can be exposed normally.

i do agree it is always not clear what should be a property, and what a 
method. while it is possible to have every method that returns only a single 
value, and every method that takes no arguments, as a property (which looks 
identical to attributes for a user), it does not make sense. like it never 
crossed my mind to make something.update() a something.update = 'whatever' 
that magically runs the update code for an object. i did once do a system 
where networked objects have a thing.changed property, which returns True if 
the thing has changed after the previous call to that property, and it was 
nice to use but scary too (perhaps even bad design). the case with 'update' 
is clear: it is command, a function in that sense, so it is best as callable. 
'changed' .. is clearly not a command, but a state/value of the object, so 
perhaps it is good as a property.

but 'transformation' and 'matrix' are not commands, they should not be 
callable. they are values, so their values are to be gotten by writing 
'thing.matrix' and assigned by 'thing.matrix = xxx'. even tho Blender does 
not store it internally like that, it does not change the fact that 'matrix' 
is still an attribute of a bone - just in a different format (a different 
view to the same data, one might say). 

i guess that is my argument. sorry for the long post, and thank you for the 
interesting point. i do accept that am not too much of an expert in this, so 
am not hurt by any kinds of flames and rants bashing potential stupid 
thinking there :)

and in this particular case, adding bone.matrix is not about writing extra 
bloat to the api code under some assumption on the usage, but a response to a 
direct request by armature import writers, right?

> Michael

~Toni