JezK

Edit File: deprecations.py

# util/deprecations.py
# Copyright (C) 2005-2023 the SQLAlchemy authors and contributors
# <see AUTHORS file>
#
# This module is part of SQLAlchemy and is released under
# the MIT License: https://www.opensource.org/licenses/mit-license.php

"""Helpers related to deprecation of functions, methods, classes, other
functionality."""

import os
import re
import sys

from . import compat
from .langhelpers import _hash_limit_string
from .langhelpers import _warnings_warn
from .langhelpers import decorator
from .langhelpers import inject_docstring_text
from .langhelpers import inject_param_text
from .. import exc

SQLALCHEMY_WARN_20 = False

SILENCE_UBER_WARNING = False

if os.getenv("SQLALCHEMY_WARN_20", "false").lower() in ("true", "yes", "1"):
    SQLALCHEMY_WARN_20 = True

if compat.py2k:
    SILENCE_UBER_WARNING = True
elif os.getenv("SQLALCHEMY_SILENCE_UBER_WARNING", "false").lower() in (
    "true",
    "yes",
    "1",
):
    SILENCE_UBER_WARNING = True

def _warn_with_version(msg, version, type_, stacklevel, code=None):
    if (
        issubclass(type_, exc.Base20DeprecationWarning)
        and not SQLALCHEMY_WARN_20
    ):
        if not SILENCE_UBER_WARNING:
            _emit_uber_warning(type_, stacklevel)

return

warn = type_(msg, code=code)
    warn.deprecated_since = version

_warnings_warn(warn, stacklevel=stacklevel + 1)

def _emit_uber_warning(type_, stacklevel):
    global SILENCE_UBER_WARNING

if SILENCE_UBER_WARNING:
        return

SILENCE_UBER_WARNING = True

file_ = sys.stderr

# source: https://github.com/pytest-dev/pytest/blob/326ae0cd88f5e954c8effc2b0c986832e9caff11/src/_pytest/_io/terminalwriter.py#L35-L37  # noqa: E501
    use_color = (
        hasattr(file_, "isatty")
        and file_.isatty()
        and os.environ.get("TERM") != "dumb"
    )

msg = (
        "%(red)sDeprecated API features detected! "
        "These feature(s) are not compatible with SQLAlchemy 2.0. "
        "%(green)sTo prevent incompatible upgrades prior to updating "
        "applications, ensure requirements files are "
        'pinned to "sqlalchemy<2.0". '
        "%(cyan)sSet environment variable SQLALCHEMY_WARN_20=1 to show all "
        "deprecation warnings.  Set environment variable "
        "SQLALCHEMY_SILENCE_UBER_WARNING=1 to silence this message.%(nocolor)s"
    )

if use_color:
        msg = msg % {
            "red": "\x1b[31m",
            "cyan": "\x1b[36m",
            "green": "\x1b[32m",
            "magenta": "\x1b[35m",
            "nocolor": "\x1b[0m",
        }
    else:
        msg = msg % {
            "red": "",
            "cyan": "",
            "green": "",
            "magenta": "",
            "nocolor": "",
        }

# note this is a exc.Base20DeprecationWarning subclass, which
    # will implicitly add the link to the SQLAlchemy 2.0 page in the message
    warn = type_(msg)
    _warnings_warn(warn, stacklevel=stacklevel + 1)

def warn_deprecated(msg, version, stacklevel=3, code=None):
    _warn_with_version(
        msg, version, exc.SADeprecationWarning, stacklevel, code=code
    )

def warn_deprecated_limited(msg, args, version, stacklevel=3, code=None):
    """Issue a deprecation warning with a parameterized string,
    limiting the number of registrations.

"""
    if args:
        msg = _hash_limit_string(msg, 10, args)
    _warn_with_version(
        msg, version, exc.SADeprecationWarning, stacklevel, code=code
    )

def warn_deprecated_20(msg, stacklevel=3, code=None):

_warn_with_version(
        msg,
        exc.RemovedIn20Warning.deprecated_since,
        exc.RemovedIn20Warning,
        stacklevel,
        code=code,
    )

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),
            version,
            header,
        )

return decorate

def deprecated_20_cls(
    clsname, alternative=None, constructor="__init__", becomes_legacy=False
):
    message = (
        ".. deprecated:: 1.4 The %s class is considered legacy as of the "
        "1.x series of SQLAlchemy and %s in 2.0."
        % (
            clsname,
            "will be removed"
            if not becomes_legacy
            else "becomes a legacy construct",
        )
    )

if alternative:
        message += " " + alternative

if becomes_legacy:
        warning_cls = exc.LegacyAPIWarning
    else:
        warning_cls = exc.RemovedIn20Warning

def decorate(cls):
        return _decorate_cls_with_warning(
            cls,
            constructor,
            warning_cls,
            message,
            warning_cls.deprecated_since,
            message,
        )

return decorate

