Add deprecation warning to initialize/shutdown_sox (#709)

torchaudio/__init__.py

@@ -2,6 +2,7 @@
 from typing import Any, Callable, Optional, Tuple, Union
 
 from torch import Tensor
+from torchaudio._internal import module_utils as _mod_utils
 from torchaudio import (
     compliance,
     datasets,
@@ -24,8 +25,8 @@
     EncodingInfo,
 )
 from torchaudio.sox_effects import (
-    init_sox_effects as initialize_sox,
-    shutdown_sox_effects as shutdown_sox,
+    init_sox_effects as _init_sox_effects,
+    shutdown_sox_effects as _shutdown_sox_effects,
 )
 
 try:
@@ -34,6 +35,30 @@
     pass
 
 
+@_mod_utils.deprecated(
+    "Please remove the function call to initialize_sox. "
+    "Resource initialization is now automatically handled.")
+def initialize_sox() -> int:
+    """Initialize sox effects.
+
+    This function is deprecated. See ``torchaudio.sox_effects.init_sox_effects``
+    """
+    _init_sox_effects()
+
+
+@_mod_utils.deprecated(
+    "Please remove the function call to torchaudio.shutdown_sox. "
+    "Resource clean up is now automatically handled. "
+    "In the unlikely event that you need to manually shutdown sox, "
+    "please use torchaudio.sox_effects.shutdown_sox_effects.")
+def shutdown_sox():
+    """Shutdown sox effects.
+
+    This function is deprecated. See ``torchaudio.sox_effects.shutdown_sox_effects``
+    """
+    _shutdown_sox_effects()
+
+
 def load(filepath: Union[str, Path],
          out: Optional[Tensor] = None,
          normalization: Union[bool, float, Callable] = True,

torchaudio/_internal/module_utils.py

@@ -1,4 +1,6 @@
+import warnings
 import importlib.util
+from typing import Optional
 from functools import wraps
 
 
@@ -33,3 +35,22 @@ def wrapped(*args, **kwargs):
                 raise RuntimeError(f'{func.__module__}.{func.__name__} requires {req}')
             return wrapped
     return decorator
+
+
+def deprecated(direction: str, version: Optional[str] = None):
+    """Decorator to add deprecation message
+
+    Args:
+        direction: Migration steps to be given to users.
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapped(*args, **kwargs):
+            message = (
+                f'{func.__module__}.{func.__name__} has been deprecated '
+                f'and will be removed from {"future" if version is None else version} release.'
+                f'{direction}')
+            warnings.warn(message, stacklevel=2)
+            return func(*args, **kwargs)
+        return wrapped
+    return decorator

torchaudio/sox_effects/sox_effects.py

@@ -26,12 +26,15 @@
 
 @_mod_utils.requires_module('torchaudio._torchaudio')
 def init_sox_effects() -> int:
-    """Initialize sox for use with effects chains.
+    """Initialize resources required to use ``SoxEffectsChain``
 
-    You only need to call this function once to use SoX effects chains multiple times.
-    It is safe to call this function multiple times as long as ``shutdown_sox`` is not yet called.
-    Once ``shutdown_sox`` is called, you can no longer use SoX effects and calling this function
-    results in `RuntimeError`.
+    You do not need to call this function manually. It is called automatically.
+
+    Once initialized, you do not need to call this function again across the multiple call of
+    ``SoxEffectsChain.sox_build_flow_effects``, though it is safe to do so as long as
+    ``shutdown_sox_effects`` is not called yet.
+    Once ``shutdown_sox_effects`` is called, you can no longer use SoX effects and calling
+    this function results in `RuntimeError`.
 
     Note:
         This function is not required for simple loading.
@@ -54,12 +57,14 @@ def init_sox_effects() -> int:
 
 @_mod_utils.requires_module("torchaudio._torchaudio")
 def shutdown_sox_effects() -> int:
-    """Showdown sox for effects chain.
+    """Clean up resources required to use ``SoxEffectsChain``
 
-    You do not need to call this function as it will be called automatically
-    at the end of program execution, if ``initialize_sox`` was called.
+    You do not need to call this function manually. It is called automatically.
 
     It is safe to call this function multiple times.
+    Once ``shutdown_sox_effects`` is called, you can no longer use SoX effects and calling
+    this function results in `RuntimeError`.
+
 
     Returns:
         int: Code corresponding to sox_error_t enum. See