Move essential backend implementations to _backend (#3549)

Summary:
Move the actual I/O implementation to `_backend` submodule so that the existing `backend` submodule contains only what's related to legacy backend utilities.

Pull Request resolved: #3549

Reviewed By: huangruizhe

Differential Revision: D48253550

Pulled By: mthrok

fbshipit-source-id: c23f1664458c723f63e134c7974b3f7cf17a1e98

Author: mthrok

torchaudio/__init__.py

@@ -11,8 +11,7 @@
     transforms,
     utils,
 )
-from .backend.common import AudioMetaData
-
+from ._backend.common import AudioMetaData  # noqa
 
 try:
     from .version import __version__, git_version  # noqa: F401
@@ -34,6 +33,9 @@ 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",

torchaudio/_backend/__init__.py

@@ -3,11 +3,11 @@
 import torchaudio
 from torchaudio._internal.module_utils import deprecated
 
-from . import utils
-
 
 # TODO: Once legacy global backend is removed, move this to torchaudio.__init__
 def _init_backend():
+    from . import utils
+
     torchaudio.info = utils.get_info_func()
     torchaudio.load = utils.get_load_func()
     torchaudio.save = utils.get_save_func()
@@ -24,6 +24,8 @@ def list_audio_backends() -> List[str]:
         - Dispatcher mode: ``"ffmpeg"``, ``"sox"`` and ``"soundfile"``.
         - Legacy backend mode: ``"sox_io"``, ``"soundfile"``.
     """
+    from . import utils
+
     return list(utils.get_available_backends().keys())
 
 

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/common.py renamed to torchaudio/_backend/common.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/ffmpeg.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/soundfile.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/soundfile_backend.py renamed to torchaudio/_backend/soundfile_backend.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/sox.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):
+    if name == "common":
+        from . import _common
+
+        return _common
+
+    if name in ["no_backend", "sox_io_backend", "soundfile_backend"]:
+        import warnings
+
+        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,
+        )
+
+        if name == "sox_io_backend":
+            from . import _sox_io_backend
+
+            return _sox_io_backend
+        if name == "soundfile_backend":
+            from torchaudio._backend import soundfile_backend
+
+            return soundfile_backend
+
+        if name == "no_backend":
+            from . import _no_backend
+
+            return _no_backend
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

torchaudio/_backend/utils.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/__init__.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/_common.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 as no_backend, _sox_io_backend as sox_io_backend
 
 __all__ = [
     "list_audio_backends",
@@ -53,13 +54,18 @@ def set_audio_backend(backend: Optional[str]):
 
 
 def _init_backend():
+    warnings.warn(
+        "TorchAudio's global backend is now deprecated. "
+        "Please enable distpatcher by setting `TORCHAUDIO_USE_BACKEND_DISPATCHER=1`, "
+        "and specify backend when calling load/info/save function.",
+        stacklevel=3,
+    )
     backends = list_audio_backends()
     if "sox_io" in backends:
         set_audio_backend("sox_io")
     elif "soundfile" in backends:
         set_audio_backend("soundfile")
     else:
-        warnings.warn("No audio backend is available.")
         set_audio_backend(None)