Coverage for matplotlib\cbook\deprecation.py: 0%

# Coverage for matplotlib\cbook\deprecation.py : 0%

## 61 statements 0 run 61 missing 0 excluded

Hot-keys on this page

r m x p toggle line displays

j k next/prev highlighted chunk

0 (zero) top of page

1 (one) first highlighted chunk

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 | import functools import textwrap import warnings class MatplotlibDeprecationWarning(UserWarning): """ A class for issuing deprecation warnings for Matplotlib users. In light of the fact that Python builtin DeprecationWarnings are ignored by default as of Python 2.7 (see link below), this class was put in to allow for the signaling of deprecation, but via UserWarnings which are not ignored by default. https://docs.python.org/dev/whatsnew/2.7.html#the-future-for-python-2-x """ pass mplDeprecation = MatplotlibDeprecationWarning def _generate_deprecation_message(since, message='', name='', alternative='', pending=False, obj_type='attribute', addendum=''): if not message: if pending: message = ( 'The %(name)s %(obj_type)s will be deprecated in a ' 'future version.') else: message = ( 'The %(name)s %(obj_type)s was deprecated in version ' '%(since)s.') altmessage = '' if alternative: altmessage = ' Use %s instead.' % alternative message = ((message % { 'func': name, 'name': name, 'alternative': alternative, 'obj_type': obj_type, 'since': since}) + altmessage) if addendum: message += addendum return message def warn_deprecated( since, message='', name='', alternative='', pending=False, obj_type='attribute', addendum=''): """ Used to display deprecation warning in a standard way. Parameters ---------- since : str The release at which this API became deprecated. message : str, optional Override the default deprecation message. The format specifier `%(name)s` may be used for the name of the function, and `%(alternative)s` may be used in the deprecation message to insert the name of an alternative to the deprecated function. `%(obj_type)s` may be used to insert a friendly name for the type of object being deprecated. name : str, optional The name of the deprecated object. alternative : str, optional An alternative function that the user may use in place of the deprecated function. The deprecation warning will tell the user about this alternative if provided. pending : bool, optional If True, uses a PendingDeprecationWarning instead of a DeprecationWarning. obj_type : str, optional The object type being deprecated. addendum : str, optional Additional text appended directly to the final message. Examples -------- Basic example:: # To warn of the deprecation of "matplotlib.name_of_module" warn_deprecated('1.4.0', name='matplotlib.name_of_module', obj_type='module') """ message = _generate_deprecation_message( since, message, name, alternative, pending, obj_type) warnings.warn(message, mplDeprecation, stacklevel=1) def deprecated(since, message='', name='', alternative='', pending=False, obj_type=None, addendum=''): """ Decorator to mark a function or a class as deprecated. Parameters ---------- since : str The release at which this API became deprecated. This is required. message : str, optional Override the default deprecation message. The format specifier `%(name)s` may be used for the name of the object, and `%(alternative)s` may be used in the deprecation message to insert the name of an alternative to the deprecated object. `%(obj_type)s` may be used to insert a friendly name for the type of object being deprecated. name : str, optional The name of the deprecated object; if not provided the name is automatically determined from the passed in object, though this is useful in the case of renamed functions, where the new function is just assigned to the name of the deprecated function. For example:: def new_function(): ... oldFunction = new_function alternative : str, optional An alternative object that the user may use in place of the deprecated object. The deprecation warning will tell the user about this alternative if provided. pending : bool, optional If True, uses a PendingDeprecationWarning instead of a DeprecationWarning. addendum : str, optional Additional text appended directly to the final message. Examples -------- Basic example:: @deprecated('1.4.0') def the_function_to_deprecate(): pass """ def deprecate(obj, message=message, name=name, alternative=alternative, pending=pending, addendum=addendum): if not name: name = obj.__name__ if isinstance(obj, type): obj_type = "class" old_doc = obj.__doc__ func = obj.__init__ def finalize(wrapper, new_doc): try: obj.__doc__ = new_doc except (AttributeError, TypeError): # cls.__doc__ is not writeable on Py2. # TypeError occurs on PyPy pass obj.__init__ = wrapper return obj else: obj_type = "function" if isinstance(obj, classmethod): func = obj.__func__ old_doc = func.__doc__ def finalize(wrapper, new_doc): wrapper = functools.wraps(func)(wrapper) wrapper.__doc__ = new_doc return classmethod(wrapper) else: func = obj old_doc = func.__doc__ def finalize(wrapper, new_doc): wrapper = functools.wraps(func)(wrapper) wrapper.__doc__ = new_doc return wrapper message = _generate_deprecation_message( since, message, name, alternative, pending, obj_type, addendum) def wrapper(*args, **kwargs): warnings.warn(message, mplDeprecation, stacklevel=2) return func(*args, **kwargs) old_doc = textwrap.dedent(old_doc or '').strip('\n') message = message.strip() new_doc = (('\n.. deprecated:: %(since)s' '\n %(message)s\n\n' % {'since': since, 'message': message}) + old_doc) if not old_doc: # This is to prevent a spurious 'unexected unindent' warning from # docutils when the original docstring was blank. new_doc += r'\ ' return finalize(wrapper, new_doc) return deprecate