From c79cad4ed1ba811e904ed38f9e1d49020a8709ca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=A0ar=C5=ABnas=20Nejus?= <snejus@protonmail.com>
Date: Fri, 24 Oct 2025 23:45:36 +0100
Subject: [PATCH] Move deprecate_imports to beets.util.deprecation

---
 beets/__init__.py         |  2 +-
 beets/autotag/__init__.py |  2 +-
 beets/library/__init__.py |  2 +-
 beets/util/__init__.py    | 24 ------------------------
 beets/util/deprecation.py | 26 ++++++++++++++++++++++++++
 5 files changed, 29 insertions(+), 27 deletions(-)
 create mode 100644 beets/util/deprecation.py

diff --git a/beets/__init__.py b/beets/__init__.py
index d448d8c49..4891010a5 100644
--- a/beets/__init__.py
+++ b/beets/__init__.py
@@ -17,7 +17,7 @@ from sys import stderr
 
 import confuse
 
-from .util import deprecate_imports
+from .util.deprecation import deprecate_imports
 
 __version__ = "2.5.1"
 __author__ = "Adrian Sampson <adrian@radbox.org>"
diff --git a/beets/autotag/__init__.py b/beets/autotag/__init__.py
index 8fa5a6864..f79b193fd 100644
--- a/beets/autotag/__init__.py
+++ b/beets/autotag/__init__.py
@@ -24,8 +24,8 @@ from beets import config, logging
 
 # Parts of external interface.
 from beets.util import unique_list
+from beets.util.deprecation import deprecate_imports
 
-from ..util import deprecate_imports
 from .hooks import AlbumInfo, AlbumMatch, TrackInfo, TrackMatch
 from .match import Proposal, Recommendation, tag_album, tag_item
 
diff --git a/beets/library/__init__.py b/beets/library/__init__.py
index b38381438..afde96e0c 100644
--- a/beets/library/__init__.py
+++ b/beets/library/__init__.py
@@ -1,4 +1,4 @@
-from beets.util import deprecate_imports
+from beets.util.deprecation import deprecate_imports
 
 from .exceptions import FileOperationError, ReadError, WriteError
 from .library import Library
diff --git a/beets/util/__init__.py b/beets/util/__init__.py
index 2592f612a..2d4bb8a65 100644
--- a/beets/util/__init__.py
+++ b/beets/util/__init__.py
@@ -27,7 +27,6 @@ import subprocess
 import sys
 import tempfile
 import traceback
-import warnings
 from collections import Counter
 from collections.abc import Callable, Sequence
 from contextlib import suppress
@@ -1195,26 +1194,3 @@ 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}'")
diff --git a/beets/util/deprecation.py b/beets/util/deprecation.py
new file mode 100644
index 000000000..4bc939cb4
--- /dev/null
+++ b/beets/util/deprecation.py
@@ -0,0 +1,26 @@
+import warnings
+from importlib import import_module
+from typing import Any
+
+
+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}'")