✨ Add aioodbc driver support

.github/workflows/test-sqlite.yaml

@@ -9,12 +9,11 @@ on:
       - main
 
 jobs:
-
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ '3.8', '3.9', '3.10', '3.11', '3.12' ]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - name: checkout
@@ -25,6 +24,11 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
+      - name: install SQLite3 ODBC Driver
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y unixodbc unixodbc-dev
+
       - name: install poetry
         env:
           POETRY_VERSION: "1.7.1"

docs/database_support/mssql.md

@@ -1,9 +1,10 @@
 # [Microsoft SQL Server](https://www.microsoft.com/en-us/sql-server/sql-server-2019)
 Supported drivers:
 
-| dbapi                              | default    | driver          | connection class              |
-|------------------------------------|------------|-----------------|-------------------------------|
-| [pymssql](https://www.pymssql.org) | :thumbsup: | `mssql+pymssql` | `pymssql._pymssql.Connection` |
+| dbapi                                          | default      | driver          | connection class                |
+| ---------------------------------------------- | ------------ | --------------- | ------------------------------- |
+| [pymssql](https://www.pymssql.org)             | :thumbsup:   | `mssql+pymssql` | `pymssql._pymssql.Connection`   |
+| [aioodbc](https://github.com/aio-libs/aioodbc) | :thumbsdown: | `mssql+aioodbc` | `aioodbc.connection.Connection` |
 
 ## pymssql
 `pymssql` is the default dbapi driver for Microsoft SQL Server in *pydapper*.
@@ -49,3 +50,31 @@ Use *pydapper* with a custom connection pool.
 ```python
 {!docs/../docs_src/connections/pymssql_using.py!}
 ```
+
+## aioodbc
+`aioodbc` supports async methods for Microsoft SQL Server and other ODBC-compatible databases. 
+It is based on [pyodbc](https://github.com/mkleehammer/pyodbc).
+
+### Installation
+=== "pip"
+    ```console
+    pip install pydapper[aioodbc]
+    ```
+
+=== "poetry"
+    ```console
+    poetry add pydapper -E aioodbc
+    ```
+
+### Example - `connect_async`
+To use async with MSSQL you need to use `aioodbc` driver.
+Please see the [pyodbc docs](https://github.com/mkleehammer/pyodbc/wiki) for a full description about connecting.
+```python
+{!docs/../docs_src/connections/aioodbc_mssql_connect.py!}
+```
+
+### Example - `using_async`
+Use *pydapper* with a `aioodbc` connection pool.
+```python
+{!docs/../docs_src/connections/aioodbc_mssql_using.py!}
+```

docs/database_support/sqlite.md

@@ -2,7 +2,7 @@
 Supported drivers:
 
 | dbapi                                                     | default    | driver           | connection class     |
-|-----------------------------------------------------------|------------|------------------|----------------------|
+| --------------------------------------------------------- | ---------- | ---------------- | -------------------- |
 | [sqlite3](https://docs.python.org/3/library/sqlite3.html) | :thumbsup: | `sqlite+sqlite3` | `sqlite3.Connection` |
 
 ## sqlite3
@@ -49,3 +49,31 @@ Use *pydapper* with a custom connection pool.
 ```python
 {!docs/../docs_src/connections/sqlite3_using.py!}
 ```
+
+## aioodbc
+`aioodbc` supports async methods for ODBC-compatible databases. It is based on [pyodbc](https://github.com/mkleehammer/pyodbc).
+You may need to install [SQLite3 ODBC Driver](http://www.ch-werner.de/sqliteodbc/).
+
+### Installation
+=== "pip"
+    ```console
+    pip install pydapper[aioodbc]
+    ```
+
+=== "poetry"
+    ```console
+    poetry add pydapper -E aioodbc
+    ```
+
+### Example - `connect_async`
+To use async with SQLite you can use `aioodbc` driver.
+Please see the [pyodbc docs](https://github.com/mkleehammer/pyodbc/wiki) for a full description about connecting.
+```python
+{!docs/../docs_src/connections/aioodbc_sqlite_connect.py!}
+```
+
+### Example - `using_async`
+Use *pydapper* with a `aioodbc` connection pool.
+```python
+{!docs/../docs_src/connections/aioodbc_sqlite_using.py!}
+```

docs_src/connections/aioodbc_mssql_connect.py

@@ -0,0 +1,19 @@
+import asyncio
+
+import pydapper
+
+
+async def main():
+    async with pydapper.connect_async("mssql+aioodbc://sa:pydapper@localhost/pydapper") as commands:
+        print(type(commands))
+        # <class 'pydapper.odbc.aioodbc.AioodbcCommands'>
+
+        print(type(commands.connection))
+        # <class 'aioodbc.connection.Connection'>
+
+        async with commands.cursor() as raw_cursor:
+            print(type(raw_cursor))
+            # <class 'aioodbc.cursor.Cursor'>
+
+
+asyncio.run(main())

docs_src/connections/aioodbc_mssql_using.py

@@ -0,0 +1,21 @@
+import asyncio
+
+import aioodbc
+
+import pydapper
+
+
+async def main():
+    async with aioodbc.create_pool(
+        dsn="DRIVER={ODBC Driver 17 for SQL Server};SERVER=localhost,1433;DATABASE=pydapper;UID=sa;PWD=pydapper"
+    ) as pool:
+        conn = await pool.acquire()
+        async with pydapper.using_async(conn) as commands:
+            print(type(commands))
+            # <class 'pydapper.odbc.aioodbc.AioodbcCommands'>
+
+            print(type(commands.connection))
+            # <class 'aioodbc.connection.Connection'>
+
+
+asyncio.run(main())

docs_src/connections/aioodbc_sqlite_connect.py

@@ -0,0 +1,19 @@
+import asyncio
+
+import pydapper
+
+
+async def main():
+    async with pydapper.connect_async("sqlite+aioodbc://pydapper.db") as commands:
+        print(type(commands))
+        # <class 'pydapper.odbc.aioodbc.AioodbcCommands'>
+
+        print(type(commands.connection))
+        # <class 'aioodbc.connection.Connection'>
+
+        async with commands.cursor() as raw_cursor:
+            print(type(raw_cursor))
+            # <class 'aioodbc.cursor.Cursor'>
+
+
+asyncio.run(main())

docs_src/connections/aioodbc_sqlite_using.py

@@ -0,0 +1,19 @@
+import asyncio
+
+import aioodbc
+
+import pydapper
+
+
+async def main():
+    async with aioodbc.create_pool(dsn="DRIVER={{SQLite3 ODBC Driver}};DATABASE=pydapper.db") as pool:
+        conn = await pool.acquire()
+        async with pydapper.using_async(conn) as commands:
+            print(type(commands))
+            # <class 'pydapper.odbc.aioodbc.AioodbcCommands'>
+
+            print(type(commands.connection))
+            # <class 'aioodbc.connection.Connection'>
+
+
+asyncio.run(main())

pydapper/__init__.py

@@ -7,6 +7,7 @@
 from .main import using_async
 from .mssql import PymssqlCommands as _PymssqlCommands
 from .mysql import MySqlConnectorPythonCommands as _MySqlConnectorPythonCommands
+from .odbc import AioodbcCommands as _AioodbcCommands
 from .oracle import CxOracleCommands as _CxOracleCommands
 from .postgresql import AiopgCommands as _AioPgCommand
 from .postgresql import Psycopg2Commands as _Psycopg2Commands

pydapper/odbc/__init__.py

@@ -0,0 +1 @@
+from .aioodbc import AioodbcCommands

pydapper/odbc/aioodbc.py

@@ -0,0 +1,62 @@
+from typing import TYPE_CHECKING
+
+from pydapper.commands import CommandsAsync
+from pydapper.commands import DefaultSqlParamHandler
+from pydapper.main import register_async
+from pydapper.types import AsyncCursorType
+from pydapper.utils import import_dbapi_module
+
+if TYPE_CHECKING:
+    from ..dsn_parser import PydapperParseResult
+
+
+_DRIVERS = {
+    "mssql": "{ODBC Driver 17 for SQL Server}",
+    "mysql": "{MySQL ODBC 8.0 Unicode Driver}",
+    "postgresql": "{PostgreSQL Unicode}",
+    "sqlite": "{SQLite3 ODBC Driver}",
+}
+
+
+def pydapper_dsn_to_odbc(parsed_dsn: "PydapperParseResult") -> str:
+    chunks = {}
+
+    server = parsed_dsn.host
+    if parsed_dsn.port:
+        server += f",{parsed_dsn.port}"
+
+    if server:
+        chunks["server"] = server
+
+    if parsed_dsn.username:
+        chunks["uid"] = parsed_dsn.username
+
+    if parsed_dsn.password:
+        chunks["pwd"] = parsed_dsn.password
+
+    if parsed_dsn.dbname:
+        chunks["database"] = parsed_dsn.dbname
+
+    if parsed_dsn.dbms:
+        chunks["driver"] = _DRIVERS.get(parsed_dsn.dbms, "")
+
+    chunks = {**chunks, **parsed_dsn.query}
+
+    return ";".join([f"{k.upper()}={v}" for k, v in chunks.items()])
+
+
+@register_async("aioodbc")
+class AioodbcCommands(CommandsAsync):
+    class SqlParamHandler(DefaultSqlParamHandler):
+        def get_param_placeholder(self, param_name: str) -> str:
+            return "(?)"
+
+    @classmethod
+    async def connect_async(cls, parsed_dsn: "PydapperParseResult", **connect_kwargs) -> "CommandsAsync":
+        aioodbc = import_dbapi_module("aioodbc")
+        dsn = pydapper_dsn_to_odbc(parsed_dsn)
+        conn = await aioodbc.connect(
+            dsn=dsn,
+            **connect_kwargs,
+        )
+        return cls(conn)