|
| 1 | +""" Class for recording and reporting deprecations |
| 2 | +""" |
| 3 | + |
| 4 | +import functools |
| 5 | +import warnings |
| 6 | +import re |
| 7 | + |
| 8 | +_LEADING_WHITE = re.compile('^(\s*)') |
| 9 | + |
| 10 | + |
| 11 | +class ExpiredDeprecationError(RuntimeError): |
| 12 | + """ Error for expired deprecation |
| 13 | +
|
| 14 | + Error raised when a called function or method has passed out of its |
| 15 | + deprecation period. |
| 16 | + """ |
| 17 | + pass |
| 18 | + |
| 19 | + |
| 20 | +def _ensure_cr(text): |
| 21 | + """ Remove trailing whitespace and add carriage return |
| 22 | +
|
| 23 | + Ensures that `text` always ends with a carriage return |
| 24 | + """ |
| 25 | + return text.rstrip() + '\n' |
| 26 | + |
| 27 | + |
| 28 | +def _add_dep_doc(old_doc, dep_doc): |
| 29 | + """ Add deprecation message `dep_doc` to docstring in `old_doc` |
| 30 | +
|
| 31 | + Parameters |
| 32 | + ---------- |
| 33 | + old_doc : str |
| 34 | + Docstring from some object. |
| 35 | + dep_doc : str |
| 36 | + Deprecation warning to add to top of docstring, after initial line. |
| 37 | +
|
| 38 | + Returns |
| 39 | + ------- |
| 40 | + new_doc : str |
| 41 | + `old_doc` with `dep_doc` inserted after any first lines of docstring. |
| 42 | + """ |
| 43 | + dep_doc = _ensure_cr(dep_doc) |
| 44 | + if not old_doc: |
| 45 | + return dep_doc |
| 46 | + old_doc = _ensure_cr(old_doc) |
| 47 | + old_lines = old_doc.splitlines() |
| 48 | + new_lines = [] |
| 49 | + for line_no, line in enumerate(old_lines): |
| 50 | + if line.strip(): |
| 51 | + new_lines.append(line) |
| 52 | + else: |
| 53 | + break |
| 54 | + next_line = line_no + 1 |
| 55 | + if next_line >= len(old_lines): |
| 56 | + # nothing following first paragraph, just append message |
| 57 | + return old_doc + '\n' + dep_doc |
| 58 | + indent = _LEADING_WHITE.match(old_lines[next_line]).group() |
| 59 | + dep_lines = [indent + L for L in [''] + dep_doc.splitlines() + ['']] |
| 60 | + return '\n'.join(new_lines + dep_lines + old_lines[next_line:]) + '\n' |
| 61 | + |
| 62 | + |
| 63 | +class Deprecator(object): |
| 64 | + """ Class to make decorator marking function or method as deprecated |
| 65 | +
|
| 66 | + The decorated function / method will: |
| 67 | +
|
| 68 | + * Raise the given `warning_class` warning when the function / method gets |
| 69 | + called, up to (and including) version `until` (if specified); |
| 70 | + * Raise the given `error_class` error when the function / method gets |
| 71 | + called, when the package version is greater than version `until` (if |
| 72 | + specified). |
| 73 | +
|
| 74 | + Parameters |
| 75 | + ---------- |
| 76 | + version_comparator : callable |
| 77 | + Callable accepting string as argument, and return 1 if string |
| 78 | + represents a higher version than encoded in the `version_comparator`, 0 |
| 79 | + if the version is equal, and -1 if the version is lower. For example, |
| 80 | + the `version_comparator` may compare the input version string to the |
| 81 | + current package version string. |
| 82 | + warn_class : class, optional |
| 83 | + Class of warning to generate for deprecation. |
| 84 | + error_class : class, optional |
| 85 | + Class of error to generate when `version_comparator` returns 1 for a |
| 86 | + given argument of ``until`` in the ``__call__`` method (see below). |
| 87 | + """ |
| 88 | + |
| 89 | + def __init__(self, |
| 90 | + version_comparator, |
| 91 | + warn_class=DeprecationWarning, |
| 92 | + error_class=ExpiredDeprecationError): |
| 93 | + self.version_comparator = version_comparator |
| 94 | + self.warn_class = warn_class |
| 95 | + self.error_class = error_class |
| 96 | + |
| 97 | + def is_bad_version(self, version_str): |
| 98 | + """ Return True if `version_str` is too high |
| 99 | +
|
| 100 | + Tests `version_str` with ``self.version_comparator`` |
| 101 | +
|
| 102 | + Parameters |
| 103 | + ---------- |
| 104 | + version_str : str |
| 105 | + String giving version to test |
| 106 | +
|
| 107 | + Returns |
| 108 | + ------- |
| 109 | + is_bad : bool |
| 110 | + True if `version_str` is for version below that expected by |
| 111 | + ``self.version_comparator``, False otherwise. |
| 112 | + """ |
| 113 | + return self.version_comparator(version_str) == -1 |
| 114 | + |
| 115 | + def __call__(self, message, since='', until='', |
| 116 | + warn_class=None, error_class=None): |
| 117 | + """ Return decorator function function for deprecation warning / error |
| 118 | +
|
| 119 | + Parameters |
| 120 | + ---------- |
| 121 | + message : str |
| 122 | + Message explaining deprecation, giving possible alternatives. |
| 123 | + since : str, optional |
| 124 | + Released version at which object was first deprecated. |
| 125 | + until : str, optional |
| 126 | + Last released version at which this function will still raise a |
| 127 | + deprecation warning. Versions higher than this will raise an |
| 128 | + error. |
| 129 | + warn_class : None or class, optional |
| 130 | + Class of warning to generate for deprecation (overrides instance |
| 131 | + default). |
| 132 | + error_class : None or class, optional |
| 133 | + Class of error to generate when `version_comparator` returns 1 for a |
| 134 | + given argument of ``until`` (overrides class default). |
| 135 | +
|
| 136 | + Returns |
| 137 | + ------- |
| 138 | + deprecator : func |
| 139 | + Function returning a decorator. |
| 140 | + """ |
| 141 | + warn_class = warn_class if warn_class else self.warn_class |
| 142 | + error_class = error_class if error_class else self.error_class |
| 143 | + messages = [message] |
| 144 | + if (since, until) != ('', ''): |
| 145 | + messages.append('') |
| 146 | + if since: |
| 147 | + messages.append('* deprecated from version: ' + since) |
| 148 | + if until: |
| 149 | + messages.append('* {} {} as of version: {}'.format( |
| 150 | + "Raises" if self.is_bad_version(until) else "Will raise", |
| 151 | + error_class, |
| 152 | + until)) |
| 153 | + message = '\n'.join(messages) |
| 154 | + |
| 155 | + def deprecator(func): |
| 156 | + |
| 157 | + @functools.wraps(func) |
| 158 | + def deprecated_func(*args, **kwargs): |
| 159 | + if until and self.is_bad_version(until): |
| 160 | + raise error_class(message) |
| 161 | + warnings.warn(message, warn_class, stacklevel=2) |
| 162 | + return func(*args, **kwargs) |
| 163 | + |
| 164 | + deprecated_func.__doc__ = _add_dep_doc(deprecated_func.__doc__, |
| 165 | + message) |
| 166 | + return deprecated_func |
| 167 | + |
| 168 | + return deprecator |
0 commit comments