From 91f376692d472a5bf0c4b4033816250ec1ce3ab6 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Fri, 26 Jun 2020 16:15:19 -0400 Subject: Add future=True to create_engine/Session; unify select() Several weeks of using the future_select() construct has led to the proposal there be just one select() construct again which features the new join() method, and otherwise accepts both the 1.x and 2.x argument styles. This would make migration simpler and reduce confusion. However, confusion may be increased by the fact that select().join() is different Current thinking is we may be better off with a few hard behavioral changes to old and relatively unknown APIs rather than trying to play both sides within two extremely similar but subtly different APIs. At the moment, the .join() thing seems to be the only behavioral change that occurs without the user taking any explicit steps. Session.execute() will still behave the old way as we are adding a future flag. This change also adds the "future" flag to Session() and session.execute(), so that interpretation of the incoming statement, as well as that the new style result is returned, does not occur for existing applications unless they add the use of this flag. The change in general is moving the "removed in 2.0" system further along where we want the test suite to fully pass even if the SQLALCHEMY_WARN_20 flag is set. Get many tests to pass when SQLALCHEMY_WARN_20 is set; this should be ongoing after this patch merges. Improve the RemovedIn20 warning; these are all deprecated "since" 1.4, so ensure that's what the messages read. Make sure the inforamtion link is on all warnings. Add deprecation warnings for parameters present and add warnings to all FromClause.select() types of methods. Fixes: #5379 Fixes: #5284 Change-Id: I765a0b912b3dcd0e995426427d8bb7997cbffd51 References: #5159 --- lib/sqlalchemy/util/__init__.py | 4 +-- lib/sqlalchemy/util/deprecations.py | 49 ++++++++++++++++++++++++++++++++----- lib/sqlalchemy/util/langhelpers.py | 4 +-- 3 files changed, 46 insertions(+), 11 deletions(-) (limited to 'lib/sqlalchemy/util') diff --git a/lib/sqlalchemy/util/__init__.py b/lib/sqlalchemy/util/__init__.py index fb90975a1..b2407ea18 100644 --- a/lib/sqlalchemy/util/__init__.py +++ b/lib/sqlalchemy/util/__init__.py @@ -92,6 +92,7 @@ from .deprecations import deprecated_20_cls # noqa from .deprecations import deprecated_cls # noqa from .deprecations import deprecated_params # noqa from .deprecations import inject_docstring_text # noqa +from .deprecations import SQLALCHEMY_WARN_20 # noqa from .deprecations import warn_deprecated # noqa from .deprecations import warn_deprecated_20 # noqa from .langhelpers import add_parameter_text # noqa @@ -149,6 +150,3 @@ from .langhelpers import warn # noqa from .langhelpers import warn_exception # noqa from .langhelpers import warn_limited # noqa from .langhelpers import wrap_callable # noqa - - -SQLALCHEMY_WARN_20 = False diff --git a/lib/sqlalchemy/util/deprecations.py b/lib/sqlalchemy/util/deprecations.py index e0669c4e8..0a79344c5 100644 --- a/lib/sqlalchemy/util/deprecations.py +++ b/lib/sqlalchemy/util/deprecations.py @@ -8,6 +8,7 @@ """Helpers related to deprecation of functions, methods, classes, other functionality.""" +import os import re import warnings @@ -19,7 +20,19 @@ from .langhelpers import inject_param_text from .. import exc +SQLALCHEMY_WARN_20 = False + +if os.getenv("SQLALCHEMY_WARN_20", "false").lower() in ("true", "yes", "1"): + SQLALCHEMY_WARN_20 = True + + def _warn_with_version(msg, version, type_, stacklevel): + if type_ is exc.RemovedIn20Warning and not SQLALCHEMY_WARN_20: + return + + if type_ is exc.RemovedIn20Warning: + msg += " (Background on SQLAlchemy 2.0 at: http://sqlalche.me/e/b8d9)" + warn = type_(msg) warn.deprecated_since = version @@ -41,7 +54,6 @@ def warn_deprecated_limited(msg, args, version, stacklevel=3): def warn_deprecated_20(msg, stacklevel=3): - msg += " (Background on SQLAlchemy 2.0 at: http://sqlalche.me/e/b8d9)" _warn_with_version( msg, @@ -69,7 +81,7 @@ def deprecated_cls(version, message, constructor="__init__"): def deprecated_20_cls(clsname, alternative=None, constructor="__init__"): message = ( - ".. deprecated:: 2.0 The %s class is considered legacy as of the " + ".. deprecated:: 1.4 The %s class is considered legacy as of the " "1.x series of SQLAlchemy and will be removed in 2.0." % clsname ) @@ -108,8 +120,16 @@ def deprecated( """ + # 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 "")) + header = ".. deprecated:: %s %s" % (version, (message or ""),) else: header = None @@ -119,7 +139,8 @@ def deprecated( if warning is None: warning = exc.SADeprecationWarning - message += " (deprecated since: %s)" % version + if warning is not exc.RemovedIn20Warning: + message += " (deprecated since: %s)" % version def decorate(fn): return _decorate_with_warning( @@ -162,6 +183,7 @@ def deprecated_params(**specs): messages = {} versions = {} version_warnings = {} + for param, (version, message) in specs.items(): versions[param] = version messages[param] = _sanitize_restructured_text(message) @@ -173,6 +195,7 @@ def deprecated_params(**specs): def decorate(fn): spec = compat.inspect_getfullargspec(fn) + if spec.defaults is not None: defaults = dict( zip( @@ -186,6 +209,8 @@ def deprecated_params(**specs): check_defaults = () check_kw = set(messages) + check_any_kw = spec.varkw + @decorator def warned(fn, *args, **kwargs): for m in check_defaults: @@ -198,6 +223,18 @@ def deprecated_params(**specs): 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( @@ -206,7 +243,6 @@ def deprecated_params(**specs): version_warnings[m], stacklevel=3, ) - return fn(*args, **kwargs) doc = fn.__doc__ is not None and fn.__doc__ or "" @@ -214,7 +250,8 @@ def deprecated_params(**specs): doc = inject_param_text( doc, { - param: ".. deprecated:: %s %s" % (version, (message or "")) + param: ".. deprecated:: %s %s" + % ("1.4" if version == "2.0" else version, (message or "")) for param, (version, message) in specs.items() }, ) diff --git a/lib/sqlalchemy/util/langhelpers.py b/lib/sqlalchemy/util/langhelpers.py index 57d3be83b..28b7aa4cc 100644 --- a/lib/sqlalchemy/util/langhelpers.py +++ b/lib/sqlalchemy/util/langhelpers.py @@ -1701,9 +1701,9 @@ def inject_param_text(doctext, inject_params): while doclines: line = doclines.pop(0) if to_inject is None: - m = re.match(r"(\s+):param (?:\\\*\*?)?(.+?):", line) + m = re.match(r"(\s+):param (.+?):", line) if m: - param = m.group(2) + param = m.group(2).lstrip("*") if param in inject_params: # default indent to that of :param: plus one indent = " " * len(m.group(1)) + " " -- cgit v1.2.1