Back to index

salome-kernel  6.5.0
deprecation.py
Go to the documentation of this file.
00001 # -*- coding: utf-8 -*-
00002 #
00003 # Copyright (C) 2007-2012  CEA/DEN, EDF R&D, OPEN CASCADE
00004 #
00005 # This library is free software; you can redistribute it and/or
00006 # modify it under the terms of the GNU Lesser General Public
00007 # License as published by the Free Software Foundation; either
00008 # version 2.1 of the License.
00009 #
00010 # This library is distributed in the hope that it will be useful,
00011 # but WITHOUT ANY WARRANTY; without even the implied warranty of
00012 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013 # Lesser General Public License for more details.
00014 #
00015 # You should have received a copy of the GNU Lesser General Public
00016 # License along with this library; if not, write to the Free Software
00017 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
00018 #
00019 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
00020 #
00021 """
00022 This module provides several functions to indicate the deprecation of a
00023 module, a method or a function.
00024 
00025 Example::
00026 
00027     from salome.kernel.deprecation import deprecated
00028 
00029     @deprecated("Deprecated since version 6.3.0. Consider replacement with "
00030                 "newFunction()")
00031     def oldFunction():
00032       ...
00033 
00034 """
00035 
00036 import sys
00037 import warnings
00038 import inspect
00039 import os
00040 
00041 from salome.kernel import termcolor
00042 
00043 msg_seedoc = "See documentation for possible replacements."
00044 
00045 def __deprecated_with_msg(func, msg):
00046 
00047     def new_func(*args, **kwargs):
00048         if len(inspect.stack()) > 1:
00049             callingfunc = inspect.stack()[1][3]
00050         else:
00051             callingfunc = "CORBA middleware"
00052         warnings.warn(
00053             ("Call to deprecated function %(funcname)s of module " +
00054              "%(modname)s (called from %(callingfunc)s).\n  %(msg)s") % {
00055                 'funcname': func.__name__,
00056                 'modname': func.__module__,
00057                 'callingfunc': callingfunc,
00058                 'msg': msg,
00059             },
00060             category = DeprecationWarning,
00061             stacklevel = 2
00062         )
00063         return func(*args, **kwargs)
00064     return new_func
00065 
00066 def deprecated(msg = msg_seedoc):
00067     """
00068     This is a decorator which can be used to mark functions
00069     as deprecated. It will result in a warning being emitted
00070     when the function is used. The message in parameter will
00071     be displayed and should indicate how this function can be
00072     replaced. If the terminal can display colors, the warning
00073     messages will appear in blue.
00074     """
00075     def make_dep(f):
00076         if is_called_by_sphinx():
00077             return f
00078         else:
00079             g = __deprecated_with_msg(f, msg)
00080             g.__name__ = f.__name__
00081             g.__doc__ = f.__doc__
00082             g.__dict__.update(f.__dict__)
00083             return g
00084     return make_dep
00085 
00086 def deprecated_module(msg = msg_seedoc):
00087     """
00088     This function can be used to mark a module as deprecated.
00089     It must be called explicitly at the beginning of the deprecated
00090     module. It will result in a warning being emitted. The message
00091     in parameter will be displayed and should indicate how this
00092     module can be replaced. If the terminal can display colors,
00093     the warning messages will appear in blue.
00094     """
00095     if not is_called_by_sphinx():
00096         warnings.warn(
00097             "Importation of deprecated module %(modname)s.\n  %(msg)s" % {
00098                 'modname': inspect.getmodulename(inspect.stack()[1][1]),
00099                 'msg': msg,
00100             },
00101             category = DeprecationWarning,
00102             stacklevel = 5
00103         )
00104 
00105 def is_called_by_sphinx():
00106     """
00107     Determine if the calling code is ultimately called by sphinx to generate
00108     documentation. The result can be used to conditionally inhibit the
00109     decorators or some Salome-related imports that fail when called outside
00110     Salome.
00111     """
00112     calling_file = inspect.stack()[len(inspect.stack())-1][1]
00113     basename = os.path.basename(calling_file)
00114     return (basename == "sphinx-build")
00115 
00116 
00117 def __show_colored_warning(message, category, filename,
00118                            lineno, file = sys.stderr, line = None):
00119     str = warnings.formatwarning(message, category, filename, lineno, line)
00120     if category == DeprecationWarning and termcolor.canDisplayColor(file):
00121         file.write(termcolor.makeColoredMessage(str, termcolor.BLUE))
00122     else:
00123         file.write(str)
00124 
00125 # Enable warnings for deprecated functions and modules (in Python 2.7, they
00126 # are disabled by default)
00127 warnings.filterwarnings("always", "Call to *", DeprecationWarning)
00128 warnings.filterwarnings("always", "Importation of *", DeprecationWarning)
00129 warnings.showwarning = __show_colored_warning