]> SALOME platform Git repositories - modules/kernel.git/blob - src/KERNEL_PY/kernel/deprecation.py
Salome HOME
Merge changes from 'master' branch.
[modules/kernel.git] / src / KERNEL_PY / kernel / deprecation.py
1 # -*- coding: utf-8 -*-
2 #
3 # Copyright (C) 2007-2016  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