Ignition 8.0.3-nightly
when I read a custom tag property with the Document type, ignition return a com.inductiveautomation.ignition.common.script.adapters.PyDocumentObjectAdapter
with .toDic() we can get a python dictionnary to be able to use the value in Ignition.
Is there any reason why the value in the qualified value returned by the system.tag.readBlocking is not directly the python dictionnary ???
I’m not aware of any reason (doesn’t mean one doesn’t exist), but it does seem to me like that would be the better experience. I’m going to create a ticket to investigate/discuss our handling of Document types in scripting and we’ll see what we can come up with.
A further note, while toDict() does work to typecast the document to a dictionary, you cant then write it back to the tag.
So if I want to edit a document tag, I have to grab the value and cast it with toDict() and then I ALSO have to system.util.jsonEncode() it and write it as a string? Feels a little wonky
eg:
tagPath = "[default]Example"
tag = system.tag.read(tagPath).value.toDict()
tag["exampleArray"].append([55])
##Works (But I have to convert the dictionary into a string first?)
encodedTag = system.util.jsonEncode(tag)
system.tag.writeBlocking([tagPath], [encodedTag])
#Doesnt work but should
system.tag.writeBlocking([tagPath], [tag])
Yeah, this is wonky. I’m glad I finally found the toDict() method to get the .PyDocumentObjectAdapter.PyDocumentObjectAdapter coverted to an ordinary dictionary. The documentation isn’t very good online for this!
Any news on this ?
I have to edit a tag value of type Document and it’s a pain.
Reading with system.tag.readBlocking returns a PyDocumentObjectAdapter, which doesn’t support item assignment, so I have to convert it with toDict(), but then this can’t be written back to the tag with system.tag.writeBlocking because Error_TypeConversion("Cannot coerce to document from class type 'class org.python.core.PyDictionary'").
Now, I can do it with system.tag.getConfiguration, converting the value property with toDict, then writing back the tag with system.tag.configure(base_path, tag, 'm'), but this feels like more steps than it should be.
Did I miss something ? Shouldn’t I edit document values ?
Side note: I tried any combination of dir, help and type I could think of on the different objects/wrappers/adapters I get with those tag handling functions, but there is no documentation whatsoever.
For example, the `PyDocumentObjectAdapter seems to have a get method. Couldn’t find how to use it:
obj = system.tag.readBlocking("[]tag")[0].getValue()
type(obj)
# -> <type 'com.inductiveautomation.ignition.common.script.adapters.PyDocumentObjectAdapter'>
dir(obj)
# -> [..., 'get', ..., 'toDict',...]
obj.get('foo')
# -> TypeError: get(): expected 2 args; got 1
obj.get('foo', 'bar')
# -> this actually returns the value of key foo in my dict, but... what is 'bar' ? What is going on ?
help(obj.get)
# -> get(...) method of com.inductiveautomation.ignition.common.script.adapters.PyDocumentObjectAdapter instance
help(type(obj.get))
# -> absolutely no useful information there
I can guess that the second argument is the default to return if the key isn’t found, and it’s easy to test, but…
This is the case with basically anything returned by anything.
I like ignition a lot, you guys have done a wonderful job. But the documentation… just doesn’t exist.
From two posts above.
As he says: feels a little wonky. Same problem as with getConfiguration and configure: feels like more steps than it should be.
I’d feel better with readBlocking returning a dict.
No, you shouldn't. Like Datasets, if you want to make an edit you should mutate a copy and write that copy back.
It's not safe to mutate the values of a "container" object you get from reading a tag. I think this applies to Document, Dataset, and array types. This is probably why that PyDocumentObjectAdapter class doesn't have any methods that let you mutate it.
Why would it give you back an immutable container reference object in the basic qualified value, instead of just a mutable copy of the object? I have used document and dataset tags tons of times, and I can’t think of a single reason to have an immutable reference?
You would still retain immutability to the tag itself with a copy because then you’d have to write back to change the value?
I don’t know, I’m really just making some guesses based on what I’m seeing and what I know about the tag system.
Also FWIW, Documents are not python dictionaries. You guys continue to conflate that fact. They are a JSON AST object in memory. You guys just like to think of python dictionaries and JSON as the same.
Since the document in-designer editor is the same as the perspective property editor, I can see where users get the idea it should work more like an object than a json document
Me being one of those users 
lol