setAnnotations() deleting existing annotations
Adding new annotations to an entity with setAnnotations() will cause existing annotations to be removed. This behavior isn't described in the documentation, so it is very easy to accidentally remove annotations when one is trying to add some new ones. To me, this is pretty unintuitive and I'd expect setAnnotations() to add/update annotations but leave others that aren't being updated untouched. Would it be possible to add an option to preserve existing annotations (the way the command line client does by default)? If not, could we add documentation of the current behavior?
Thanks for dropping a notes. Please keep doing it. I added a label “Consistency” to this ticket. So that when we revisit the the APIs at the whole and can see which consistency issues need to be addressed. Please feel free to add the same label and/ or comment to other Jira tickets.
Just adding a note here that the behavior of synSetAnnotations() is different in this regard from synSetPermissions(). synSetPermissions() updates the specific permissions you request, but not any others.
The simplest compromise may be to add a parameter keep_existing, which defaults to False. This will keep the current behavior of setAnnotations but will change the paradigm from “I am replacing this dictionary with another dictionary” to “I am replacing these key value pairs with other key value pairs”.
I’d support having a separate function if it were clear which one does which thing. Maybe addAnnotations()?
I don’t think the method Tom described has an equivalent in the R client. This does not impact the annotations:
And x$annotations is a python dict, not any type of R data structure, so it’s not clear how to edit/add to it. If this is the official way to add annotations then it should be supported in both clients.
I was confused about setAnnotations as well, but from many conversations, the 'set' operation as larsson describes implies that you are erasing all old and creating annotations with the dictionary you are providing.