[Bf-python] API overhaul - irc meeting?

[Gilbert, Joseph T.]

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

Agreed yea.
>>>1)Yes were things are not thin wrappers we need to change that. (my
code included). 
2) This point includes sticking to UI naming for attributes. The script
writer needs to see things he understands. When there is a conflict
between a UI name and a struct attribute name the UI name is what goes
in the API.
3) tp_init/tp_new where needed. (Some classes will need factory
functions) tp_getset needed.



-----Original Message-----
From: bf-python-bounces at projects.blender.org
[mailto:bf-python-bounces at projects.blender.org] On Behalf Of Stephen
Swaney
Sent: Sunday, January 08, 2006 12:05 PM
To: Blender Foundation Python list
Subject: Re: [Bf-python] API overhaul - irc meeting?

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

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