Coverage for python/lsst/daf/persistence/deprecation.py: 51%
53 statements
« prev ^ index » next coverage.py v6.5.0, created at 2023-01-05 10:53 +0000
« prev ^ index » next coverage.py v6.5.0, created at 2023-01-05 10:53 +0000
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#
23__all__ = ("deprecateGen2", "always_warn", "deprecate_class")
25import textwrap
26import traceback
27import warnings
29always_warn = False
30"""Control how often a warning is issued.
32Options are:
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"""
39# Cache recording which components have issued previously
40_issued = {}
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."
49_version_deprecated = "v22.0"
52def deprecateGen2(component=None):
53 """Issue deprecation warning for Butler.
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.
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
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
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
92 label = ""
93 if component is not None and always_warn is not None:
94 label = f" ({component})"
96 warnings.warn(_warning_msg.format(label=label), category=FutureWarning, stacklevel=stacklevel)
97 _issued[component] = True
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()
110 docstring = textwrap.dedent(wrapped.__doc__ or "")
112 if docstring:
113 docstring += "\n\n"
114 docstring += f".. deprecated:: {_version_deprecated}\n"
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
123class Deprecator:
124 """Class for deprecation decorator to use."""
126 def __call__(self, wrapped):
127 """Intercept the call to ``__new__`` and issue the warning first."""
128 old_new1 = wrapped.__new__
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)
136 wrapped.__new__ = staticmethod(wrapped_cls)
137 _add_deprecation_docstring(wrapped)
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)
146 wrapped.__init_subclass__ = classmethod(add_deprecation_docstring_to_subclass)
148 return wrapped
151def deprecate_class(cls):
152 return Deprecator()(cls)