def deprecated(
    version,
    message=None,
    add_deprecation_to_docstring=True,
    warning=None,
    enable_warnings=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.

"""

# nothing is deprecated "since" 2.0 at this time.  All "removed in 2.0"
    # should emit the RemovedIn20Warning, but messaging should be expressed
    # in terms of "deprecated since 1.4".

if version == "2.0":
        if warning is None:
            warning = exc.RemovedIn20Warning
        version = "1.4"
    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"

if warning is None:
        warning = exc.SADeprecationWarning

if warning is not exc.RemovedIn20Warning:
        message += " (deprecated since: %s)" % version

def decorate(fn):
        return _decorate_with_warning(
            fn,
            warning,
            message % dict(func=fn.__name__),
            version,
            header,
            enable_warnings=enable_warnings,
        )

return decorate

def moved_20(message, **kw):
    return deprecated(
        "2.0", message=message, warning=exc.MovedIn20Warning, **kw
    )

def deprecated_20(api_name, alternative=None, becomes_legacy=False, **kw):
    type_reg = re.match("^:(attr|func|meth):", api_name)
    if type_reg:
        type_ = {"attr": "attribute", "func": "function", "meth": "method"}[
            type_reg.group(1)
        ]
    else:
        type_ = "construct"
    message = (
        "The %s %s is considered legacy as of the "
        "1.x series of SQLAlchemy and %s in 2.0."
        % (
            api_name,
            type_,
            "will be removed"
            if not becomes_legacy
            else "becomes a legacy construct",
        )
    )

if ":attr:" in api_name:
        attribute_ok = kw.pop("warn_on_attribute_access", False)
        if not attribute_ok:
            assert kw.get("enable_warnings") is False, (
                "attribute %s will emit a warning on read access.  "
                "If you *really* want this, "
                "add warn_on_attribute_access=True.  Otherwise please add "
                "enable_warnings=False." % api_name
            )

if alternative:
        message += " " + alternative

if becomes_legacy:
        warning_cls = exc.LegacyAPIWarning
    else:
        warning_cls = exc.RemovedIn20Warning

return deprecated("2.0", message=message, warning=warning_cls, **kw)

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 = {}
    versions = {}
    version_warnings = {}

for param, (version, message) in specs.items():
        versions[param] = version
        messages[param] = _sanitize_restructured_text(message)
        version_warnings[param] = (
            exc.RemovedIn20Warning
            if version == "2.0"
            else exc.SADeprecationWarning
        )

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)

check_any_kw = spec.varkw

@decorator
        def warned(fn, *args, **kwargs):
            for m in check_defaults:
                if (defaults[m] is None and kwargs[m] is not None) or (
                    defaults[m] is not None and kwargs[m] != defaults[m]
                ):
                    _warn_with_version(
                        messages[m],
                        versions[m],
                        version_warnings[m],
                        stacklevel=3,
                    )

if check_any_kw in messages and set(kwargs).difference(
                check_defaults
            ):

_warn_with_version(
                    messages[check_any_kw],
                    versions[check_any_kw],
                    version_warnings[check_any_kw],
                    stacklevel=3,
                )

for m in check_kw:
                if m in kwargs:
                    _warn_with_version(
                        messages[m],
                        versions[m],
                        version_warnings[m],
                        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"
                    % ("1.4" if version == "2.0" else version, (message or ""))
                    for param, (version, message) in specs.items()
                },
            )
        decorated = warned(fn)
        decorated.__doc__ = doc
        return decorated

return decorate

def _sanitize_restructured_text(text):
    def repl(m):
        type_, name = m.group(1, 2)
        if type_ in ("func", "meth"):
            name += "()"
        return name

text = re.sub(r":ref:`(.+) <.*>`", lambda m: '"%s"' % m.group(1), text)
    return re.sub(r"\:(\w+)\:`~?(?:_\w+)?\.?(.+?)`", repl, text)

def _decorate_cls_with_warning(
    cls, constructor, wtype, message, version, docstring_header=None
):
    doc = cls.__doc__ is not None and cls.__doc__ or ""
    if docstring_header is not None:

if constructor is not None:
            docstring_header %= dict(func=constructor)

if issubclass(wtype, exc.Base20DeprecationWarning):
            docstring_header += (
                " (Background on SQLAlchemy 2.0 at: "
                ":ref:`migration_20_toplevel`)"
            )
        doc = inject_docstring_text(doc, docstring_header, 1)

if type(cls) is type:
            clsdict = dict(cls.__dict__)
            clsdict["__doc__"] = doc
            clsdict.pop("__dict__", None)
            clsdict.pop("__weakref__", None)
            cls = type(cls.__name__, cls.__bases__, clsdict)
            if constructor is not None:
                constructor_fn = clsdict[constructor]

else:
            cls.__doc__ = doc
            if constructor is not None:
                constructor_fn = getattr(cls, constructor)

if constructor is not None:
            setattr(
                cls,
                constructor,
                _decorate_with_warning(
                    constructor_fn, wtype, message, version, None
                ),
            )
    return cls

def _decorate_with_warning(
    func, wtype, message, version, docstring_header=None, enable_warnings=True
):
    """Wrap a function with a warnings.warn and augmented docstring."""

message = _sanitize_restructured_text(message)

if issubclass(wtype, exc.Base20DeprecationWarning):
        doc_only = (
            " (Background on SQLAlchemy 2.0 at: "
            ":ref:`migration_20_toplevel`)"
        )
    else:
        doc_only = ""

@decorator
    def warned(fn, *args, **kwargs):
        skip_warning = not enable_warnings or kwargs.pop(
            "_sa_skip_warning", False
        )
        if not skip_warning:
            _warn_with_version(message, version, 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__)

docstring_header += doc_only

doc = inject_docstring_text(doc, docstring_header, 1)

decorated = warned(func)
    decorated.__doc__ = doc
    decorated._sa_warn = lambda: _warn_with_version(
        message, version, wtype, stacklevel=3
    )
    return decorated

JezK

Edit File: deprecations.py

FAIRNETZT