1 # -*- coding: utf-8 -*-
3 # Copyright (C) 2007-2009 EDF R&D
5 # This file is part of PAL_SRC.
7 # PAL_SRC is free software; you can redistribute it and/or modify
8 # it under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 2 of the License, or
10 # (at your option) any later version.
12 # PAL_SRC is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with PAL_SRC; if not, write to the Free Software
19 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 This module provides several functions to indicate the deprecation of a
23 module, a method or a function.
31 from salome.kernel import termcolor
33 msg_seedoc = "See documentation for possible replacements."
35 def __deprecated_with_msg(func, msg):
37 def new_func(*args, **kwargs):
38 if len(inspect.stack()) > 1:
39 callingfunc = inspect.stack()[1][3]
41 callingfunc = "CORBA middleware"
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,
50 category = DeprecationWarning,
53 return func(*args, **kwargs)
56 def deprecated(msg = msg_seedoc):
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.
66 if is_called_by_sphinx():
69 g = __deprecated_with_msg(f, msg)
70 g.__name__ = f.__name__
72 g.__dict__.update(f.__dict__)
76 def deprecated_module(msg = msg_seedoc):
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.
85 if not is_called_by_sphinx():
87 "Importation of deprecated module %(modname)s.\n %(msg)s" % {
88 'modname': inspect.getmodulename(inspect.stack()[1][1]),
91 category = DeprecationWarning,
95 def is_called_by_sphinx():
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
102 calling_file = inspect.stack()[len(inspect.stack())-1][1]
103 basename = os.path.basename(calling_file)
104 return (basename == "sphinx-build")
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))
115 warnings.showwarning = __show_colored_warning