add AsdfDeprecationWarning to AsdfFile.blocks

[braingram]

Public use of the block manager will be removed in ASDF 3.0 to allow for major changes to it's API. It is currently used by the legacy extensions (also removed in ASDF 3.0). The new converters do not currently have block storage access.

To provide a sense for possible breaking changes to the block manager and block storage access, the current experimental branch that adds block storage access to converters passes all block manager calls through the serialization context:
4f62156
Adding block storage access to the converter is scheduled for ASDF 3.0 and the API and implementation details are not yet finalized.

Fixes issue #1335

[braingram]

The error in asdf-astropy is interesting and may be a bug in asdf.
https://github.com/asdf-format/asdf/actions/runs/4046535979/jobs/6959444733

The tests triggered by the fits schema:
https://github.com/astropy/asdf-astropy/blob/main/asdf_astropy/resources/schemas/fits/fits-1.0.0.yaml
result in an attempt to serialize and deserialize an object with tag tag:astropy.org:astropy/fits/fits-1.0.0. This correctly uses to_yaml_tree and from_yaml_tree from the converter in asdf-astropy. However, the astropy.io.misc.asdf uses the same tag for FitsType which defines a reserve_blocks (I'm not sure why it needs to reserve blocks). https://github.com/astropy/astropy/blob/070fc3ce0e5bfeeecc0582844dc8a968f254dd7a/astropy/io/misc/asdf/tags/fits/fits.py#L68-L72
This results in FitsType.reserve_blocks being called on an object that is then serialized with AstropyFitsConverter.

It seems to me that finding a converter should prevent the use of the type similar to what is done during serialization:

asdf/asdf/yamlutil.py

Lines 256 to 266 in da32b40

	if extension_manager.handles_type(type(obj)):
	return _convert_obj(obj)
	tag = ctx.type_index.from_custom_type(
	type(obj),
	ctx.version_string,
	_serialization_context=_serialization_context,
	)
	if tag is not None:
	return tag.to_tree_tagged(obj, ctx)

but no such check is done:

asdf/asdf/block.py

Lines 558 to 562 in da32b40

	for node in treeutil.iter_tree(tree):
	hook = ctx.type_index.get_hook_for_type("reserve_blocks", type(node), ctx.version_string)
	if hook is not None:
	for block in hook(node, ctx):
	reserved_blocks.add(block)

[WilliamJamieson]

However, the astropy.io.misc.asdf uses the same tag for FitsType which defines a reserve_blocks (I'm not sure why it needs to reserve blocks). astropy/astropy@070fc3c/astropy/io/misc/asdf/tags/fits/fits.py#L68-L72 This results in FitsType.reserve_blocks being called on an object that is then serialized with AstropyFitsConverter.

This is irrelevant as astropy.io.misc.asdf is deprecated, and we have already agreed with astropy that astropy.io.misc.asdf will not support ASDF 3.0. Thus we don't need to bend over backwards to support it. Astropy can be specifically updated to skip the ASDF related tests for ASDF < 3 and ignore the deprecation warnings for ASDF 2.15.

[braingram]

This is irrelevant as astropy.io.misc.asdf is deprecated, and we have already agreed with astropy that astropy.io.misc.asdf will not support ASDF 3.0. Thus we don't need to bend over backwards to support it. Astropy can be specifically updated to skip the ASDF related tests for ASDF < 3 and ignore the deprecation warnings for ASDF 2.15.

That all sounds good. I opened a PR to fix the issue as it looks like a bug in asdf where it shouldn't be calling reserve_blocks on an object that will be serialized with a converter.

I looked into ignoring the warnings for specific astropy tests and I think the following should suffice if we're happy with the format of the warnings:
astropy/astropy@460f2bd

[braingram]

@WilliamJamieson What are your thoughts on this as a way to keep our downstream CI from failing until astropy is updated to ignore this new deprecation?

[WilliamJamieson]

This is fine

[WilliamJamieson]

This might be out of scope, but as we add these deprecation warnings, we should create a distinct page in the docs which calls out all of them. We may want to include notes on timelines for removal (maybe link to mitigation strategies too).

[WilliamJamieson]

Suggestion, more than a request maybe we should have a test_deprecated.py for this. We are going to have a bunch more deprecation warnings that we are going to have to test. It would be nice if those were all in one spot so that we can strip them out when they are done.

[braingram]

Excellent idea. I opened an issue to track this:
#1346