deprecate validation on AsdfFile.tree assignment, AsdfFile.__init__ and AsdfFile.resolve_references

[braingram]

Description

This PR deprecates automatic validation on assignment to AsdfFile.tree. This long-undocumented feature (documentation added in asdf 3.0 #1599) can be replaced by a call to AsdfFile.validate after tree assignment (which is already necessary for tree assignments that don't replace the entire tree).

The eventual disabling of the deprecated feature will allow downstream code that currently uses the non-public _tree attribute (to avoid the validation on assignment) to be updated to use the public tree. Here are a few examples:

• https://github.com/spacetelescope/stdatamodels/blob/4a06de96585dad1c8497e4fd01d4041ee2c210b4/src/stdatamodels/model_base.py#L623
• https://github.com/spacetelescope/stdatamodels/blob/4a06de96585dad1c8497e4fd01d4041ee2c210b4/src/stdatamodels/fits_support.py#L772

In addition to mentioning this change in the docs and changelog a deprecation warning is added which is triggered only on failed validation during AsdfFile.tree assignment. This was done to avoid raising a warning for every AsdfFile.tree assignment. As these warnings typically only show during test suite runs it will hopefully signal to any downstream developers that might be relying on the validation on AsdfFile.tree assignment. A survey of AsdfFile.tree assignment in all packages in our downstream testing suggests the deprecation and removal of this feature should only have the positive effect of removing many unnecessary validations (see below for an example).

In this example from roman_datamodels.datamodels._core:

    def to_asdf(self, init, *args, **kwargs):
        with validate.nuke_validation():
            asdffile = self.open_asdf(**kwargs)
            asdffile.tree = {"roman": self._instance}
            asdffile.write_to(init, *args, **kwargs)

While writing out this model to an ASDF file, the model is validated (the nuke_validation setting is off by default) first on assignment to asdffile.tree (due to the feature deprecated in this PR) and validated a second time during the call to asdffile.write_to.

The roman_datamodels downstream failures are due to the new warning (being turned into an error). The failing tests are mostly from the same code used in the example above. The code could be updated (in this case) to avoid the duplicate validation and pass all tests with the changes in this PR:

             asdffile["roman"] = self._instance
             asdffile.write_to(init, *args, **kwargs)

If this PR is approved a PR can be opened against roman_datamodels with the above change to allow those tests to pass both with and without this asdf PR. After the change is made in roman_datamodels and the downstream test passes here this PR can be merged.

A few tests in roman_datamodels also assume validation on AsdfFile.__init__. This branch has updates sufficient to allow all roman_datamodels tests to pass with the source branch for this PR: spacetelescope/roman_datamodels@main...braingram:roman_datamodels:duplicate_validation

Fixes #315

Checklist:

• pre-commit checks ran successfully
• tests ran successfully
• for a public change, a changelog entry was added
• for a public change, documentation was updated
• for any new features, unit tests were added

[eslavich]

This is a nice compromise...

[eslavich]

You may have told me this on Friday and I just forgot, but why not also deprecate the validation here?

[braingram]

Great idea! I added a warning in: b8a80a5

This change triggered some more warnings (turned into errors) in roman_datamodels.

[eslavich]

I also don't see the value of validating here, but maybe just a failure of imagination.

[braingram]

Great idea! I deprecated this (and the unused kwargs) in: afe8f86

[eslavich]

Does this bit need to change now that we've also removed validation when constructing a new AsdfFile?

[braingram]

Yes! Thanks for finding this. I removed this mention in 97a09a5

[eslavich]

🚀

[braingram]

The CI failure for stdatamodels is also seen in stdatamodels main and addressed in: spacetelescope/stdatamodels#260