src/KERNEL_PY/kernel/deprecation.py

   1 # -*- coding: utf-8 -*-
   2 #
   3 # Copyright (C) 2007-2014  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, or (at your option) any later version.
   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 ## \defgroup deprecation deprecation
  23 #  \{
  24 #  \details
  25 #  This module provides several functions to indicate the deprecation of a
  26 #  module, a method or a function.
  27 #  \code
  28 #  from salome.kernel.deprecation import deprecated
  29 #  deprecated("Deprecated since version 6.3.0. Consider replacement with
  30 #              newFunction()")
  31 #  def oldFunction():
  32 #  ...
  33 #  \endcode
  34 #  \}
  35
  36 """
  37 This module provides several functions to indicate the deprecation of a
  38 module, a method or a function.
  39
  40 Example::
  41
  42     from salome.kernel.deprecation import deprecated
  43
  44     @deprecated("Deprecated since version 6.3.0. Consider replacement with "
  45                 "newFunction()")
  46     def oldFunction():
  47       ...
  48
  49 """
  50
  51 import sys
  52 import warnings
  53 import inspect
  54 import os
  55
  56 from salome.kernel import termcolor
  57
  58 msg_seedoc = "See documentation for possible replacements."
  59
  60 def __deprecated_with_msg(func, msg):
  61
  62     def new_func(*args, **kwargs):
  63         if len(inspect.stack()) > 1:
  64             callingfunc = inspect.stack()[1][3]
  65         else:
  66             callingfunc = "CORBA middleware"
  67         warnings.warn(
  68             ("Call to deprecated function %(funcname)s of module " +
  69              "%(modname)s (called from %(callingfunc)s).\n  %(msg)s") % {
  70                 'funcname': func.__name__,
  71                 'modname': func.__module__,
  72                 'callingfunc': callingfunc,
  73                 'msg': msg,
  74             },
  75             category = DeprecationWarning,
  76             stacklevel = 2
  77         )
  78         return func(*args, **kwargs)
  79     return new_func
  80
  81 ## This is a decorator which can be used to mark functions
  82 #  as deprecated. It will result in a warning being emitted
  83 #  when the function is used. The message in parameter will
  84 #  be displayed and should indicate how this function can be
  85 #  replaced. If the terminal can display colors, the warning
  86 #  messages will appear in blue.
  87 #  \ingroup deprecation
  88 def deprecated(msg = msg_seedoc):
  89     """
  90     This is a decorator which can be used to mark functions
  91     as deprecated. It will result in a warning being emitted
  92     when the function is used. The message in parameter will
  93     be displayed and should indicate how this function can be
  94     replaced. If the terminal can display colors, the warning
  95     messages will appear in blue.
  96     """
  97     def make_dep(f):
  98         if is_called_by_sphinx():
  99             return f
 100         else:
 101             g = __deprecated_with_msg(f, msg)
 102             g.__name__ = f.__name__
 103             g.__doc__ = f.__doc__
 104             g.__dict__.update(f.__dict__)
 105             return g
 106     return make_dep
 107
 108 ## This function can be used to mark a module as deprecated.
 109 #  It must be called explicitly at the beginning of the deprecated
 110 #  module. It will result in a warning being emitted. The message
 111 #  in parameter will be displayed and should indicate how this
 112 #  module can be replaced. If the terminal can display colors,
 113 #  the warning messages will appear in blue.
 114 #  \ingroup deprecation
 115 def deprecated_module(msg = msg_seedoc):
 116     """
 117     This function can be used to mark a module as deprecated.
 118     It must be called explicitly at the beginning of the deprecated
 119     module. It will result in a warning being emitted. The message
 120     in parameter will be displayed and should indicate how this
 121     module can be replaced. If the terminal can display colors,
 122     the warning messages will appear in blue.
 123     """
 124     if not is_called_by_sphinx():
 125         warnings.warn(
 126             "Importation of deprecated module %(modname)s.\n  %(msg)s" % {
 127                 'modname': inspect.getmodulename(inspect.stack()[1][1]),
 128                 'msg': msg,
 129             },
 130             category = DeprecationWarning,
 131             stacklevel = 5
 132         )
 133
 134 ## Determine if the calling code is ultimately called by sphinx to generate
 135 #  documentation. The result can be used to conditionally inhibit the
 136 #  decorators or some Salome-related imports that fail when called outside
 137 #  Salome.
 138 #  \ingroup deprecation
 139 def is_called_by_sphinx():
 140     """
 141     Determine if the calling code is ultimately called by sphinx to generate
 142     documentation. The result can be used to conditionally inhibit the
 143     decorators or some Salome-related imports that fail when called outside
 144     Salome.
 145     """
 146     calling_file = inspect.stack()[len(inspect.stack())-1][1]
 147     basename = os.path.basename(calling_file)
 148     return (basename == "sphinx-build")
 149
 150
 151 def __show_colored_warning(message, category, filename,
 152                            lineno, file = None, line = None):
 153     if file is None:
 154         file = sys.stderr
 155     str = warnings.formatwarning(message, category, filename, lineno, line)
 156     if category == DeprecationWarning and termcolor.canDisplayColor(file):
 157         file.write(termcolor.makeColoredMessage(str, termcolor.BLUE))
 158     else:
 159         file.write(str)
 160
 161 # Enable warnings for deprecated functions and modules (in Python 2.7, they
 162 # are disabled by default)
 163 warnings.filterwarnings("always", "Call to *", DeprecationWarning)
 164 warnings.filterwarnings("always", "Importation of *", DeprecationWarning)
 165 warnings.showwarning = __show_colored_warning