[Bf-python] API overhaul - irc meeting?

[Stephen Swaney]

On Sun, Jan 08, 2006 at 02:43:02PM +0000, Michael Reimpell wrote:

Lots of thoughtful stuff here!  A few comments follow:

> > 6) The start: define API before coding it, create (epy)docs and tests, etc.
> 
> This is a very good idea! Blender's BPy development is definitely missing some 
> tests (aka "use cases"). 

Use cases are good!  The fundamental problem with BPy is that is has been
grown over time without a comprehensive view of the details.  I call it the
Coral Reef model of software dev.

[NMesh discussion snipped]

NMesh certainly has some, umm, 'interesting' features.  However, it is an 
exception to most of our design principles.  It is a classic example of 
legacy code.


> To avoid such issues in the future, I propose the following design guidelines:
> 
> 1) There is a one-to-one correspondence between Blender internal C-structs and 
> BPy's classes. This includes that all struct elements are available as 
> attributes and derived values are available via methods (I will address the 
> "C-struct element names are too cryptic" and "attributes above methods" 
> arguments later)

Our design principle here was to take a user centered approach.  What you see
in the API should resemble what you seen on the screen and the mental models
involved with that.

> 2) BPy is a thin wrapper to the C-structs. There is no caching inbetween. 

This has *always* been a design principle for the latest iteration of
the API.  Yeah, NMesh is a huge exception.  However, that is a
historical artifact due to the huge amount of work already put into
the NMesh module.  The purpose of the new Mesh module is to correct
this historical (and slow) problem.

> 
> As promised, here my comment on "most script writers are not interested in the 
> internal representation". Although I can't know what most script writers are 
> interested in, it is simply not possible to write any nontrivial script in 
> BPy without looking into Blender's interal codebase: You want to know what 
> the camera "lens" value is? You have to look into the corresponding C code. 

Most scripters are artists, not C coders.  I would NEVER expect any
user to look at source for C structs.  The UI is our reference here.
And the BPy API doc, of course!  Also, C structs ofen have names like
f1 and f1.


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

Since BPy is a Python-based scripting language, it should look like
Python.  The use of getStuf() and setStuff() methods is another
historical artifact, this time based on the state of Python itself at
the time.  Back then, the only way to do attributes for user defined
types was a user-written function with a huge block of if( attr_name
== "something")-like statements.  A side effect of this was that
making getter and settter methods as will as direct attribute access
was easy.  Python has changed as part of the process of integrating
types and classes.  Now, using the tp_getset slot and providing only
attribute access makes more sense for a number of reasons I am not
going to go into now.  We will still have methods.  Just not for
attribute access.


> The proposed BPy design can be summerized into one sentence: "The same design 
> as Blender's codebase". On the one hand this concept is extremly easy to 
> grab, on the other hand it is flexible and feature save. Even if you come up 
> with another BPy design in the end, please check that with the arguments 
> above.

The following are essentially our principles:

1) BPy types are thin wrappers around Blender data.  
	NO copying data back and forth.

2) BPy scripting should be 'familiar' to an experienced Blender user.  
	BPy should 'look like' Blender.

3) Move BPy types towards being full classes as Python provides the facilities 
  to do so. Atribute access using the tp_getset slot is part of this process.

-- 
Stephen Swaney			
sswaney at centurytel.net