Implement support for extension URIs

[eslavich]

This PR is branched off of #849. Here I'm adding support for extension URIs, where are defined as an attribute on the extension instance and are written to the file metadata. Technically this is part of the new extension API, but the change fit nicely into a separate PR.

There are two new extension attributes:

• extension_uri: The URI of the "extension to the ASDF Standard" that the extension class implements. Something like "asdf://somewhere.org/extensions/foo-1.0".
• legacy_class_names: The fully qualified names of extension classes that provided this functionality before the advent of URIs. This allows us to switch to URIs and change the class name without incurring warnings from the library.

Additionally I changed AsdfFile.__init__ and asdf.open to accept extension URIs in addition to extension instances.

[perrygreenfield]

One more thing I would add is that I think these changes should be accompanied by updates to the developer documentation to indicate how things work after these changes, otherwise it will become very outdated.

[perrygreenfield]

I realize it is a tall order, but eventually it would be nice to have complicated methods like this have a docstring summarizing their purpose.

[eslavich]

I'll add one to _check_extensions and _process_extensions now, since I just modified them.

[perrygreenfield]

Missing the description for the _serialization_context arguement.

[eslavich]

I omitted this intentionally, since it's not part of the public API. I didn't want to advertise it to external developers who might be using the method, since it's going to disappear in 3.0 anyway. Bad idea?

[perrygreenfield]

OK, perhaps a comment after the docstring should clarify the intent

[perrygreenfield]

Somewhere the concept of dynamic subclasses should be explained. In my search of the code, I didn't easily find it. Perhaps better explained in the developer documentation; more on that later

[eslavich]

I'm a little hazy on this myself, but I think the intention of this feature was to allow serialization of subclasses that didn't exist at the time that the TypeIndex was constructed. When building the type index, we inspect the __subclasses__ attribute of each type and insert all the sub-types into a dict for fast lookup. But that only finds subclasses that have already been imported. Setting handle_dynamic_subclasses = True causes the type index to make an actual issubclass check against the listed types so it can catch subclasses that were imported later. It's slower but more comprehensive.

The new API doesn't support any brand of automatically serializing sub-types. A type must be explicitly listed in a converter in order to be serialized. So when TypeIndex is dropped in 3.0 we won't have to worry about this import order issue anymore.

[perrygreenfield]

Like what exactly? There is no longer a _CompoundModel class, and no current subclasses of CompoundModel that I'm aware of. Or is this just to handle older versions of astropy?

[eslavich]

See my comment above, but I suspect the problem this was intended to solve was an import order issue. Without this feature, the following would succeed:

import SomeCustomCompoundModelSubclass
import asdf.type_index.TypeIndex

type_index = TypeIndex(...)

assert type_index.from_custom_type(SomeCustomCompoundModelSubclass) is not None

but this would fail:

import asdf.type_index.TypeIndex

type_index = TypeIndex(...)

import SomeCustomCompoundModelSubclass

assert type_index.from_custom_type(SomeCustomCompoundModelSubclass) is not None

[eslavich]

I created #861 as a reminder to update the developer documentation before release.