Deprecate beets.autotag.Distance beets.autotag.current_metadata

beets/autotag/__init__.py

@@ -16,15 +16,16 @@
 
 from __future__ import annotations
 
+import warnings
+from importlib import import_module
 from typing import TYPE_CHECKING, Union
 
 from beets import config, logging
-from beets.util import get_most_common_tags as current_metadata
 
 # Parts of external interface.
 from beets.util import unique_list
 
-from .distance import Distance
+from ..util import deprecate_imports
 from .hooks import AlbumInfo, AlbumMatch, TrackInfo, TrackMatch
 from .match import Proposal, Recommendation, tag_album, tag_item
 
@@ -33,10 +34,27 @@ if TYPE_CHECKING:
 
     from beets.library import Album, Item, LibModel
 
+
+def __getattr__(name: str):
+    if name == "current_metadata":
+        warnings.warn(
+            (
+                f"'beets.autotag.{name}' is deprecated and will be removed in"
+                " 3.0.0. Use 'beets.util.get_most_common_tags' instead."
+            ),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return import_module("beets.util").get_most_common_tags
+
+    return deprecate_imports(
+        __name__, {"Distance": "beets.autotag.distance"}, name, "3.0.0"
+    )
+
+
 __all__ = [
     "AlbumInfo",
     "AlbumMatch",
-    "Distance",  # for backwards compatibility
     "Proposal",
     "Recommendation",
     "TrackInfo",
@@ -44,7 +62,6 @@ __all__ = [
     "apply_album_metadata",
     "apply_item_metadata",
     "apply_metadata",
-    "current_metadata",  # for backwards compatibility
     "tag_album",
     "tag_item",
 ]

beets/library/__init__.py

@@ -1,5 +1,4 @@
-import warnings
-from importlib import import_module
+from beets.util import deprecate_imports
 
 from .exceptions import FileOperationError, ReadError, WriteError
 from .library import Library
@@ -14,18 +13,7 @@ NEW_MODULE_BY_NAME = dict.fromkeys(
 
 
 def __getattr__(name: str):
-    if name in NEW_MODULE_BY_NAME:
-        new_module = NEW_MODULE_BY_NAME[name]
-        warnings.warn(
-            (
-                f"'beets.library.{name}' import is deprecated and will be removed"
-                f"in v3.0.0; import '{new_module}.{name}' instead."
-            ),
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return getattr(import_module(new_module), name)
-    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+    return deprecate_imports(__name__, NEW_MODULE_BY_NAME, name, "3.0.0")
 
 
 __all__ = [

beets/util/__init__.py

@@ -27,6 +27,7 @@ import subprocess
 import sys
 import tempfile
 import traceback
+import warnings
 from collections import Counter
 from collections.abc import Sequence
 from contextlib import suppress
@@ -1191,3 +1192,26 @@ def get_temp_filename(
 def unique_list(elements: Iterable[T]) -> list[T]:
     """Return a list with unique elements in the original order."""
     return list(dict.fromkeys(elements))
+
+
+def deprecate_imports(
+    old_module: str, new_module_by_name: dict[str, str], name: str, version: str
+) -> Any:
+    """Handle deprecated module imports by redirecting to new locations.
+
+    Facilitates gradual migration of module structure by intercepting import
+    attempts for relocated functionality. Issues deprecation warnings while
+    transparently providing access to the moved implementation, allowing
+    existing code to continue working during transition periods.
+    """
+    if new_module := new_module_by_name.get(name):
+        warnings.warn(
+            (
+                f"'{old_module}.{name}' is deprecated and will be removed"
+                f" in {version}. Use '{new_module}.{name}' instead."
+            ),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return getattr(import_module(new_module), name)
+    raise AttributeError(f"module '{old_module}' has no attribute '{name}'")

docs/changelog.rst

@@ -76,13 +76,15 @@ For plugin developers:
         ``album_for_id``, ``candidates``, ``item_candidates``, ``album_distance``, ``track_distance`` methods,
         please update your plugin to inherit from the new baseclass, as otherwise your plugin will
         stop working with the next major release.
-* Several definitions have been moved away from ``beets.library`` module:
-  * ``BLOB_TYPE`` constant, ``PathQuery`` and ``SingletonQuery`` queries have moved
-    to ``beets.dbcore.queries`` module
-  * ``DateType``, ``DurationType``, ``PathType`` types and ``MusicalKey`` class have
-    moved to ``beets.dbcore.types`` module.
-  Old imports are now deprecated and will be removed in version ``3.0.0``.
-
+* Several definitions have been moved:
+    * ``BLOB_TYPE`` constant, ``PathQuery`` and ``SingletonQuery`` queries have
+      moved from ``beets.library`` to ``beets.dbcore.query`` module
+    * ``DateType``, ``DurationType``, ``PathType`` types and ``MusicalKey``
+      class have moved from ``beets.library`` to ``beets.dbcore.types`` module.
+    * ``Distance`` has moved from ``beets.autotag`` to
+      ``beets.autotag.distance`` module.
+    * ``beets.autotag.current_metadata`` has been renamed to
+      ``beets.util.get_most_common_tags``.
 
 Other changes: