Coverage for python/lsst/daf/persistence/deprecation.py: 50%

Shortcuts 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

52 statements  

1# 

2# LSST Data Management System 

3# Copyright 2016 LSST Corporation. 

4# 

5# This product includes software developed by the 

6# LSST Project (http://www.lsst.org/). 

7# 

8# This program is free software: you can redistribute it and/or modify 

9# it under the terms of the GNU General Public License as published by 

10# the Free Software Foundation, either version 3 of the License, or 

11# (at your option) any later version. 

12# 

13# This program is distributed in the hope that it will be useful, 

14# but WITHOUT ANY WARRANTY; without even the implied warranty of 

15# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 

16# GNU General Public License for more details. 

17# 

18# You should have received a copy of the LSST License Statement and 

19# the GNU General Public License along with this program. If not, 

20# see <http://www.lsstcorp.org/LegalNotices/>. 

21# 

22 

23__all__ = ("deprecateGen2", "always_warn", "deprecate_class") 

24 

25import textwrap 

26import traceback 

27import warnings 

28 

29always_warn = False 

30"""Control how often a warning is issued. 

31 

32Options are: 

33 

34* `True`: Always issue a warning. 

35* `False`: Only issue a warning the first time a component is encountered. 

36* `None`: Only issue a warning once regardless of component. 

37""" 

38 

39# Cache recording which components have issued previously 

40_issued = {} 

41 

42# This is the warning message to issue. There is a "label" placeholder 

43# that should be inserted on format. 

44_warning_msg = "Gen2 Butler has been deprecated{label}. It will be removed sometime after v23.0 but no" \ 

45 " earlier than the end of 2021." 

46 

47_version_deprecated = "v22.0" 

48 

49 

50def deprecateGen2(component=None): 

51 """Issue deprecation warning for Butler. 

52 

53 Parameters 

54 ---------- 

55 component : `str`, optional 

56 Name of component to warn about. If `None` will only issue a warning 

57 if no other warnings have been issued. 

58 

59 Notes 

60 ----- 

61 The package variable `lsst.daf.persistence.deprecation.always_warn` can be 

62 set to `True` to always issue a warning rather than only issuing 

63 on first encounter. If set to `None` only a single message will ever 

64 be issued. 

65 """ 

66 global _issued 

67 

68 if always_warn: 

69 # Sidestep all the logic and always issue the warning 

70 pass 

71 elif always_warn is None and _issued: 

72 # We have already issued so return immediately 

73 return 

74 else: 

75 # Either we've already issued a warning for this component 

76 # or it's a null component and we've issued something already. 

77 # In this situation we do not want to warn again. 

78 if _issued.get(component, False) or (component is None and _issued): 

79 return 

80 

81 # Calculate a stacklevel that pops the warning out of daf_persistence 

82 # and into user code. 

83 stacklevel = 3 # Default to the caller's caller 

84 stack = traceback.extract_stack() 

85 for i, s in enumerate(reversed(stack)): 

86 if not ("python/lsst/daf/persistence" in s.filename or "python/lsst/obs/base" in s.filename): 

87 stacklevel = i + 1 

88 break 

89 

90 label = "" 

91 if component is not None and always_warn is not None: 

92 label = f" ({component})" 

93 

94 warnings.warn(_warning_msg.format(label=label), category=FutureWarning, stacklevel=stacklevel) 

95 _issued[component] = True 

96 

97 

98def _add_deprecation_docstring(wrapped): 

99 """Add the deprecation docstring to the supplied class""" 

100 # Add the deprecation message to the docstring. 

101 # (logic taken from deprecated.sphinx) 

102 reason = textwrap.dedent(_warning_msg.format(label="")).strip() 

103 reason = '\n'.join( 

104 textwrap.fill(line, width=70, initial_indent=' ', 

105 subsequent_indent=' ') for line in reason.splitlines() 

106 ).strip() 

107 

108 docstring = textwrap.dedent(wrapped.__doc__ or "") 

109 

110 if docstring: 

111 docstring += "\n\n" 

112 docstring += f".. deprecated:: {_version_deprecated}\n" 

113 

114 # No need for a component label since this message will be associated 

115 # with the class directly. 

116 docstring += " {reason}\n".format(reason=reason) 

117 wrapped.__doc__ = docstring 

118 return wrapped 

119 

120 

121class Deprecator: 

122 """Class for deprecation decorator to use.""" 

123 

124 def __call__(self, wrapped): 

125 """Intercept the call to ``__new__`` and issue the warning first.""" 

126 old_new1 = wrapped.__new__ 

127 

128 def wrapped_cls(cls, *args, **kwargs): 

129 deprecateGen2(cls.__name__) 

130 if old_new1 is object.__new__: 

131 return old_new1(cls) 

132 return old_new1(cls, *args, **kwargs) 

133 

134 wrapped.__new__ = staticmethod(wrapped_cls) 

135 _add_deprecation_docstring(wrapped) 

136 

137 # Want to add the deprecation message to subclasses as well 

138 # so register an __init_subclass__ method to attach it. 

139 # We know that daf_persistence does not use __init_subclass_ 

140 # so do not need to get any cleverer here. 

141 def add_deprecation_docstring_to_subclass(cls, **kwargs): 

142 _add_deprecation_docstring(cls) 

143 

144 wrapped.__init_subclass__ = classmethod(add_deprecation_docstring_to_subclass) 

145 

146 return wrapped 

147 

148 

149def deprecate_class(cls): 

150 return Deprecator()(cls)