lsst.daf.persistence 22.0.1-5-g6a31054+488b794621
deprecation.py
Go to the documentation of this file.
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
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
150 return Deprecator()(cls)
def deprecateGen2(component=None)
Definition: deprecation.py:50