Move essential backend implementations to _backend

Move the actual I/O implementation to _backend submodule so that
the new _backend does not depend on the legacy backend,
and the existing backend submodule contains only what's related to legacy backend utilities.

The legacy implementation depends on the new one.

torchaudio/__init__.py

@@ -11,8 +11,7 @@
     transforms,
     utils,
 )
-from .backend.common import AudioMetaData
-
+from ._backend.common import AudioMetaData
 
 try:
     from .version import __version__, git_version  # noqa: F401
@@ -35,6 +34,10 @@ def _is_backend_dispatcher_enabled():
 _init_backend()
 
 
+# for backward compatibility. This has to happen after _backend is imported.
+from . import backend  # noqa: F401
+
+
 __all__ = [
     "AudioMetaData",
     "io",

torchaudio/_backend/backend.py

@@ -4,7 +4,7 @@
 
 from torch import Tensor
 
-from torchaudio.backend.common import AudioMetaData
+from .common import AudioMetaData
 
 
 class Backend(ABC):

torchaudio/_backend/ffmpeg.py

@@ -5,10 +5,10 @@
 
 import torch
 import torchaudio
-from torchaudio.backend.common import AudioMetaData
 from torchaudio.io import StreamWriter
 
 from .backend import Backend
+from .common import AudioMetaData
 
 if torchaudio._extension._FFMPEG_EXT is not None:
     StreamReaderFileObj = torchaudio._extension._FFMPEG_EXT.StreamReaderFileObj

torchaudio/_backend/soundfile.py

@@ -3,10 +3,9 @@
 
 import torch
 
-from torchaudio.backend import soundfile_backend
-from torchaudio.backend.common import AudioMetaData
-
+from . import soundfile_backend
 from .backend import Backend
+from .common import AudioMetaData
 
 
 class SoundfileBackend(Backend):

torchaudio/_backend/sox.py

@@ -2,9 +2,9 @@
 from typing import BinaryIO, Optional, Tuple, Union
 
 import torch
-from torchaudio.backend.common import AudioMetaData
 
 from .backend import Backend
+from .common import AudioMetaData
 
 
 class SoXBackend(Backend):

torchaudio/_backend/utils.py

@@ -5,10 +5,11 @@
 import torch
 
 from torchaudio._extension import _FFMPEG_EXT, _SOX_INITIALIZED
-from torchaudio.backend import soundfile_backend
-from torchaudio.backend.common import AudioMetaData
+
+from . import soundfile_backend
 
 from .backend import Backend
+from .common import AudioMetaData
 from .ffmpeg import FFmpegBackend
 from .soundfile import SoundfileBackend
 from .sox import SoXBackend

torchaudio/backend/__init__.py

@@ -1,4 +1,42 @@
+# NOTE:
+# The entire `torchaudio.backend` module is deprecated.
+# New things should be added to `torchaudio._backend`.
+# Only things related to backward compatibility should be placed here.
+
 from .utils import _init_backend, get_audio_backend, list_audio_backends, set_audio_backend
 
 
 __all__ = ["_init_backend", "get_audio_backend", "list_audio_backends", "set_audio_backend"]
+
+
+def __getattr__(name: str):
+    import warnings
+
+    if name == "sox_io_backend":
+        warnings.warn(
+            "Torchaudio's I/O functions now support par-call bakcend dispatch. "
+            "Importing backend implementation directly is no longer guaranteed to work. "
+            "Please use `backend` keyword with load/save/info function, instead of "
+            "calling the udnerlying implementation directly.",
+            stacklevel=2,
+        )
+        from . import sox_io_backend
+
+        return sox_io_backend
+    if name == "soundfile_backend":
+        warnings.warn(
+            "Torchaudio's I/O functions now support par-call bakcend dispatch. "
+            "Importing backend implementation directly is no longer guaranteed to work. "
+            "Please use `backend` keyword with load/save/info functions, instead of "
+            "calling the udnerlying implementation directly.",
+            stacklevel=2,
+        )
+        from torchaudio._backend import soundfile_backend
+
+        return soundfile_backend
+
+    if name == "common":
+        from . import _common
+
+        return _common
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

torchaudio/backend/_common.py

@@ -0,0 +1,13 @@
+def __getattr__(name: str):
+    import warnings
+
+    if name == "AudioMetaData":
+        warnings.warn(
+            "`torchaudio.backend.common.AudioMetaData` has been moved to "
+            "`torchaudio.AudioMetaData`. Please update the import path.",
+            stacklevel=2,
+        )
+        from torchaudio._backend.common import AudioMetaData
+
+        return AudioMetaData
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

torchaudio/backend/sox_io_backend.py

@@ -3,8 +3,7 @@
 
 import torch
 import torchaudio
-
-from .common import AudioMetaData
+from torchaudio import AudioMetaData
 
 
 @torchaudio._extension.fail_if_no_sox

torchaudio/backend/utils.py

@@ -3,9 +3,10 @@
 from typing import List, Optional
 
 import torchaudio
+from torchaudio._backend import soundfile_backend
 from torchaudio._internal import module_utils as _mod_utils
 
-from . import no_backend, soundfile_backend, sox_io_backend
+from . import no_backend, sox_io_backend
 
 __all__ = [
     "list_audio_backends",