src/KERNEL_PY/kernel/deprecation.py

   1 # -*- coding: utf-8 -*-
   2 #
   3 # Copyright (C) 2007-2011  CEA/DEN, EDF R&D, OPEN CASCADE
   4 #
   5 # This library is free software; you can redistribute it and/or
   6 # modify it under the terms of the GNU Lesser General Public
   7 # License as published by the Free Software Foundation; either
   8 # version 2.1 of the License.
   9 #
  10 # This library is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 # Lesser General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU Lesser General Public
  16 # License along with this library; if not, write to the Free Software
  17 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  18 #
  19 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  20 #
  21 """
  22 This module provides several functions to indicate the deprecation of a
  23 module, a method or a function.
  24 """
  25
  26 import sys
  27 import warnings
  28 import inspect
  29 import os
  30
  31 from salome.kernel import termcolor
  32
  33 msg_seedoc = "See documentation for possible replacements."
  34
  35 def __deprecated_with_msg(func, msg):
  36
  37     def new_func(*args, **kwargs):
  38         if len(inspect.stack()) > 1:
  39             callingfunc = inspect.stack()[1][3]
  40         else:
  41             callingfunc = "CORBA middleware"
  42         warnings.warn(
  43             ("Call to deprecated function %(funcname)s of module " +
  44              "%(modname)s (called from %(callingfunc)s).\n  %(msg)s") % {
  45                 'funcname': func.__name__,
  46                 'modname': func.__module__,
  47                 'callingfunc': callingfunc,
  48                 'msg': msg,
  49             },
  50             category = DeprecationWarning,
  51             stacklevel = 2
  52         )
  53         return func(*args, **kwargs)
  54     return new_func
  55
  56 def deprecated(msg = msg_seedoc):
  57     """
  58     This is a decorator which can be used to mark functions
  59     as deprecated. It will result in a warning being emitted
  60     when the function is used. The message in parameter will
  61     be displayed and should indicate how this function can be
  62     replaced. If the terminal can display colors, the warning
  63     messages will appear in blue.
  64     """
  65     def make_dep(f):
  66         if is_called_by_sphinx():
  67             return f
  68         else:
  69             g = __deprecated_with_msg(f, msg)
  70             g.__name__ = f.__name__
  71             g.__doc__ = f.__doc__
  72             g.__dict__.update(f.__dict__)
  73             return g
  74     return make_dep
  75
  76 def deprecated_module(msg = msg_seedoc):
  77     """
  78     This function can be used to mark a module as deprecated.
  79     It must be called explicitly at the beginning of the deprecated
  80     module. It will result in a warning being emitted. The message
  81     in parameter will be displayed and should indicate how this
  82     module can be replaced. If the terminal can display colors,
  83     the warning messages will appear in blue.
  84     """
  85     if not is_called_by_sphinx():
  86         warnings.warn(
  87             "Importation of deprecated module %(modname)s.\n  %(msg)s" % {
  88                 'modname': inspect.getmodulename(inspect.stack()[1][1]),
  89                 'msg': msg,
  90             },
  91             category = DeprecationWarning,
  92             stacklevel = 5
  93         )
  94
  95 def is_called_by_sphinx():
  96     """
  97     Determine if the calling code is ultimately called by sphinx to generate
  98     documentation. The result can be used to conditionally inhibit the
  99     decorators or some Salome-related imports that fail when called outside
 100     Salome.
 101     """
 102     calling_file = inspect.stack()[len(inspect.stack())-1][1]
 103     basename = os.path.basename(calling_file)
 104     return (basename == "sphinx-build")
 105
 106
 107 def __show_colored_warning(message, category, filename,
 108                            lineno, file = sys.stderr, line = None):
 109     str = warnings.formatwarning(message, category, filename, lineno, line)
 110     if category == DeprecationWarning and termcolor.canDisplayColor(file):
 111         file.write(termcolor.makeColoredMessage(str, termcolor.BLUE))
 112     else:
 113         file.write(str)
 114
 115 warnings.showwarning = __show_colored_warning