Deprecate AsdfExtension, AsdfExtensionList, BuiltinExtension

CHANGES.rst

@@ -31,6 +31,7 @@ The ASDF Standard is at v1.6.0
 - deprecate default_extensions, get_default_resolver and
   get_cached_asdf_extension_list in asdf.extension [#1409]
 - move asdf.types.format_tag to asdf.testing.helpers.format_tag [#1433]
+- Deprecate AsdfExtenion, AsdfExtensionList, BuiltinExtension [#1429]
 
 2.14.3 (2022-12-15)
 -------------------

asdf/__init__.py

@@ -27,7 +27,17 @@
 from .asdf import AsdfFile
 from .asdf import open_asdf as open  # noqa: A001
 from .config import config_context, get_config
-from .extension import AsdfExtension
 from .stream import Stream
 from .tags.core import IntegerType
 from .tags.core.external_reference import ExternalArrayReference
+
+
+def __getattr__(name):
+    if name == "AsdfExtension":
+        # defer import to only issue deprecation warning when
+        # asdf.AsdfExtension is used
+        from asdf import extension
+
+        return extension.AsdfExtension
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

asdf/asdf.py

@@ -16,8 +16,7 @@
 from ._helpers import validate_version
 from .config import config_context, get_config
 from .exceptions import AsdfConversionWarning, AsdfDeprecationWarning, AsdfWarning
-from .extension import AsdfExtension, AsdfExtensionList, Extension, ExtensionProxy, get_cached_extension_manager
-from .extension._legacy import get_cached_asdf_extension_list
+from .extension import Extension, ExtensionProxy, _legacy, get_cached_extension_manager
 from .search import AsdfSearchResult
 from .tags.core import AsdfObject, ExtensionMetadata, HistoryEntry, Software
 from .util import NotSet
@@ -276,7 +275,9 @@ def extension_list(self):
     @property
     def _extension_list(self):
         if self._extension_list_ is None:
-            self._extension_list_ = get_cached_asdf_extension_list(self._user_extensions + self._plugin_extensions)
+            self._extension_list_ = _legacy.get_cached_asdf_extension_list(
+                self._user_extensions + self._plugin_extensions,
+            )
         return self._extension_list_
 
     def __enter__(self):
@@ -379,9 +380,9 @@ def _process_user_extensions(self, extensions):
         """
         if extensions is None:
             extensions = []
-        elif isinstance(extensions, (AsdfExtension, Extension, ExtensionProxy)):
+        elif isinstance(extensions, (_legacy.AsdfExtension, Extension, ExtensionProxy)):
             extensions = [extensions]
-        elif isinstance(extensions, AsdfExtensionList):
+        elif isinstance(extensions, _legacy.AsdfExtensionList):
             extensions = extensions.extensions
 
         if not isinstance(extensions, list):

asdf/entry_points.py

@@ -69,6 +69,17 @@ def _handle_error(e):
                         category=AsdfDeprecationWarning,
                         message="asdf.types is deprecated",
                     )
+                    warnings.filterwarnings(
+                        "ignore",
+                        category=AsdfDeprecationWarning,
+                        message="AsdfExtension is deprecated",
+                    )
+                    warnings.filterwarnings(
+                        "ignore",
+                        category=AsdfDeprecationWarning,
+                        message="BuiltinExtension is deprecated",
+                    )
+
                 elements = entry_point.load()()
 
         except Exception as e:  # noqa: BLE001

asdf/extension/__init__.py

@@ -10,7 +10,6 @@
 from ._compressor import Compressor
 from ._converter import Converter, ConverterProxy
 from ._extension import Extension, ExtensionProxy
-from ._legacy import AsdfExtension, AsdfExtensionList, BuiltinExtension
 from ._manager import ExtensionManager, get_cached_extension_manager
 from ._manifest import ManifestExtension
 from ._tag import TagDefinition
@@ -77,14 +76,22 @@ def get_default_resolver():
     return get_default_resolver()
 
 
+_deprecated_legacy = {
+    "default_extensions",
+    "AsdfExtension",
+    "AsdfExtensionList",
+    "BuiltinExtension",
+}
+
+
 def __getattr__(name):
-    if name == "default_extensions":
+    if name in _deprecated_legacy:
         warnings.warn(
-            "default_extensions is deprecated. "
+            f"{name} is deprecated. "
             "Please see the new extension API "
             "https://asdf.readthedocs.io/en/stable/asdf/extending/converters.html",
             AsdfDeprecationWarning,
         )
-        return _legacy.default_extensions
+        return getattr(_legacy, name)
     msg = f"module {__name__!r} has no attribute {name!r}"
     raise AttributeError(msg)

asdf/tests/test_asdf.py

@@ -8,7 +8,8 @@
 from asdf.asdf import AsdfFile, SerializationContext, open_asdf
 from asdf.entry_points import get_extensions
 from asdf.exceptions import AsdfWarning
-from asdf.extension import AsdfExtensionList, ExtensionManager, ExtensionProxy
+from asdf.extension import ExtensionManager, ExtensionProxy
+from asdf.extension._legacy import AsdfExtensionList
 from asdf.tests.helpers import assert_no_warnings, assert_tree_match, yaml_to_asdf
 from asdf.versioning import AsdfVersion
 

asdf/tests/test_config.py

@@ -6,7 +6,8 @@
 import asdf
 from asdf import get_config
 from asdf.core._integration import get_json_schema_resource_mappings
-from asdf.extension import BuiltinExtension, ExtensionProxy
+from asdf.extension import ExtensionProxy
+from asdf.extension._legacy import BuiltinExtension
 from asdf.resource import ResourceMappingProxy
 
 

asdf/tests/test_deprecated.py

@@ -92,3 +92,14 @@ def test_asdf_type_format_tag():
     with pytest.warns(AsdfDeprecationWarning, match="asdf.types.format_tag is deprecated"):
         asdf._types.format_tag
     asdf.testing.helpers.format_tag
+
+
+@pytest.mark.parametrize("name", ["AsdfExtension", "AsdfExtensionList", "BuiltinExtension"])
+def test_extension_class_deprecation(name):
+    with pytest.warns(AsdfDeprecationWarning, match=f"{name} is deprecated"):
+        getattr(asdf.extension, name)
+
+
+def test_top_level_asdf_extension_deprecation():
+    with pytest.warns(AsdfDeprecationWarning, match="AsdfExtension is deprecated"):
+        asdf.AsdfExtension

asdf/tests/test_extension.py

@@ -5,8 +5,6 @@
 from asdf._types import CustomType
 from asdf.exceptions import AsdfDeprecationWarning, ValidationError
 from asdf.extension import (
-    AsdfExtension,
-    BuiltinExtension,
     Compressor,
     Converter,
     ConverterProxy,
@@ -19,6 +17,7 @@
     get_cached_asdf_extension_list,
     get_cached_extension_manager,
 )
+from asdf.extension._legacy import AsdfExtension, BuiltinExtension
 from asdf.tests.helpers import assert_extension_correctness
 
 

asdf/tests/test_types.py

@@ -5,8 +5,9 @@
 
 import asdf
 from asdf import _types as types
-from asdf import extension, util, versioning
+from asdf import util, versioning
 from asdf.exceptions import AsdfConversionWarning, AsdfDeprecationWarning, AsdfWarning
+from asdf.extension import _legacy
 
 from . import helpers
 from .objects import CustomExtension, CustomTestType
@@ -335,7 +336,7 @@ def tag_mapping(self):
         def url_mapping(self):
             return [("http://stsci.edu/schemas/asdf/core/", "FOOBAR/{url_suffix}")]
 
-    extension_list = extension.AsdfExtensionList([extension.BuiltinExtension(), FancyComplexExtension()])
+    extension_list = _legacy.AsdfExtensionList([_legacy.BuiltinExtension(), FancyComplexExtension()])
 
     assert extension_list.url_mapping("http://stsci.edu/schemas/asdf/core/asdf-1.0.0") == "FOOBAR/asdf-1.0.0"
     assert (

asdf/tests/test_util.py

@@ -3,7 +3,7 @@
 import pytest
 
 from asdf import generic_io, util
-from asdf.extension import BuiltinExtension
+from asdf.extension._legacy import BuiltinExtension
 
 
 def test_is_primitive():

pyproject.toml

@@ -58,7 +58,7 @@ tests = [
 [project.entry-points]
 'asdf.extensions' = {asdf = 'asdf.core._integration:get_extensions'}
 'asdf.resource_mappings' = {asdf = 'asdf.core._integration:get_json_schema_resource_mappings'}
-asdf_extensions = {builtin = 'asdf.extension:BuiltinExtension'}
+asdf_extensions = {builtin = 'asdf.extension._legacy:BuiltinExtension'}
 console_scripts = {asdftool = 'asdf.commands.main:main'}
 pytest11 = {asdf_schema_tester = 'pytest_asdf.plugin'}
 

tox.ini

@@ -161,7 +161,8 @@ commands_pre =
 commands =
     pytest specutils \
         -W "ignore::asdf.exceptions.AsdfDeprecationWarning:asdf.fits_embed" \
-        -W "ignore::asdf.exceptions.AsdfDeprecationWarning:asdf.types"
+        -W "ignore::asdf.exceptions.AsdfDeprecationWarning:asdf.types" \
+        -W "ignore::asdf.exceptions.AsdfDeprecationWarning:asdf.extension"
 
 [testenv:gwcs]
 change_dir = {env_tmp_dir}