6.0.0 release changes

[braingram]

Some possible changes are:

• removal of deprecated features (that have had deprecation warnings in a minor release). Are there any items to remove?
• change of defaults (generally evaluate a way to perhaps warn for these default changes in a non-obtrusive way):
  • warn_on_failed_conversion: Consider option for allowing more graceful loading of files with failed conversions #1555 Some investigation of downstream impact is called for and consideration of recommendations for when to turn this off (for example for test suites that may want to exception).
  • save_array_base: Make default_array_save_base False #1994 changing this default seems overall an improvement
  • validate_on_read: Similar to warn_on_failed_conversion investigate downstream impact and when to turn this back on (test suites, etc)
• add ASDF for FITS users page: Add "ASDF for FITS users" page #2084

[sydduckworth]

Change already in main: deprecating direct external usage of GenericFile and passing duck-typed file objects to generic_io

[sydduckworth]

Regarding warnings for changes to default values, Numpy's process specifies using a subclass of FutureWarning which is raised when the value isn't explicitly passed.

The use of FutureWarning means that, unlike DeprecationWarning, it is shown to end-users as well.

We could do a heirarchy like FutureWarning -> AsdfFutureWarning -> SpecificOptionFutureWarning. That way users could easily silence all future warnings, or silence all asdf future warnings.

I've sketched out a demo implementation below:

Implementation

This implementation is maybe a bit over-designed, but the idea is to define a descriptor that can wrap a property like this:

import warnings
from typing import Any, Generic, TypeVar

_T = TypeVar("_T")


# Adapted from https://docs.python.org/3/howto/descriptor.html#properties
class _ChangingDefault(Generic[_T]):
    def __init__(
        self,
        prop,
        old_default: _T,
        new_default: _T,
        warning: type[Warning] = FutureWarning,
    ):
        self._prop = prop
        self.__doc__ = self._prop.__doc__
        self.old_default = old_default
        self.new_default = new_default
        self.warning = warning

        self.is_set = False

    def __set_name__(self, owner, name):
        self.__name__ = name

    def __get__(self, obj, objtype=None):
        if not self.is_set:
            msg = (
                f"In the future the default for {self.__name__} will be {self.new_default} "
                f"instead of the current default of {self.old_default}. "
                f"Explicitly pass {self.new_default} or {self.old_default} to silence this warning."
            )
            warnings.warn(msg, self.warning, stacklevel=2)
        return self._prop.__get__(obj, objtype)

    def __set__(self, obj, value):
        self.is_set = True
        return self._prop.__set__(obj, value)

    def __delete__(self, obj):
        self.is_set = False
        self._prop.__delete__(obj)

    def getter(self, fget):
        self._prop = type(self._prop)(fget, self._prop.fset, self._prop.fdel, self.__doc__)
        return self

    def setter(self, fset):
        self._prop = type(self._prop)(self._prop.fget, fset, self._prop.fdel, self.__doc__)
        return self

    def deleter(self, fdel):
        self._prop = type(self._prop)(self._prop.fget, self._prop.fset, fdel, self.__doc__)
        return self


def changing_default(old_default: _T, new_default: _T, warning: type[Warning]):
    def f(prop):
        return _ChangingDefault(prop, old_default, new_default, warning)

    return f

This allows you to just add the wrapper to the changing properties and set the old and new default values:

class Config:
    def __init__(self):
        self._my_value = 1

    @changing_default(1, 2)
    @property
    def my_value(self) -> int:
        return self._my_value

    @my_value.setter
    def my_value(self, value: int) -> None:
        self._my_value = value

The result is that when the property is accessed it will raise a warning if the value hasn't been manually set but no warning if it has (even if it's been set to the old default)

>>> cfg = Config()
>>> cfg.value
FutureWarning: In the future the default for value will be 2 instead of the current default of 1. Explicitly pass 2 or 1 to silence this warning.
 cfg.value
1
>>> cfg.value = 3
>>> cfg.value
3

This implementation emits a warning every time the property is accessed, relying on Python's duplicate warning suppression to handle cases where the property is accessed multiple times.

It could obviously instead be implemented to only emit a warning the first time the value is accessed.

[braingram]

Thanks for looking into this. I don't think we want these to generally appear to end users as they often do not and cannot set these values (for example where datamodels construct and manage the config). The tracking of setting may be helpful for downstream dealing with the change (they could explicitly set the upcoming default). Perhaps we can first evaluate how much impact the changes will have before deciding on a warning/deprecation method? One approach would be to change the defaults in a PR and run downstream/regression tests.

[sydduckworth]

We can always use DeprecationWarning instead of FutureWarning, but I do think if we try to be too unobtrusive we run the risk of downstream libraries/users not being aware of the upcoming change at all.