SA20: Restore backward-compatibility with SQLAlchemy 1.3

Note that this is on a best-effort basis. SQLAlchemy 2.0 will be
mostly compatible with most SQLAlchemy 1.3 code which is not using any
of the deprecated functionalities, modulo a few aspects.

> It is possible to have code that is compatible with 2.0 and 1.3 at the
> same time, you would just need to ensure you use the subset of
> features and APIs that are common to both.

This patch adds a small compatibility layer, which activates on SA13
only, and monkey-patches two spots where anomalies have been spotted.

src/crate/client/sqlalchemy/__init__.py

@@ -19,7 +19,13 @@
 # with Crate these terms will supersede the license and you may use the
 # software solely pursuant to the terms of the relevant commercial agreement.
 
+from .compat.api13 import monkeypatch_add_exec_driver_sql
 from .dialect import CrateDialect
+from .sa_version import SA_1_4, SA_VERSION
+
+# SQLAlchemy 1.3 does not have the `exec_driver_sql` method.
+if SA_VERSION < SA_1_4:
+    monkeypatch_add_exec_driver_sql()
 
 __all__ = [
     CrateDialect,

src/crate/client/sqlalchemy/compat/api13.py

@@ -0,0 +1,133 @@
+# -*- coding: utf-8; -*-
+#
+# Licensed to CRATE Technology GmbH ("Crate") under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  Crate licenses
+# this file to you under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.  You may
+# obtain a copy of the License at
+#
+#   https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# However, if you have executed another commercial license agreement
+# with Crate these terms will supersede the license and you may use the
+# software solely pursuant to the terms of the relevant commercial agreement.
+
+"""
+Compatibility module for running a subset of SQLAlchemy 2.0 programs on
+SQLAlchemy 1.3. By using monkey-patching, it can do two things:
+
+1. Add the `exec_driver_sql` method to SA's `Connection` and `Engine`.
+2. Amend the `sql.select` function to accept the calling semantics of
+   the modern variant.
+
+Reason: `exec_driver_sql` gets used within the CrateDB dialect already,
+and the new calling semantics of `sql.select` already get used within
+many of the test cases already. Please note that the patch for
+`sql.select` is only applied when running the test suite.
+"""
+
+import collections.abc as collections_abc
+
+from sqlalchemy import exc
+from sqlalchemy.sql import Select
+from sqlalchemy.sql import select as original_select
+from sqlalchemy.util import immutabledict
+
+
+# `_distill_params_20` copied from SA14's `sqlalchemy.engine.{base,util}`.
+_no_tuple = ()
+_no_kw = immutabledict()
+
+
+def _distill_params_20(params):
+    if params is None:
+        return _no_tuple, _no_kw
+    elif isinstance(params, list):
+        # collections_abc.MutableSequence): # avoid abc.__instancecheck__
+        if params and not isinstance(params[0], (collections_abc.Mapping, tuple)):
+            raise exc.ArgumentError(
+                "List argument must consist only of tuples or dictionaries"
+            )
+
+        return (params,), _no_kw
+    elif isinstance(
+        params,
+        (tuple, dict, immutabledict),
+        # only do abc.__instancecheck__ for Mapping after we've checked
+        # for plain dictionaries and would otherwise raise
+    ) or isinstance(params, collections_abc.Mapping):
+        return (params,), _no_kw
+    else:
+        raise exc.ArgumentError("mapping or sequence expected for parameters")
+
+
+def exec_driver_sql(self, statement, parameters=None, execution_options=None):
+    """
+    Adapter for `exec_driver_sql`, which is available since SA14, for SA13.
+    """
+    if execution_options is not None:
+        raise ValueError(
+            "SA13 backward-compatibility: "
+            "`exec_driver_sql` does not support `execution_options`"
+        )
+    args_10style, kwargs_10style = _distill_params_20(parameters)
+    return self.execute(statement, *args_10style, **kwargs_10style)
+
+
+def monkeypatch_add_exec_driver_sql():
+    """
+    Transparently add SA14's `exec_driver_sql()` method to SA13.
+
+    AttributeError: 'Connection' object has no attribute 'exec_driver_sql'
+    AttributeError: 'Engine' object has no attribute 'exec_driver_sql'
+    """
+    from sqlalchemy.engine.base import Connection, Engine
+
+    # Add `exec_driver_sql` method to SA's `Connection` and `Engine` classes.
+    Connection.exec_driver_sql = exec_driver_sql
+    Engine.exec_driver_sql = exec_driver_sql
+
+
+def select_sa14(*columns, **kw) -> Select:
+    """
+    Adapt SA14/SA20's calling semantics of `sql.select()` to SA13.
+
+    With SA20, `select()` no longer accepts varied constructor arguments, only
+    the "generative" style of `select()` will be supported. The list of columns
+    / tables to select from should be passed positionally.
+
+    Derived from https://github.com/sqlalchemy/alembic/blob/b1fad6b6/alembic/util/sqla_compat.py#L557-L558
+
+    sqlalchemy.exc.ArgumentError: columns argument to select() must be a Python list or other iterable
+    """
+    if isinstance(columns, tuple) and isinstance(columns[0], list):
+        if "whereclause" in kw:
+            raise ValueError(
+                "SA13 backward-compatibility: "
+                "`whereclause` is both in kwargs and columns tuple"
+            )
+        columns, whereclause = columns
+        kw["whereclause"] = whereclause
+    return original_select(columns, **kw)
+
+
+def monkeypatch_amend_select_sa14():
+    """
+    Make SA13's `sql.select()` transparently accept calling semantics of SA14
+    and SA20, by swapping in the newer variant of `select_sa14()`.
+
+    This supports the test suite of `crate-python`, because it already uses the
+    modern calling semantics.
+    """
+    import sqlalchemy
+
+    sqlalchemy.select = select_sa14
+    sqlalchemy.sql.select = select_sa14
+    sqlalchemy.sql.expression.select = select_sa14

src/crate/client/sqlalchemy/tests/__init__.py

@@ -1,5 +1,13 @@
 # -*- coding: utf-8 -*-
 
+from ..compat.api13 import monkeypatch_amend_select_sa14
+from ..sa_version import SA_1_4, SA_VERSION
+
+# `sql.select()` of SQLAlchemy 1.3 uses old calling semantics,
+# but the test cases already need the modern ones.
+if SA_VERSION < SA_1_4:
+    monkeypatch_amend_select_sa14()
+
 from unittest import TestSuite, makeSuite
 from .connection_test import SqlAlchemyConnectionTest
 from .dict_test import SqlAlchemyDictTypeTest