[Bf-taskforce25] Proposal: Blender API revisited

[Campbell Barton]

Good summery, It could just as well be a consensus :)

+1, all things considered this is one of the best options, but there
are a few things that can go wrong.

Re: a - Making operators and PyAPI functions share property
definitions would help a lot here. (as venkoon suggests)

Re: c - Apart from Operator counterparts not getting written in the
first place, lack of testing is the most likely problem IMHO. But this
is still a lot better then the 2.4x api which often has 3 accessor
functions with 6 docstrings (3 for C, 3 for epydocs) for a single
setting.

With an operator like interface to the api functions unit testing is
easier, (can print a list of all functions not yet in the unit tests)

Brecht suggested we can generate a list of Operators & API functions
that are added or change between releases. These can be included in
the documentation to help people update their scripts.

With all the time I get from not having to maintain Blender2.4x api Id
be happy to do unit tests for the new api and generate changes between
versions. :)

Re: d - Two API's is OK but how do we deal with changes to the api?
(that could break scripts)
If operators change with new blender versions this can break macro's too.
Id rather have PyAPI functions change with the operators, otherwise
some operators and API functions will become different over time, with
irrelevant properties & functions hanging around.
With generated change-logs between releases this is not as bad as with
2.4x api breakage.


This will break the "Python should not be able to do stuff users cant
do" - rule which will make Ton sad.  Sneaky python devs will add all
sorts of evil yet useful functions.

- Campbell

On Fri, Mar 20, 2009 at 11:52 AM, Brecht Van Lommel <brecht at blender.org> wrote:
>
> After some IRC discussion with Campbell, some issues that came up (hope
> I'm summarizing this well). The comments on the issues are mine, not a
> consensus between us :).
>
>
> a) Lazy developers will only update Operators and not the API.
>
> Once an operator uses an API function call, changing the operator
> properties will require the API function to be updated too. If that gets
> out of sync, it should generate a compile error or at least a compiler
> warning.
>
> There's still the issue though that for new operators no API function
> may be added. I don't think it would be more work than doing
> context-decoupling of the operator, but if they are separate things it's
> easier to make excuses..
>
> b) Code duplication.
>
> As vekoon mentioned, we could let the operators copy properties and
> description from the API function. It would do the job I think.
>
> c) API may not get tested well.
>
> The core code that runs is the same for Operators and API. What can go
> wrong is that the API function does not do some check but instead does
> it in the operator (e.g. for library linking). If other operators do
> this correct I guess it will stand out? Not sure if there are other
> typical mistakes that could be made.
>
> d) Python will have "two API's".
>
> This is true, though it is not entirely bad in my opinion. You would be
> able to call a tool, or call a member function on an object, they would
> be quite different styles of scripting anyway?
>
> Some operators will not have a corresponding API function because they
> are not useful there, and some API functions will not be useful as an
> operator. For the ones that do have both, they would still be consistent
> if properties and description are copied from the API function to the
> operator.
>
>
> I don't have a good answer to all these issues, but from my point of
> view the tradeoffs are acceptable?
>
> Brecht.
>
>
> _______________________________________________
> Bf-taskforce25 mailing list
> Bf-taskforce25 at blender.org
> http://lists.blender.org/mailman/listinfo/bf-taskforce25