From b82258078fdd4cffce77d8ebd00965405bb89046 Mon Sep 17 00:00:00 2001 From: moto <855818+mthrok@users.noreply.github.com> Date: Thu, 11 Jun 2020 19:46:33 -0400 Subject: [PATCH] Add deprecation warning to initialize/shutdown_sox (#709) --- torchaudio/__init__.py | 29 +++++++++++++++++++++++++-- torchaudio/_internal/module_utils.py | 21 +++++++++++++++++++ torchaudio/sox_effects/sox_effects.py | 21 +++++++++++-------- 3 files changed, 61 insertions(+), 10 deletions(-) diff --git a/torchaudio/__init__.py b/torchaudio/__init__.py index ca0c100dee..68b82e07e1 100644 --- a/torchaudio/__init__.py +++ b/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, diff --git a/torchaudio/_internal/module_utils.py b/torchaudio/_internal/module_utils.py index 5ddc82d769..575a76c1ed 100644 --- a/torchaudio/_internal/module_utils.py +++ b/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 diff --git a/torchaudio/sox_effects/sox_effects.py b/torchaudio/sox_effects/sox_effects.py index 33393b8c0c..6a6b5be0a5 100644 --- a/torchaudio/sox_effects/sox_effects.py +++ b/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