[Bf-taskforce25] Proposal: Blender API revisited

[Campbell Barton]

On Sat, Mar 21, 2009 at 5:05 PM, Nathan Vegdahl <cessen at cessen.com> wrote:
>> Re: a - Making operators and PyAPI functions share property
>> definitions would help a lot here. (as venkoon suggests)
> ...
>> 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.
>
> Certainly this makes sense in cases where there is a 1:1 mapping
> between operators and API functions.
>
> But presumably one of the benefits of having them be separate is that
> we don't have to force a 1:1 mapping where it doesn't make sense.
> Maybe there will be cases where it makes sense to split an op into two
> api functions, for example.  And I'm sure there will be plenty of api
> functions that just don't make sense as operators.
>
> Anyway, I'm not knocking what you're saying.  I'm just wondering how
> these things will be handled in cases that aren't 1:1 between ops and
> api.
>
> --Nathan V

Sure, I should have said this is only relevant when theres a 1:1 match.
Ofcourse if some properties only make sense for an operator or an API
call these differences are acceptable.

My point is that as operators are updated, properties will be
added/removed and operators could become irrelevant and be removed
too.
In cases where theres a close match I'd prefer to keep these functions in sync.
Otherwise it gets confusing to remember that the API function has some
differences to the operator that are only kept to maintain
comparability with older scripts.

In some cases an update to an operators changes some internal behavior.
If we really want to not break scripts we'd need to duplicate the
internal function and have the API call use an unmodified version of
the function.

Id rather not take the route, better allow some breakage but minimize
code duplication and confusion since this becomes hard to maintain.

This might seem a minor point but IMHO its worth thinking about how
this api will deal with internal changes in blender over 5+ years.

> On Sat, Mar 21, 2009 at 2:36 PM, Campbell Barton <ideasman42 at gmail.com> wrote:
>> 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
>> _______________________________________________
>> Bf-taskforce25 mailing list
>> Bf-taskforce25 at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>>
> _______________________________________________
> Bf-taskforce25 mailing list
> Bf-taskforce25 at blender.org
> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>



-- 
- Campbell