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}. "\
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"
53 """Issue deprecation warning for Butler.
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.
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
73 elif always_warn
is None and _issued:
80 if _issued.get(component,
False)
or (component
is None and _issued):
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):
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"""
104 reason = textwrap.dedent(_warning_msg.format(label=
"")).strip()
106 textwrap.fill(line, width=70, initial_indent=
' ',
107 subsequent_indent=
' ')
for line
in reason.splitlines()
110 docstring = textwrap.dedent(wrapped.__doc__
or "")
114 docstring += f
".. deprecated:: {_version_deprecated}\n"
118 docstring +=
" {reason}\n".format(reason=reason)
119 wrapped.__doc__ = docstring
124 """Class for deprecation decorator to use."""
127 """Intercept the call to ``__new__`` and issue the warning first."""
128 old_new1 = wrapped.__new__
130 def wrapped_cls(cls, *args, **kwargs):
132 if old_new1
is object.__new__:
134 return old_new1(cls, *args, **kwargs)
136 wrapped.__new__ = staticmethod(wrapped_cls)
137 _add_deprecation_docstring(wrapped)
143 def add_deprecation_docstring_to_subclass(cls, **kwargs):
144 _add_deprecation_docstring(cls)
146 wrapped.__init_subclass__ = classmethod(add_deprecation_docstring_to_subclass)
def __call__(self, wrapped)
def deprecateGen2(component=None)