Package logilab-common-0 ::
Package 36 ::
Package 1 ::
Module deprecation
|
|
1 """Deprecation utilities.
2
3 :copyright: 2006-2008 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
4 :contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
5 :license: General Public License version 2 - http://www.gnu.org/licenses
6 """
7 __docformat__ = "restructuredtext en"
8
9 import sys
10 from warnings import warn
11
12
14 """metaclass to print a warning on instantiation of a deprecated class"""
15
17 msg = getattr(cls, "__deprecation_warning__",
18 "%s is deprecated" % cls.__name__)
19 warn(msg, DeprecationWarning, stacklevel=2)
20 return type.__call__(cls, *args, **kwargs)
21
22
24 """automatically creates a class which fires a DeprecationWarning
25 when instantiated.
26
27 >>> Set = class_renamed('Set', set, 'Set is now replaced by set')
28 >>> s = Set()
29 sample.py:57: DeprecationWarning: Set is now replaced by set
30 s = Set()
31 >>>
32 """
33 clsdict = {}
34 if message is None:
35 message = '%s is deprecated' % old_name
36 clsdict['__deprecation_warning__'] = message
37 try:
38
39 return deprecated(old_name, (new_class,), clsdict)
40 except (NameError, TypeError):
41
42 class DeprecatedClass(new_class):
43 """FIXME: There might be a better way to handle old/new-style class
44 """
45 def __init__(self, *args, **kwargs):
46 warn(message, DeprecationWarning, stacklevel=2)
47 new_class.__init__(self, *args, **kwargs)
48 return DeprecatedClass
49
50
51 -def class_moved(new_class, old_name=None, message=None):
52 """nice wrapper around class_renamed when a class has been moved into
53 another module
54 """
55 if old_name is None:
56 old_name = new_class.__name__
57 if message is None:
58 message = 'class %s is now available as %s.%s' % (
59 old_name, new_class.__module__, new_class.__name__)
60 return class_renamed(old_name, new_class, message)
61
62
64 """Creates a function which fires a DeprecationWarning when used.
65
66 For example, if <bar> is deprecated in favour of <foo>:
67
68 >>> bar = deprecated_function(foo, 'bar is deprecated')
69 >>> bar()
70 sample.py:57: DeprecationWarning: bar is deprecated
71 bar()
72 >>>
73 """
74 if message is None:
75 message = "this function is deprecated, use %s instead" % (
76 new_func.func_name)
77 def deprecated(*args, **kwargs):
78 warn(message, DeprecationWarning, stacklevel=2)
79 return new_func(*args, **kwargs)
80 return deprecated
81
82
83 -def moved(modpath, objname):
84 """use to tell that a callable has been moved to a new module.
85
86 It returns a callable wrapper, so that when its called a warning is printed
87 telling where the object can be found, import is done (and not before) and
88 the actual object is called.
89
90 NOTE: the usage is somewhat limited on classes since it will fail if the
91 wrapper is use in a class ancestors list, use the `class_moved` function
92 instead (which has no lazy import feature though).
93 """
94 def callnew(*args, **kwargs):
95 from logilab.common.modutils import load_module_from_name
96 message = "object %s has been moved to module %s" % (objname, modpath)
97 warn(message, DeprecationWarning, stacklevel=2)
98 m = load_module_from_name(modpath)
99 return getattr(m, objname)(*args, **kwargs)
100 return callnew
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124 -def obsolete(reason="This function is obsolete"):
125 """this function is an alternative to `deprecated_function`
126 when there's no real replacement for the deprecated function
127 """
128 def newdecorator(func):
129 def wrapped(*args, **kwargs):
130 warn(reason, DeprecationWarning, stacklevel=2)
131 return func(*args, **kwargs)
132 return wrapped
133 return newdecorator
134