Package common :: Module deprecation
[frames] | no frames]

Source Code for Module common.deprecation

  1  # copyright 2003-2011 LOGILAB S.A. (Paris, FRANCE), all rights reserved. 
  2  # contact http://www.logilab.fr/ -- mailto:contact@logilab.fr 
  3  # 
  4  # This file is part of logilab-common. 
  5  # 
  6  # logilab-common is free software: you can redistribute it and/or modify it under 
  7  # the terms of the GNU Lesser General Public License as published by the Free 
  8  # Software Foundation, either version 2.1 of the License, or (at your option) any 
  9  # later version. 
 10  # 
 11  # logilab-common is distributed in the hope that it will be useful, but WITHOUT 
 12  # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
 13  # FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more 
 14  # details. 
 15  # 
 16  # You should have received a copy of the GNU Lesser General Public License along 
 17  # with logilab-common.  If not, see <http://www.gnu.org/licenses/>. 
 18  """Deprecation utilities.""" 
 19   
 20  __docformat__ = "restructuredtext en" 
 21   
 22  import sys 
 23  from warnings import warn 
 24   
25 -class class_deprecated(type):
26 """metaclass to print a warning on instantiation of a deprecated class""" 27
28 - def __call__(cls, *args, **kwargs):
29 msg = getattr(cls, "__deprecation_warning__", 30 "%(cls)s is deprecated") % {'cls': cls.__name__} 31 warn(msg, DeprecationWarning, stacklevel=2) 32 return type.__call__(cls, *args, **kwargs)
33 34
35 -def class_renamed(old_name, new_class, message=None):
36 """automatically creates a class which fires a DeprecationWarning 37 when instantiated. 38 39 >>> Set = class_renamed('Set', set, 'Set is now replaced by set') 40 >>> s = Set() 41 sample.py:57: DeprecationWarning: Set is now replaced by set 42 s = Set() 43 >>> 44 """ 45 clsdict = {} 46 if message is None: 47 message = '%s is deprecated, use %s' % (old_name, new_class.__name__) 48 clsdict['__deprecation_warning__'] = message 49 try: 50 # new-style class 51 return class_deprecated(old_name, (new_class,), clsdict) 52 except (NameError, TypeError): 53 # old-style class 54 class DeprecatedClass(new_class): 55 """FIXME: There might be a better way to handle old/new-style class 56 """ 57 def __init__(self, *args, **kwargs): 58 warn(message, DeprecationWarning, stacklevel=2) 59 new_class.__init__(self, *args, **kwargs)
60 return DeprecatedClass 61 62
63 -def class_moved(new_class, old_name=None, message=None):
64 """nice wrapper around class_renamed when a class has been moved into 65 another module 66 """ 67 if old_name is None: 68 old_name = new_class.__name__ 69 if message is None: 70 message = 'class %s is now available as %s.%s' % ( 71 old_name, new_class.__module__, new_class.__name__) 72 return class_renamed(old_name, new_class, message)
73
74 -def deprecated(reason=None, stacklevel=2, name=None, doc=None):
75 """Decorator that raises a DeprecationWarning to print a message 76 when the decorated function is called. 77 """ 78 def deprecated_decorator(func): 79 message = reason or 'The function "%s" is deprecated' 80 if '%s' in message: 81 message = message % func.__name__ 82 def wrapped(*args, **kwargs): 83 warn(message, DeprecationWarning, stacklevel=stacklevel) 84 return func(*args, **kwargs)
85 try: 86 wrapped.__name__ = name or func.__name__ 87 except TypeError: # readonly attribute in 2.3 88 pass 89 wrapped.__doc__ = doc or func.__doc__ 90 return wrapped 91 return deprecated_decorator 92
93 -def moved(modpath, objname):
94 """use to tell that a callable has been moved to a new module. 95 96 It returns a callable wrapper, so that when its called a warning is printed 97 telling where the object can be found, import is done (and not before) and 98 the actual object is called. 99 100 NOTE: the usage is somewhat limited on classes since it will fail if the 101 wrapper is use in a class ancestors list, use the `class_moved` function 102 instead (which has no lazy import feature though). 103 """ 104 def callnew(*args, **kwargs): 105 from logilab.common.modutils import load_module_from_name 106 message = "object %s has been moved to module %s" % (objname, modpath) 107 warn(message, DeprecationWarning, stacklevel=2) 108 m = load_module_from_name(modpath) 109 return getattr(m, objname)(*args, **kwargs)
110 return callnew 111 112 113
114 -class DeprecationWrapper(object):
115 """proxy to print a warning on access to any attribute of the wrapped object 116 """
117 - def __init__(self, proxied, msg=None):
118 self._proxied = proxied 119 self._msg = msg
120
121 - def __getattr__(self, attr):
122 warn(self._msg, DeprecationWarning, stacklevel=2) 123 return getattr(self._proxied, attr)
124
125 - def __setattr__(self, attr, value):
126 if attr in ('_proxied', '_msg'): 127 self.__dict__[attr] = value 128 else: 129 warn(self._msg, DeprecationWarning, stacklevel=2) 130 setattr(self._proxied, attr, value)
131