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

53 statements  

« prev     ^ index     » next       coverage.py v6.5.0, created at 2022-10-12 02:38 -0700

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}. "\ 

45 " This Gen2 code may be removed in any future daily or weekly release."\ 

46 " For a Gen3-based Getting Started Tutorial, please see" \ 

47 " https://pipelines.lsst.io/getting-started/index.html." 

48 

49_version_deprecated = "v22.0" 

50 

51 

52def deprecateGen2(component=None): 

53 """Issue deprecation warning for Butler. 

54 

55 Parameters 

56 ---------- 

57 component : `str`, optional 

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

59 if no other warnings have been issued. 

60 

61 Notes 

62 ----- 

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

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

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

66 be issued. 

67 """ 

68 global _issued 

69 

70 if always_warn: 

71 # Sidestep all the logic and always issue the warning 

72 pass 

73 elif always_warn is None and _issued: 

74 # We have already issued so return immediately 

75 return 

76 else: 

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

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

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

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

81 return 

82 

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

84 # and into user code. 

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

86 stack = traceback.extract_stack() 

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

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

89 stacklevel = i + 1 

90 break 

91 

92 label = "" 

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

94 label = f" ({component})" 

95 

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

97 _issued[component] = True 

98 

99 

100def _add_deprecation_docstring(wrapped): 

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

102 # Add the deprecation message to the docstring. 

103 # (logic taken from deprecated.sphinx) 

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

105 reason = '\n'.join( 

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

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

108 ).strip() 

109 

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

111 

112 if docstring: 

113 docstring += "\n\n" 

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

115 

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

117 # with the class directly. 

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

119 wrapped.__doc__ = docstring 

120 return wrapped 

121 

122 

123class Deprecator: 

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

125 

126 def __call__(self, wrapped): 

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

128 old_new1 = wrapped.__new__ 

129 

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

131 deprecateGen2(cls.__name__) 

132 if old_new1 is object.__new__: 

133 return old_new1(cls) 

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

135 

136 wrapped.__new__ = staticmethod(wrapped_cls) 

137 _add_deprecation_docstring(wrapped) 

138 

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

140 # so register an __init_subclass__ method to attach it. 

141 # We know that daf_persistence does not use __init_subclass_ 

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

143 def add_deprecation_docstring_to_subclass(cls, **kwargs): 

144 _add_deprecation_docstring(cls) 

145 

146 wrapped.__init_subclass__ = classmethod(add_deprecation_docstring_to_subclass) 

147 

148 return wrapped 

149 

150 

151def deprecate_class(cls): 

152 return Deprecator()(cls)