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}")