# util/deprecations.py # Copyright (C) 2005-2021 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php """Helpers related to deprecation of functions, methods, classes, other functionality.""" import re import warnings from . import compat from .langhelpers import _hash_limit_string from .langhelpers import decorator from .langhelpers import inject_docstring_text from .langhelpers import inject_param_text from .. import exc def warn_deprecated(msg, stacklevel=3): warnings.warn(msg, exc.SADeprecationWarning, stacklevel=stacklevel) def warn_deprecated_limited(msg, args, stacklevel=3): """Issue a deprecation warning with a parameterized string, limiting the number of registrations. """ if args: msg = _hash_limit_string(msg, 10, args) warnings.warn(msg, exc.SADeprecationWarning, stacklevel) def warn_pending_deprecation(msg, stacklevel=3): warnings.warn(msg, exc.SAPendingDeprecationWarning, stacklevel=stacklevel) def deprecated_cls(version, message, constructor="__init__"): header = ".. deprecated:: %s %s" % (version, (message or "")) def decorate(cls): return _decorate_cls_with_warning( cls, constructor, exc.SADeprecationWarning, message % dict(func=constructor), header, ) return decorate def deprecated(version, message=None, add_deprecation_to_docstring=True): """Decorates a function and issues a deprecation warning on use. :param version: Issue version in the warning. :param message: If provided, issue message in the warning. A sensible default is used if not provided. :param add_deprecation_to_docstring: Default True. If False, the wrapped function's __doc__ is left as-is. If True, the 'message' is prepended to the docs if provided, or sensible default if message is omitted. """ if add_deprecation_to_docstring: header = ".. deprecated:: %s %s" % (version, (message or "")) else: header = None if message is None: message = "Call to deprecated function %(func)s" def decorate(fn): return _decorate_with_warning( fn, exc.SADeprecationWarning, message % dict(func=fn.__name__), header, ) return decorate def deprecated_params(**specs): """Decorates a function to warn on use of certain parameters. e.g. :: @deprecated_params( weak_identity_map=( "0.7", "the :paramref:`.Session.weak_identity_map parameter " "is deprecated." ) ) """ messages = {} for param, (version, message) in specs.items(): messages[param] = _sanitize_restructured_text(message) def decorate(fn): spec = compat.inspect_getfullargspec(fn) if spec.defaults is not None: defaults = dict( zip( spec.args[(len(spec.args) - len(spec.defaults)) :], spec.defaults, ) ) check_defaults = set(defaults).intersection(messages) check_kw = set(messages).difference(defaults) else: check_defaults = () check_kw = set(messages) @decorator def warned(fn, *args, **kwargs): for m in check_defaults: if kwargs[m] != defaults[m]: warnings.warn( messages[m], exc.SADeprecationWarning, stacklevel=3 ) for m in check_kw: if m in kwargs: warnings.warn( messages[m], exc.SADeprecationWarning, stacklevel=3 ) return fn(*args, **kwargs) doc = fn.__doc__ is not None and fn.__doc__ or "" if doc: doc = inject_param_text( doc, { param: ".. deprecated:: %s %s" % (version, (message or "")) for param, (version, message) in specs.items() }, ) decorated = warned(fn) decorated.__doc__ = doc return decorated return decorate def pending_deprecation( version, message=None, add_deprecation_to_docstring=True ): """Decorates a function and issues a pending deprecation warning on use. :param version: An approximate future version at which point the pending deprecation will become deprecated. Not used in messaging. :param message: If provided, issue message in the warning. A sensible default is used if not provided. :param add_deprecation_to_docstring: Default True. If False, the wrapped function's __doc__ is left as-is. If True, the 'message' is prepended to the docs if provided, or sensible default if message is omitted. """ if add_deprecation_to_docstring: header = ".. deprecated:: %s (pending) %s" % (version, (message or "")) else: header = None if message is None: message = "Call to deprecated function %(func)s" def decorate(fn): return _decorate_with_warning( fn, exc.SAPendingDeprecationWarning, message % dict(func=fn.__name__), header, ) return decorate def deprecated_option_value(parameter_value, default_value, warning_text): if parameter_value is None: return default_value else: warn_deprecated(warning_text) return parameter_value def _sanitize_restructured_text(text): def repl(m): type_, name = m.group(1, 2) if type_ in ("func", "meth"): name += "()" return name return re.sub(r"\:(\w+)\:`~?(?:_\w+)?\.?(.+?)`", repl, text) def _decorate_cls_with_warning( cls, constructor, wtype, message, docstring_header=None ): doc = cls.__doc__ is not None and cls.__doc__ or "" if docstring_header is not None: docstring_header %= dict(func=constructor) doc = inject_docstring_text(doc, docstring_header, 1) if type(cls) is type: clsdict = dict(cls.__dict__) clsdict["__doc__"] = doc cls = type(cls.__name__, cls.__bases__, clsdict) constructor_fn = clsdict[constructor] else: cls.__doc__ = doc constructor_fn = getattr(cls, constructor) setattr( cls, constructor, _decorate_with_warning(constructor_fn, wtype, message, None), ) return cls def _decorate_with_warning(func, wtype, message, docstring_header=None): """Wrap a function with a warnings.warn and augmented docstring.""" message = _sanitize_restructured_text(message) @decorator def warned(fn, *args, **kwargs): warnings.warn(message, wtype, stacklevel=3) return fn(*args, **kwargs) doc = func.__doc__ is not None and func.__doc__ or "" if docstring_header is not None: docstring_header %= dict(func=func.__name__) doc = inject_docstring_text(doc, docstring_header, 1) decorated = warned(func) decorated.__doc__ = doc decorated._sa_warn = lambda: warnings.warn(message, wtype, stacklevel=3) return decorated