23 __all__ = (
"deprecateGen2",
"always_warn",
"deprecate_class")
30 """Control how often a warning is issued.
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.
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."
47 _version_deprecated =
"v22.0"
51 """Issue deprecation warning for Butler.
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.
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
71 elif always_warn
is None and _issued:
78 if _issued.get(component,
False)
or (component
is None and _issued):
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):
91 if component
is not None and always_warn
is not None:
92 label = f
" ({component})"
94 warnings.warn(_warning_msg.format(label=label), category=FutureWarning, stacklevel=stacklevel)
95 _issued[component] =
True
98 def _add_deprecation_docstring(wrapped):
99 """Add the deprecation docstring to the supplied class"""
102 reason = textwrap.dedent(_warning_msg.format(label=
"")).strip()
104 textwrap.fill(line, width=70, initial_indent=
' ',
105 subsequent_indent=
' ')
for line
in reason.splitlines()
108 docstring = textwrap.dedent(wrapped.__doc__
or "")
112 docstring += f
".. deprecated:: {_version_deprecated}\n"
116 docstring +=
" {reason}\n".format(reason=reason)
117 wrapped.__doc__ = docstring
122 """Class for deprecation decorator to use."""
125 """Intercept the call to ``__new__`` and issue the warning first."""
126 old_new1 = wrapped.__new__
128 def wrapped_cls(cls, *args, **kwargs):
130 if old_new1
is object.__new__:
132 return old_new1(cls, *args, **kwargs)
134 wrapped.__new__ = staticmethod(wrapped_cls)
135 _add_deprecation_docstring(wrapped)
141 def add_deprecation_docstring_to_subclass(cls, **kwargs):
142 _add_deprecation_docstring(cls)
144 wrapped.__init_subclass__ = classmethod(add_deprecation_docstring_to_subclass)
def __call__(self, wrapped)
def deprecateGen2(component=None)