Move vfs.py to beetsplug._utils package to avoid polluting core namespace (#6017)

This PR moves the `vfs.py` module, which is only used by plugins, to
avoid polluting the main beets namespace. Also exposes the `vfs` and
`art` module from beets with a deprecation warning.

beets/__init__.py

@@ -17,10 +17,25 @@ from sys import stderr
 
 import confuse
 
+from .util import deprecate_imports
+
 __version__ = "2.4.0"
 __author__ = "Adrian Sampson <adrian@radbox.org>"
 
 
+def __getattr__(name: str):
+    """Handle deprecated imports."""
+    return deprecate_imports(
+        old_module=__name__,
+        new_module_by_name={
+            "art": "beetsplug._utils",
+            "vfs": "beetsplug._utils",
+        },
+        name=name,
+        version="3.0.0",
+    )
+
+
 class IncludeLazyConfig(confuse.LazyConfig):
     """A version of Confuse's LazyConfig that also merges in data from
     YAML files specified in an `include` setting.

beetsplug/_utils/__init__.py

@@ -0,0 +1,3 @@
+from . import art, vfs
+
+__all__ = ["art", "vfs"]

beetsplug/_utils/vfs.py

@@ -16,17 +16,25 @@
 libraries.
 """
 
-from typing import Any, NamedTuple
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NamedTuple
 
 from beets import util
 
+if TYPE_CHECKING:
+    from beets.library import Library
+
 
 class Node(NamedTuple):
-    files: dict[str, Any]
-    dirs: dict[str, Any]
+    files: dict[str, int]
+    # Maps filenames to Item ids.
+
+    dirs: dict[str, Node]
+    # Maps directory names to child nodes.
 
 
-def _insert(node, path, itemid):
+def _insert(node: Node, path: list[str], itemid: int):
     """Insert an item into a virtual filesystem node."""
     if len(path) == 1:
         # Last component. Insert file.
@@ -40,7 +48,7 @@ def _insert(node, path, itemid):
         _insert(node.dirs[dirname], rest, itemid)
 
 
-def libtree(lib):
+def libtree(lib: Library) -> Node:
     """Generates a filesystem-like directory tree for the files
     contained in `lib`. Filesystem nodes are (files, dirs) named
     tuples in which both components are dictionaries. The first

beetsplug/bench.py

@@ -17,10 +17,11 @@
 import cProfile
 import timeit
 
-from beets import importer, library, plugins, ui, vfs
+from beets import importer, library, plugins, ui
 from beets.autotag import match
 from beets.plugins import BeetsPlugin
 from beets.util.functemplate import Template
+from beetsplug._utils import vfs
 
 
 def aunique_benchmark(lib, prof):

beetsplug/bpd/__init__.py

@@ -30,10 +30,11 @@ from typing import TYPE_CHECKING
 
 import beets
 import beets.ui
-from beets import dbcore, logging, vfs
+from beets import dbcore, logging
 from beets.library import Item
 from beets.plugins import BeetsPlugin
 from beets.util import as_string, bluelet
+from beetsplug._utils import vfs
 
 if TYPE_CHECKING:
     from beets.dbcore.query import Query

docs/changelog.rst

@@ -48,6 +48,9 @@ Other changes:
 - Moved ``art.py`` utility module from ``beets`` into ``beetsplug`` namespace as
   it is not used in the core beets codebase. It can now be found in
   ``beetsplug._utils``.
+- Moved ``vfs.py`` utility module from ``beets`` into ``beetsplug`` namespace as
+  it is not used in the core beets codebase. It can now be found in
+  ``beetsplug._utils``.
 - :class:`beets.metadata_plugin.MetadataSourcePlugin`: Remove discogs specific
   disambiguation stripping.
 

test/plugins/utils/test_vfs.py

@@ -14,9 +14,9 @@
 
 """Tests for the virtual filesystem builder.."""
 
-from beets import vfs
 from beets.test import _common
 from beets.test.helper import BeetsTestCase
+from beetsplug._utils import vfs
 
 
 class VFSTest(BeetsTestCase):