[Bf-committers] Can we please stop breaking APIs?

Campbell Barton ideasman42 at gmail.com
Sat Jul 16 00:37:13 CEST 2011


On Fri, Jul 15, 2011 at 10:35 PM, Diego B <bdiego at gmail.com> wrote:
> Hello,
>
> On Fri, Jul 15, 2011 at 3:14 AM, Campbell Barton <ideasman42 at gmail.com> wrote:
>> Nope, the api is not stable and probably wont be until blender
>> development ceases.
>
> so.. that mean that the api never will be stable ? because blender is
> always in development, like
> any other software.

In practice we end up stabilizing most areas and don't just break
stuff indefinitely - But bigger changes mean api breakage is
unavoidable in most cases - BMesh, Particle Rewrite, Curves/Nurbs
branch... etc.

Since operators are effectively an API from python now it means
changing tool options will break scripts too.

> At this point, when you already have two version stable, you can't say
> "is not stable and probably wont be",
> because you are telling me that the api is just crap.

Yep, its crap, and IMHO there are 2 main reasons for this.

- Not having enough api maintainers who can sign off on an api being
`correct and proper` before a stable release so we know we wont need
to make changes later (I'd guess companies which release API's do
this).

- Our API is so closely related to blenders internals that its
impractical to make changes to blender without also making potentially
breaking changes to the api.

We can always say "Lets not break stuff", but IMHO this is worse long
term (and was attempted in 2.4x with only moderate success).

Take the recent change to bgl.Buffer.list
in previously we had...
>>> ls = obj['MyArray'].convert_to_pyobject() # id property access
>>> ls = bglbuffer.list  # bgl buffer

Both do the same thing and are poor choices of names.
The first because python language doesn't refer to PyObject's
internally (thats a C implementation name), the second because its an
attribute when it should be a function since its creating new,
converted data thats read-only, the use of an attribute is misleading.

Both are now called .to_list().

> We have the same problem here and it's a pain every time that you
> break de api, because I have to update
> four or five script... and the problem is that I always now about this
> because the user try to run the script
> and get an error...
>
> SO the thing is that the API is more a library that a program and you
> need keep things around and mark
> it as "deprecate" for two version (at least), doing that you can keep
> improve the api but at the same time
> you give an option to the user and the process is not so painful.

As I said before, I'm not against deprecating API in certain cases,
but its impractical to deprecate _every_ breakage (even most of them).

>> Instead we document what changes/breaks between releases, and try to
>> keep *reasonably* stable.
>> http://www.blender.org/documentation/blender_python_api_2_58_release/change_log.html
>
> This is a good idea, but soon or later will fail, if I don't remember
> bad Matt point a change the last week
> that break the script and was not in the list...

Yep, its not ideal and some changes can be missed, I had to manually
add in the changes Matt pointed out, though mostly this list is
generated from RNA.

> The thing is, that if you see a message "This function is deprecate
> and will be remove on Blender 2.5X"
> is easy to update things and don't stop the artist from work.
>
> And this is just the "user side", there are server when this is use to
> run differents script to build
> scene for render.. so the problem there is bigger..
>
> The point of all this is "by really reasonably" and put a "deprecate
> mark", in some case is a pain
> work with the blender api.

Agree we should deprecate in some cases - at the moment its arbitrary
when to do so. Currently I just check if any addons/scripts use it and
if its documented.
If not, this is a reasonable indication its not widely used. (nobody
complained when convert_to_pyobject() was renamed for eg.)

Diego, I'd be interested to know if the breakages you are referring to
are in our C api, RNA or python modules.

> -
>
>  Diego
>
>>
>> As for this change, I didn't think this module was in wide use (the
>> buffer part especially),
>> 'bgl' was quickly patched to work with python3, this module got left
>> behind with the initial api update/rewrite, still needs to be finished
>> porting to py3 (slicing) and only got docs working again recently.
>>
>> While I'm not totally against deprecation in some cases I suspect
>> you're one of the few people using this part of the API.
>>
>> A quick workaround to allow running with both versions.
>>
>> ls = buf.to_list() if hasattr(buf, "to_list") else getattr(buf, "list")
>>
>> On Fri, Jul 15, 2011 at 1:41 PM, Mitchell Stokes <mogurijin at gmail.com> wrote:
>>> Hello devs,
>>>
>>> I thought the 2.5 Python API was supposed to be considered "stable",
>>> but lo and behold, a recent commit once again broke my scripts. The
>>> commit in question changes BGL.Buffer.list to BGL.Buffer.to_list()
>>> [1]. Bgui[2] makes use of BGL and is now broken. Furthermore, if I fix
>>> Bgui to work with Blender trunk and I release a version of Bgui before
>>> Blender 2.59 (which is possible), then Bgui would have a requirement
>>> of needing an "in development" version of Blender. If we're going to
>>> be changing APIs, can we at least keep old things around as
>>> "deprecated" for a release or two?
>>>
>>> [1] http://lists.blender.org/pipermail/bf-blender-cvs/2011-July/037581.html
>>> [2] https://code.google.com/p/bgui/
>>>
>>> Thank you,
>>> Mitchell Stokes
>>> _______________________________________________
>>> Bf-committers mailing list
>>> Bf-committers at blender.org
>>> http://lists.blender.org/mailman/listinfo/bf-committers
>>>
>>
>>
>>
>> --
>> - Campbell
>> _______________________________________________
>> Bf-committers mailing list
>> Bf-committers at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-committers
>>
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at blender.org
> http://lists.blender.org/mailman/listinfo/bf-committers
>



-- 
- Campbell


More information about the Bf-committers mailing list