What's the difference between passive and active objects in the python API?

[psifertex]

Please explain the differences between things in the Python API that are "active" and things that are "passive".

[psifertex]

First, a quick refresher: Binary Ninja has a C++ core with a C API for binary compatibility (and multi-language bindings) and its most popular (but not only!) API for plugins is Python. That means when you use the Python API to request an objet from the core, some of those objects will represent a currently live, active object in the core. Changes you make in the core will be immediately reflected in the Python API and vice-versa.

For example:

>>> a = current_function
>>> a.name
_start
>>> #Use the UI and rename the function
>>> a.name
newname
>>> a.name = "different"
>>> # Look in the UI and the function has changed

Function objects are active.

(One rule of thumb is that if the python class has a handle, it's live)

Other objects in the Python API are passive and changes to that object exist only in the python API and not in the core.

Variables are one example of this class of object:

>>> a = current_function.vars[0]
>>> a.name
'var_648'
>>> # Change the variable in the UI
>>> a.name
'var_648'
>>> # Conversely, changing the python object does not change the UI

We're currently in the process of adding better documentation around objects in the API that are passive to make this less surprising (using the @decorators.passive decorator), but we figured a better explanation about the differences would be helpful here too!