Add support for SQLAlchemy 1.4

.github/workflows/tests.yml

@@ -19,7 +19,7 @@ jobs:
         os: [ubuntu-latest, macos-latest]
         python-version: ['3.7', '3.8', '3.9', '3.10']
         cratedb-version: ['4.8.0']
-        sqla-version: ['1.3.24']
+        sqla-version: ['1.3.24', '1.4.37']
       fail-fast: true
 
     steps:

CHANGES.txt

@@ -22,6 +22,43 @@ Unreleased
 - Added support for enabling SSL using SQLAlchemy DB URI with parameter
   ``?ssl=true``.
 
+- Added support for SQLAlchemy 1.4
+
+.. note::
+
+    For learning about the transition to SQLAlchemy 1.4, we recommend the
+    corresponding documentation `What’s New in SQLAlchemy 1.4?`_.
+
+
+
+Breaking changes
+----------------
+
+Textual column expressions
+''''''''''''''''''''''''''
+
+SQLAlchemy 1.4 became stricter on some details. It requires to wrap `CrateDB
+system columns`_ like ``_score`` in a `SQLAlchemy literal_column`_ type.
+Before, it was possible to use a query like this::
+
+    session.query(Character.name, '_score')
+
+It must now be written like::
+
+    session.query(Character.name, sa.literal_column('_score'))
+
+Otherwise, SQLAlchemy will complain like::
+
+    sqlalchemy.exc.ArgumentError: Textual column expression '_score' should be
+    explicitly declared with text('_score'), or use column('_score') for more
+    specificity
+
+
+.. _CrateDB system columns: https://crate.io/docs/crate/reference/en/4.8/general/ddl/system-columns.html
+.. _SQLAlchemy literal_column: https://docs.sqlalchemy.org/en/14/core/sqlelement.html#sqlalchemy.sql.expression.literal_column
+.. _What’s New in SQLAlchemy 1.4?: https://docs.sqlalchemy.org/en/14/changelog/migration_14.html
+
+
 2020/09/28 0.26.0
 =================
 

DEVELOP.rst

@@ -33,7 +33,12 @@ Run all tests::
 
 Run specific tests::
 
-    # Ignore all tests below src/crate/testing
+    ./bin/test -vvvv -t SqlAlchemyCompilerTest
+    ./bin/test -vvvv -t test_score
+    ./bin/test -vvvv -t sqlalchemy
+
+Ignore specific test directories::
+
     ./bin/test -vvvv --ignore_dir=testing
 
 You can run the tests against multiple Python interpreters with tox_::

README.rst

@@ -52,7 +52,7 @@ Prerequisites
 =============
 
 Recent versions of this library are validated on Python 3 (>= 3.7).
-It might also work on earlier versions of Python.
+It may also work on earlier versions of Python.
 
 
 Installation

docs/getting-started.rst

@@ -15,9 +15,8 @@ Learn how to install and get started the :ref:`CrateDB Python client library
 Prerequisites
 =============
 
-Python 3.7 is recommended.
-
-However, :ref:`older versions of Python <python-versions>` can still be used.
+Recent versions of this library are validated on Python 3 (>= 3.7).
+It may also work on earlier versions of Python.
 
 `Pip`_ should be installed on your system.
 

docs/sqlalchemy.rst

@@ -11,7 +11,7 @@ The CrateDB Python client library provides support for SQLAlchemy. A CrateDB
 configuration.
 
 The CrateDB Python client library is validated to work with SQLAlchemy versions
-``1.3``.
+``1.3`` and ``1.4``.
 
 .. NOTE::
 

lgtm.yml

@@ -0,0 +1,12 @@
+queries:
+
+  # Suppress some LGTM warnings.
+
+  # A module is imported with the "import" and "import from" statements.
+  # https://lgtm.com/rules/1818040193/
+  - exclude: py/import-and-import-from
+
+  # Disable rule to compensate parameter naming in `CrateCompiler._get_crud_params`.
+  # Using an alternative name for the first parameter of an instance method makes code more difficult to read.
+  # https://lgtm.com/rules/910082/
+  - exclude: py/not-named-self

setup.py

@@ -67,7 +67,7 @@ def read(path):
         test=['zope.testing>=4,<5',
               'zc.customdoctests>=1.0.1,<2',
               'stopit>=1.1.2,<2'],
-        sqlalchemy=['sqlalchemy>=1.0,<1.4', 'geojson>=2.5.0']
+        sqlalchemy=['sqlalchemy>=1.0,<1.5', 'geojson>=2.5.0']
     ),
     python_requires='>=3.4',
     install_requires=requirements,

src/crate/client/doctests/sqlalchemy.txt

@@ -289,7 +289,7 @@ the other rows. The higher the score value, the more relevant the row.
 In most cases ``_score`` is not part of the SQLAlchemy Table definition,
 so it must be passed as a string::
 
-    >>> session.query(Character.name, '_score') \
+    >>> session.query(Character.name, sa.literal_column('_score')) \
     ...     .filter(match(Character.quote_ft, 'space')) \
     ...     .all()
     [('Tricia McMillan', ...)]
@@ -298,11 +298,10 @@ To search on multiple columns you have to pass a dictionary with columns
 and ``boost`` attached. ``boost`` is a factor that increases the
 relevance of a column in respect to the other columns::
 
-    >>> from sqlalchemy.sql import text
     >>> session.query(Character.name) \
     ...           .filter(match({Character.name_ft: 1.5, Character.quote_ft: 0.1},
     ...                         'Arthur')) \
-    ...     .order_by(sa.desc(text('_score'))) \
+    ...     .order_by(sa.desc(sa.literal_column('_score'))) \
     ...     .all()
     [('Arthur Dent',), ('Tricia McMillan',)]