add note about implicit tuple to list conversion on write/read

[braingram]

As mentioned: #1588

asdf writes tuples as YAML sequences which are loaded as lists (not tuples). This PR describes the behavior in the documentation and mentions how a custom extension could be used to write/read tuples.

[WilliamJamieson]

Is there a reason why ASDF cannot round trip this? This seems antithetical to the core features of ASDF.

[perrygreenfield]

I think this PR does address that, doesn't it? Or are you raising a different issue? I thought the fundamental issue is that YAML doesn't itself distinguish between lists and tuples and the more natural interpretation for a YAML sequence is a list (in any case, the default has to be one or the other). With a tuple tag, round tripping should be possible. Perhaps this should be part of the standard itself? Even so, starting with an extension implementation isn't a bad place to start before making it part of the standard. But I may be missing the main point.

[WilliamJamieson]

Yes, tuples should be recognized and tagged so that they can be round-tripped. Why this note, technically informs the user of this limitation, it is not what an end user would necessarily expect based on how ASDF functions normally.

If we do not wish to support this (immutable sequences) by default then that should be added to the ASDF standard and then linked to here.

[perrygreenfield]

I would support that as the ultimate target (making it part of the standard). But that is a slower process and an extension could address it in the interim (or does that make it a more complex transition @braingram?). And languages that don't have such a distinction between lists and tuples can ignore it in their library if they wish, other than being careful to propagate the type.

[braingram]

Thanks all for your input.

Perhaps I should have clarified. This PR is not intended to solve the issue of tuple support (#1588 should remain open even if this PR is merged hence the lack of closing words).

I opened an issue on asdf-standard to discuss adding support for an tuple/immutable sequence: asdf-format/asdf-standard#393

I will follow up with some comments there but without spending some time looking at how pyyaml converts types I'm currently unsure if there are other transparent conversions and if there are other builtin python types (like frozenset) that should be considered for inclusion in the standard if we are adding a distinction between mutable and immutable types.

@perrygreenfield thanks for your question about adding tuple support via extension vs adding it to the core. One complication I can see is: what library should provide the extension? I don't see any custom tags in asdf, and if we add a non-standard tag we should likely allow users to disable this to make files that are fully defined by the standard. I don't think it makes sense to add a tuple converter to asdf-astropy so perhaps a new asdf-python package?

As mentioned in #1588 we might consider raising an exception if a tuple is encountered rather than transparently convert it to a list. Perhaps with a config setting to enable/disable this behavior (with the default matching the current behavior where tuples are converted to lists). Perhaps that can be discussed on #1588 to solicit feedback from the user that opened the issue?

[WilliamJamieson]

In my opinion support for tuple should be provided by the ASDF Python package as Python is the "package" which "owns" the type. Whether or not a tuple schema is incorporated into ASDF-standard or in a distinct set of schemas is a separate discussion.

Indeed, issue #1588 points out that working with basic types like tuple is something that users would naturally expect to work without needing to install additional things given how we describe it working.

As for frozenset the same issue applies. I think in general all the "built in" types which do not require one to import from somewhere should be supported by the Python implementation of ASDF. It looks like the two types with questionable support are tuple and frozenset. This way users can serialize data structured by the built in and always available types without immediate problems.

[eslavich]

Perfectly reasonable note that accurately summarizes the current state of the code and ASDF Standard support for tuple/immutable sequence.