[Bf-taskforce25] Operator PyAPI

[Brecht Van Lommel]

Hi,

On Wed, 2008-12-03 at 03:16 +1100, Campbell Barton wrote:
> For auto wrapping the operator api we'd need something similar to RNA,
> where operator definitions are stored (docstrings would be nice too)
> Just wondering if this is planned.

Operators are currently defined as wmOperatorType's, this is done by
the window manager, maybe that needs to be separated indeed, if we want
to do background mode without a window manager but still with
operators. There's currently a human readable name and unique
identifier, and its properties are defined with RNA, though there is no
function name or description/docstring.

> If the operators revieve (context, IDprop) this means python only
> needs a list of function names, so it should not be that big a deal.
> 
> Mentioning now since an auto PyAPI for operators relies on this.
> 
> from python, keyword args could be converted into ID props by the C api.
>   context.transform(scale=(1,1,2), space='LOCAL', filter=mySelFunc)
> 
> or if we want it to be more state based...
>   from Operators import *
>   context.setActive()
>   transform(scale=(1,1,2), space='LOCAL', filter=mySelFunc)

I think it would be interesting to have context and operator inputs
overlap, so if something was in the context with name "selected_objects"
it could be automatically passed to operators with an argument named the
same way. So if that was used this wouldn't be mutually exclusive. Not
sure yet if that is a good idea though, or if that system should be used
for python, since it has downsides too..
http://wiki.blender.org/index.php/BlenderDev/Blender2.5/Context#Context_Design

> Notes
> * using ID props to set return values was discussed, maybe this means
> we have to use  ID props from python (not convert keyword args)

The current operator type does not make a distinction between inputs
and outputs, which should be added for python probably. I think it is
sensible to use RNA / ID properties for setting return values inside
the operator. How python then best deals with that I'm not sure,
working on some operator object, returning a dictionary, or just
returning a tuple. I suppose using names explicitly for specifying
inputs and getting outputs is easier for preserving compatibility with
future changes.

> * a way for the operators to return an exception is needed, again this
> could be set in the ID prop thats passed to the function, or it could
> share an exception method with RNA which also needs one.

Still thinking about design for exceptions/errors/warnings/.. . I'd like
to make exceptions in a way that you can just report them into the
context. Then while an operator is running, or a modifier is being
evaluated, or some other case, the caller can but it's on report list in
the context, and can then decided what to do with it when the call is
done.

Brecht.