deprecated.py

# Allen Institute Software License - This software license is the 2-clause BSD
# license plus a third clause that prohibits redistribution for commercial
# purposes without further permission.
#
# Copyright 2017. Allen Institute. All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# 1. Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
#
# 2. Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
#
# 3. Redistributions for commercial purposes are not permitted without the
# Allen Institute's written permission.
# For purposes of this license, commercial purposes is the incorporation of the
# Allen Institute's software into anything for which you will charge fees or
# other compensation. Contact terms@alleninstitute.org for commercial licensing
# opportunities.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
#
import copy
import warnings
import functools
from numpy import VisibleDeprecationWarning

    
def deprecated(message=None):

    if message is None:
        message = '' 
    
    def output_decorator(fn):
        
        @functools.wraps(fn)
        def wrapper(*args, **kwargs):
        
            warnings.warn("Function {0} is deprecated. {1}".format(
                          fn.__name__, message), 
                          category=VisibleDeprecationWarning, stacklevel=2)
            
            return fn(*args, **kwargs)
            
        return wrapper
        
    return output_decorator
    
    
def class_deprecated(message=None):

    if message is None:
        message = ''
        
    def output_class_decorator(cls):
        
        fn_copy = copy.deepcopy(cls.__init__)
        
        @functools.wraps(cls.__init__)
        def wrapper(*args, **kwargs):
            warnings.warn("Class {0} is deprecated. {1}".format(
                          cls.__name__, message), 
                          category=VisibleDeprecationWarning, stacklevel=2)
            fn_copy(*args, **kwargs)
                          
        cls.__init__ = wrapper
        return cls
        
    return output_class_decorator


def legacy(message=None):

    if message is None:
        message = '' 
    
    def output_decorator(fn):
        
        @functools.wraps(fn)
        def wrapper(*args, **kwargs):
        
            warnings.warn("Function {0} is provided for backward-compatibilty with a legacy API, and may be removed in the future. {1}".format(
                          fn.__name__, message), 
                          category=VisibleDeprecationWarning, stacklevel=2)
            
            return fn(*args, **kwargs)
            
        return wrapper
        
    return output_decorator