Refactoring/637 update dependency declaration pyexasol (#644)

* Update dependency declaration to `pyexasol`

* Set websocket_sslopt={"cert_reqs": ssl.CERT_NONE} in tests

* Add option to pass on fingerprint in websocket connection

* Reorganize documentation & add part about fingerprint to websocket-based dialect

* Prepare release 5.2.0

* Simplify test as always args = []

* Add unit test for websocket fingerprint usage

* Simplify tests to highlight difference between use cases

Author: ArBridgeman

README.rst

@@ -45,141 +45,40 @@ SQLAlchemy Dialect for EXASOL DB
 
 Getting Started with SQLAlchemy-Exasol
 --------------------------------------
-SQLAlchemy-Exasol supports multiple dialects, primarily differentiated by whether they are ODBC or Websocket based.
+SQLAlchemy-Exasol supports multiple dialects, primarily differentiated by whether they are ODBC or Websocket-based.
 
 Choosing a Dialect
 ++++++++++++++++++
 
-We recommend using the Websocket-based dialect due to its simplicity. ODBC-based dialects demand a thorough understanding of (Unix)ODBC, and the setup is considerably more complex.
+We recommend using the Websocket-based dialect due to its simplicity.
+ODBC-based dialects demand a thorough understanding of (Unix)ODBC, and the setup is considerably more complex.
 
 .. warning::
 
-    The maintenance of Turbodbc support is currently paused, and it may be phased out in future versions.
-    We are also planning to phase out the pyodbc support in the future.
-
+    The maintenance of Turbodbc & pyodbc support is currently paused, and it is planned to be phased out in future versions.
 
 
 System Requirements
 -------------------
-- Python
-- An Exasol DB (e.g. `docker-db <test_docker_image_>`_ or a `cloud instance <test_drive_>`_)
+- Exasol >= 7.1 (e.g. `docker-db <test_docker_image_>`_ or a `cloud instance <test_drive_>`_)
+- Python >= 3.10
 
 .. note::
 
    For ODBC-Based Dialects, additional libraries required for ODBC are necessary
    (for further details, checkout the `developer guide`_).
 
-Setting Up Your Python Project
-------------------------------
-
-Install SQLAlchemy-Exasol:
-
-.. code-block:: shell
-
-    $ pip install sqlalchemy-exasol
-
-.. note::
-
-   To use an ODBC-based dialect, you must specify it as an extra during installation.
-
-   .. code-block:: shell
-
-      pip install "sqlalchemy-exasol[pydobc]"
-      pip install "sqlalchemy-exasol[turbodbc]"
-
-
-Using SQLAlchemy with EXASOL DB
--------------------------------
-
-**Websocket based Dialect:**
-
-.. code-block:: python
-
-    from sqlalchemy import create_engine
-    url = "exa+websocket://A_USER:[email protected]:1234/my_schema?CONNECTIONLCALL=en_US.UTF-8"
-    e = create_engine(url)
-    query = "select 42 from dual"
-    with engine.connect() as con:
-        result = con.execute(sql.text(query)).fetchall()
-
-Examples:
-
-.. code-block:: python
-
-    from sqlalchemy import create_engine
-
-    engine = create_engine("exa+websocket://sys:[email protected]:8888")
-
-    # don't rely on autocommit for DML and DDL
-    with engine.begin() as con:
-        ...
-
-    # for non-DML or non-DDL queries
-    with engine.connect() as con:
-        ...
-
-.. code-block:: python
-
-    from sqlalchemy import create_engine
-
-    # ATTENTION:
-    # In terms of security it is NEVER a good idea to disable certificate validation!!
-    # In rare cases it may be handy for non-security related reasons.
-    # That said, if you are not a 100% sure about your scenario, stick with the
-    # secure defaults.
-    # In most cases, having a valid certificate and/or configuring the truststore(s)
-    # appropriately is the best/correct solution.
-    engine = create_engine("exa+websocket://sys:[email protected]:8888?SSLCertificate=SSL_VERIFY_NONE")
-    with engine.connect() as con:
-        ...
-
-
-**Pyodbc (ODBC based Dialect):**
-
-.. code-block:: python
-
-    from sqlalchemy import create_engine
-    url = "exa+pyodbc://A_USER:[email protected]:1234/my_schema?CONNECTIONLCALL=en_US.UTF-8&driver=EXAODBC"
-    e = create_engine(url)
-    query = "select 42 from dual"
-    with engine.connect() as con:
-        result = con.execute(sql.text(query)).fetchall()
-
-**Turbodbc (ODBC based Dialect):**
-
-.. code-block:: python
-
-    from sqlalchemy import create_engine
-    url = "exa+turbodbc://A_USER:[email protected]:1234/my_schema?CONNECTIONLCALL=en_US.UTF-8&driver=EXAODBC"
-    e = create_engine(url)
-    query = "select 42 from dual"
-    with engine.connect() as con:
-        result = con.execute(sql.text(query)).fetchall()
-
-
 Features
 --------
 
 - SELECT, INSERT, UPDATE, DELETE statements
 
-General Notes
--------------
+Getting Started
+---------------
 
-- Schema name and parameters are optional for the host url
-- At least on Linux/Unix systems it has proven valuable to pass 'CONNECTIONLCALL=en_US.UTF-8' as a url parameter. This will make sure that the client process (Python) and the EXASOL driver (UTF-8 internal) know how to interpret code pages correctly.
-- Always use all lower-case identifiers for schema, table and column names. SQLAlchemy treats all lower-case identifiers as case-insensitive, the dialect takes care of transforming the identifier into a case-insensitive representation of the specific database (in case of EXASol this is upper-case as for Oracle)
-- As of Exasol client driver version 4.1.2 you can pass the flag 'INTTYPESINRESULTSIFPOSSIBLE=y' in the connection string (or configure it in your DSN). This will convert DECIMAL data types to Integer-like data types. Creating integers is a factor three faster in Python than creating Decimals.
+Check out sqlalchemy-exasols's [User Guide(https://exasol.github.io/sqlalchemy-exasol/master/user_guide.html) page for your first steps.
 
 .. _developer guide: https://github.com/exasol/sqlalchemy-exasol/blob/master/doc/developer_guide/developer_guide.rst
+.. _test_docker_image: https://github.com/exasol/docker-db
 .. _odbc_driver: https://docs.exasol.com/db/latest/connect_exasol/drivers/odbc/odbc_linux.htm
 .. _test_drive: https://cloud.exasol.com/signup
-.. _test_docker_image: https://github.com/exasol/docker-db
-
-Known Issues
-------------
-* Insert
-    - Insert multiple empty rows via prepared statements does not work in all cases
-
-Development & Testing
----------------------
-See `developer guide`_

doc/changes/changelog.md

@@ -1,6 +1,7 @@
 # Changes
 
 * [unreleased](unreleased.md)
+* [5.2.0](changes_5.2.0.md)
 * [5.1.0](changes_5.1.0.md)
 * [5.0.0](changes_5.0.0.md)
 * [4.6.3](changes_4.6.3.md)
@@ -63,6 +64,7 @@
 hidden:
 ---
 unreleased
+changes_5.2.0
 changes_5.1.0
 changes_5.0.0
 changes_4.6.3
@@ -120,4 +122,3 @@ changes_0.7.5
 changes_0.7.4
 changes_0.7.0
 ```
-

doc/changes/changes_5.2.0.md

@@ -0,0 +1,68 @@
+# 5.2.0 - 2025-11-04
+
+This release drops the support for Python 3.9 as this Python version has reached its [end-of-life](https://devguide.python.org/versions/) in 2025-10. In consequence, the release also fixes security vulnerabilities by updating the dependencies.
+
+With this release, in the Websocket-based dialect, it is possible for users to pass `FINGERPRINT` into
+the connection URL to take advantage of an additional security feature in PyExasol version
+1.x.
+
+```python
+from sqlalchemy import create_engine
+    url = "exa+websocket://A_USER:[email protected]:1234/my_schema?FINGERPRINT=C70EB4DC0F62A3BF8FD7FF22D2EB2C489834958212AC12C867459AB86BE3A028"
+    engine = create_engine(url)
+    query = "select 42 from dual"
+    with engine.connect() as con:
+        result = con.execute(sql.text(query)).fetchall()
+```
+
+## Feature
+
+- #612: Updated CI tests to run against Exasol DB versions 7.1.30, 8.34.0, and 2025.1.0. Dropped support for Python 3.9.
+- #637: Added option to `exa-websocket` (Websocket-based dialect) to pass `FINGERPRINT` in the connection URL for additional security
+
+## Refactoring
+
+- #610: Altered string input into `Connection.execute()` to be handled properly with `sql.text()`
+- #614: Altered params input into `Connection.execute()` to be handled properly with `dict`
+- #616: Altered usage of MetaData which was binding to a connection to instead bind in the needed object or function
+- #617: Enacted warning for the deprecation of the `autoload` parameter and requirement of `bind`
+- #618: Switched DML & DDL executions from `engine.connect()` to `engine.begin()` usage
+- #637: Updated dependency declaration to `pyexasol`
+
+## Internal
+
+- #558: Updated to poetry 2.1.2 & relocked dependencies to resolve CVE-2025-27516
+- #548: Replaced pytest-exasol-itde with pytest-backend
+- Relocked dependencies to resolve CVE-2025-43859
+- #564: Replaced nox test:unit with that from exasol-toolbox
+- Reformatted files to meet project specifications
+- #588: Updated to exasol-toolbox 1.6.0 and relocked dependencies to resolve CVE-2025-50182, CVE-2025-50181, & CVE-2024-47081
+- #605: Removed non-ASCII unicode from templates & relocked dependencies to resolve CVE-2025-8869 (pip -> transitive dependency)
+- #640: Re-locked dependencies to resolve CVE-2025-8869 for transitive dependency pip
+
+## Dependency Updates
+
+### `main`
+* Updated dependency `packaging:24.2` to `25.0`
+* Updated dependency `pyexasol:0.27.0` to `1.2.1`
+* Updated dependency `pyodbc:5.2.0` to `5.3.0`
+
+### `dev`
+* Removed dependency `black:25.1.0`
+* Updated dependency `exasol-integration-test-docker-environment:3.4.0` to `4.3.0`
+* Updated dependency `exasol-toolbox:0.20.0` to `1.12.0`
+* Removed dependency `furo:2024.8.6`
+* Removed dependency `isort:5.13.2`
+* Removed dependency `mypy:1.15.0`
+* Updated dependency `nox:2025.2.9` to `2025.10.16`
+* Removed dependency `pre-commit:4.1.0`
+* Removed dependency `pylint:3.3.4`
+* Updated dependency `pyodbc:5.2.0` to `5.3.0`
+* Removed dependency `pytest-cov:6.0.0`
+* Added dependency `pytest-exasol-backend:1.2.2`
+* Removed dependency `pytest-exasol-itde:0.2.1`
+* Removed dependency `pytest-history:0.3.0`
+* Removed dependency `pyupgrade:3.19.1`
+* Removed dependency `sphinx:7.4.7`
+* Removed dependency `sphinx-copybutton:0.5.2`
+* Removed dependency `urlscan:1.0.6`

doc/changes/unreleased.md

@@ -1,27 +1 @@
 # Unreleased
-
-Due to an EOL for [Python 3.9 in 2025-10](https://devguide.python.org/versions/), we dropped support for it.
-This allows us to use the latest dependencies, which do not have open vulnerabilities.
-
-## Feature
-
-- #612: Updated CI tests to run against Exasol DB versions 7.1.30, 8.34.0, and 2025.1.0. Dropped support for Python 3.9.
-
-## Refactoring
-
-- #610: Altered string input into `Connection.execute()` to be handled properly with `sql.text()`
-- #614: Altered params input into `Connection.execute()` to be handled properly with `dict`
-- #616: Altered usage of MetaData which was binding to a connection to instead bind in the needed object or function
-- #617: Enacted warning for the deprecation of the `autoload` parameter and requirement of `bind`
-- #618: Switched DML & DDL executions from `engine.connect()` to `engine.begin()` usage
-
-## Internal
-
-- #558: Updated to poetry 2.1.2 & relocked dependencies to resolve CVE-2025-27516
-- #548: Replaced pytest-exasol-itde with pytest-backend
-- Relocked dependencies to resolve CVE-2025-43859
-- #564: Replaced nox test:unit with that from exasol-toolbox
-- Reformatted files to meet project specifications
-- #588: Updated to exasol-toolbox 1.6.0 and relocked dependencies to resolve CVE-2025-50182, CVE-2025-50181, & CVE-2024-47081
-- #605: Removed non-ASCII unicode from templates & relocked dependencies to resolve CVE-2025-8869 (pip -> transitive dependency)
-- #640: Re-locked dependencies to resolve CVE-2025-8869 for transitive dependency pip