sqlalchemy-firebird-async 0.1.0__tar.gz → 0.2.0__tar.gz

{sqlalchemy_firebird_async-0.1.0 → sqlalchemy_firebird_async-0.2.0}/.gitignore

@@ -147,3 +147,4 @@ cython_debug/
 
 # PyCharm
 .idea/
+uv.lock

{sqlalchemy_firebird_async-0.1.0 → sqlalchemy_firebird_async-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlalchemy-firebird-async
-Version: 0.1.0
+Version: 0.2.0
 Summary: Asyncio support for Firebird in SQLAlchemy
 Project-URL: Homepage, https://github.com/attid/sqlalchemy-firebird-async
 Author-email: Igor Tolstov <attid0@gmail.com>
@@ -16,9 +16,12 @@ Requires-Dist: sqlalchemy-firebird>=2.0.0
 Requires-Dist: sqlalchemy>=2.0.0
 Provides-Extra: all
 Requires-Dist: fdb>=2.0; extra == 'all'
+Requires-Dist: firebird-driver>=1.0; extra == 'all'
 Requires-Dist: firebirdsql>=1.0; extra == 'all'
 Provides-Extra: fdb
 Requires-Dist: fdb>=2.0; extra == 'fdb'
+Provides-Extra: firebird-driver
+Requires-Dist: firebird-driver>=1.0; extra == 'firebird-driver'
 Provides-Extra: firebirdsql
 Requires-Dist: firebirdsql>=1.0; extra == 'firebirdsql'
 Provides-Extra: test
@@ -37,18 +40,22 @@ Description-Content-Type: text/markdown
 
 This library provides proper `asyncio` support for Firebird databases in SQLAlchemy 2.0+, allowing you to write fully asynchronous code using modern Python patterns.
 
-It supports two underlying drivers:
-1. **`fdb`** (Recommended) - Runs the official C-based driver in a thread pool. Fast and stable.
-2. **`firebirdsql`** - Pure Python asyncio driver. Currently experimental due to upstream issues.
+It supports three underlying drivers:
+1. **`fdb`** (Legacy) - Runs the official C-based driver in a thread pool. Fast and stable.
+2. **`firebird-driver`** (Modern) - Official driver for Firebird 3+. Also threaded (run_in_executor).
+3. **`firebirdsql`** - Pure Python asyncio driver. Currently experimental due to upstream issues.
 
 ## 📦 Installation
 
 Install using pip:
 
 ```bash
-# Recommended: Install with the FDB driver (Threaded, Fast)
+# Install with the FDB driver (Legacy, Stable)
 pip install "sqlalchemy-firebird-async[fdb]"
 
+# Install with the Firebird Driver (Modern, FB 3.0+)
+pip install "sqlalchemy-firebird-async[firebird-driver]"
+
 # Install with pure python driver (Experimental)
 pip install "sqlalchemy-firebird-async[firebirdsql]"
 # Note: For correct async behavior with firebirdsql, you might need a patched version:
@@ -57,9 +64,9 @@ pip install "sqlalchemy-firebird-async[firebirdsql]"
 
 ## 🚀 Quick Start
 
-### 1. Using FDB Driver (Recommended)
+### 1. Using FDB Driver (Legacy)
 
-This dialect runs the official `fdb` driver in a thread pool (`run_in_executor`). While not "truly" async at the socket level, it provides the best performance and stability currently available for Firebird in Python.
+This dialect runs the legacy `fdb` driver in a thread pool.
 
 **URL Scheme:** `firebird+fdb_async://`
 
@@ -70,29 +77,25 @@ from sqlalchemy import text
 
 async def main():
     # Format: firebird+fdb_async://user:password@host:port/path/to/db
-    # Note: For Linux, ensure the path is absolute (e.g. //firebird/data/...)
     dsn = "firebird+fdb_async://sysdba:masterkey@localhost:3050//firebird/data/employee.fdb"
     
     engine = create_async_engine(dsn, echo=True)
+    # ... usage is identical for all drivers
+```
 
-    async with engine.begin() as conn:
-        result = await conn.execute(text("SELECT rdb$get_context('SYSTEM', 'ENGINE_VERSION') FROM rdb$database"))
-        version = result.scalar()
-        print(f"Firebird Version: {version}")
+### 2. Using Firebird Driver (Modern)
 
-    # Using AsyncSession
-    async_session = async_sessionmaker(engine, expire_on_commit=False)
-    async with async_session() as session:
-        result = await session.execute(text("SELECT count(*) FROM rdb$relations"))
-        print(f"Total tables: {result.scalar()}")
+This dialect uses the modern `firebird-driver` package (the official driver for Firebird 3.0+), running in a thread pool. It requires Firebird 3.0 or higher.
 
-    await engine.dispose()
+**URL Scheme:** `firebird+firebird_async://`
 
-if __name__ == "__main__":
-    asyncio.run(main())
+```python
+engine = create_async_engine(
+    "firebird+firebird_async://sysdba:masterkey@localhost:3050//firebird/data/employee.fdb?charset=UTF8"
+)
 ```
 
-### 2. Using Native Async Driver (firebirdsql)
+### 3. Using Native Async Driver (firebirdsql)
 
 **Warning:** The upstream `firebirdsql` driver currently has issues with `asyncio` compatibility (bugs causing crashes or incorrect behavior).
 A patched fork is available at [attid/pyfirebirdsql](https://github.com/attid/pyfirebirdsql.git), which fixes the async logic but currently exhibits significantly lower performance (approx. 4x slower than fdb).
@@ -124,7 +127,8 @@ As seen above, `fdb` in a thread pool is significantly faster for high-load scen
 
 | Driver | Protocol | URL Scheme |
 | :--- | :--- | :--- |
-| **fdb** (Recommended) | TCP/IP | `firebird+fdb_async://user:pass@host:port/db_path` |
+| **fdb** (Legacy) | TCP/IP | `firebird+fdb_async://user:pass@host:port/db_path` |
+| **firebird-driver** (Modern) | TCP/IP | `firebird+firebird_async://user:pass@host:port/db_path` |
 | **firebirdsql** | TCP/IP | `firebird+firebirdsql_async://user:pass@host:port/db_path` |
 
 ## 🤝 Contributing

{sqlalchemy_firebird_async-0.1.0 → sqlalchemy_firebird_async-0.2.0}/README.md

@@ -8,18 +8,22 @@
 
 This library provides proper `asyncio` support for Firebird databases in SQLAlchemy 2.0+, allowing you to write fully asynchronous code using modern Python patterns.
 
-It supports two underlying drivers:
-1. **`fdb`** (Recommended) - Runs the official C-based driver in a thread pool. Fast and stable.
-2. **`firebirdsql`** - Pure Python asyncio driver. Currently experimental due to upstream issues.
+It supports three underlying drivers:
+1. **`fdb`** (Legacy) - Runs the official C-based driver in a thread pool. Fast and stable.
+2. **`firebird-driver`** (Modern) - Official driver for Firebird 3+. Also threaded (run_in_executor).
+3. **`firebirdsql`** - Pure Python asyncio driver. Currently experimental due to upstream issues.
 
 ## 📦 Installation
 
 Install using pip:
 
 ```bash
-# Recommended: Install with the FDB driver (Threaded, Fast)
+# Install with the FDB driver (Legacy, Stable)
 pip install "sqlalchemy-firebird-async[fdb]"
 
+# Install with the Firebird Driver (Modern, FB 3.0+)
+pip install "sqlalchemy-firebird-async[firebird-driver]"
+
 # Install with pure python driver (Experimental)
 pip install "sqlalchemy-firebird-async[firebirdsql]"
 # Note: For correct async behavior with firebirdsql, you might need a patched version:
@@ -28,9 +32,9 @@ pip install "sqlalchemy-firebird-async[firebirdsql]"
 
 ## 🚀 Quick Start
 
-### 1. Using FDB Driver (Recommended)
+### 1. Using FDB Driver (Legacy)
 
-This dialect runs the official `fdb` driver in a thread pool (`run_in_executor`). While not "truly" async at the socket level, it provides the best performance and stability currently available for Firebird in Python.
+This dialect runs the legacy `fdb` driver in a thread pool.
 
 **URL Scheme:** `firebird+fdb_async://`
 
@@ -41,29 +45,25 @@ from sqlalchemy import text
 
 async def main():
     # Format: firebird+fdb_async://user:password@host:port/path/to/db
-    # Note: For Linux, ensure the path is absolute (e.g. //firebird/data/...)
     dsn = "firebird+fdb_async://sysdba:masterkey@localhost:3050//firebird/data/employee.fdb"
     
     engine = create_async_engine(dsn, echo=True)
+    # ... usage is identical for all drivers
+```
 
-    async with engine.begin() as conn:
-        result = await conn.execute(text("SELECT rdb$get_context('SYSTEM', 'ENGINE_VERSION') FROM rdb$database"))
-        version = result.scalar()
-        print(f"Firebird Version: {version}")
+### 2. Using Firebird Driver (Modern)
 
-    # Using AsyncSession
-    async_session = async_sessionmaker(engine, expire_on_commit=False)
-    async with async_session() as session:
-        result = await session.execute(text("SELECT count(*) FROM rdb$relations"))
-        print(f"Total tables: {result.scalar()}")
+This dialect uses the modern `firebird-driver` package (the official driver for Firebird 3.0+), running in a thread pool. It requires Firebird 3.0 or higher.
 
-    await engine.dispose()
+**URL Scheme:** `firebird+firebird_async://`
 
-if __name__ == "__main__":
-    asyncio.run(main())
+```python
+engine = create_async_engine(
+    "firebird+firebird_async://sysdba:masterkey@localhost:3050//firebird/data/employee.fdb?charset=UTF8"
+)
 ```
 
-### 2. Using Native Async Driver (firebirdsql)
+### 3. Using Native Async Driver (firebirdsql)
 
 **Warning:** The upstream `firebirdsql` driver currently has issues with `asyncio` compatibility (bugs causing crashes or incorrect behavior).
 A patched fork is available at [attid/pyfirebirdsql](https://github.com/attid/pyfirebirdsql.git), which fixes the async logic but currently exhibits significantly lower performance (approx. 4x slower than fdb).
@@ -95,7 +95,8 @@ As seen above, `fdb` in a thread pool is significantly faster for high-load scen
 
 | Driver | Protocol | URL Scheme |
 | :--- | :--- | :--- |
-| **fdb** (Recommended) | TCP/IP | `firebird+fdb_async://user:pass@host:port/db_path` |
+| **fdb** (Legacy) | TCP/IP | `firebird+fdb_async://user:pass@host:port/db_path` |
+| **firebird-driver** (Modern) | TCP/IP | `firebird+firebird_async://user:pass@host:port/db_path` |
 | **firebirdsql** | TCP/IP | `firebird+firebirdsql_async://user:pass@host:port/db_path` |
 
 ## 🤝 Contributing

{sqlalchemy_firebird_async-0.1.0 → sqlalchemy_firebird_async-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlalchemy-firebird-async"
-version = "0.1.0"
+version = "0.2.0"
 description = "Asyncio support for Firebird in SQLAlchemy"
 readme = "README.md"
 authors = [
@@ -27,7 +27,8 @@ dependencies = [
 [project.optional-dependencies]
 fdb = ["fdb>=2.0"]
 firebirdsql = ["firebirdsql>=1.0"]
-all = ["fdb>=2.0", "firebirdsql>=1.0"]
+firebird-driver = ["firebird-driver>=1.0"]
+all = ["fdb>=2.0", "firebirdsql>=1.0", "firebird-driver>=1.0"]
 test = [
     "pytest>=7.0",
     "pytest-asyncio>=0.21",
@@ -37,6 +38,7 @@ test = [
 [project.entry-points."sqlalchemy.dialects"]
 "firebird.fdb_async" = "sqlalchemy_firebird_async.fdb:AsyncFDBDialect"
 "firebird.firebirdsql_async" = "sqlalchemy_firebird_async.firebirdsql:AsyncFirebirdSQLDialect"
+"firebird.firebird_async" = "sqlalchemy_firebird_async.firebird_driver:AsyncFirebirdDialect"
 
 [project.urls]
-"Homepage" = "https://github.com/attid/sqlalchemy-firebird-async"
+"Homepage" = "https://github.com/attid/sqlalchemy-firebird-async"

sqlalchemy_firebird_async-0.2.0/src/sqlalchemy_firebird_async/compiler.py

@@ -0,0 +1,12 @@
+from sqlalchemy_firebird.base import FBTypeCompiler
+
+class PatchedFBTypeCompiler(FBTypeCompiler):
+    def _render_string_type(self, type_, name, length_override=None):
+        # Fix for TypeError: unsupported operand type(s) for +: 'int' and 'str'
+        if not isinstance(name, str):
+            # Attempt to restore type name from the type object itself
+            if hasattr(type_, "__visit_name__"):
+                name = type_.__visit_name__.upper()
+            else:
+                name = "VARCHAR"
+        return super()._render_string_type(type_, name, length_override)

sqlalchemy_firebird_async-0.2.0/src/sqlalchemy_firebird_async/fdb.py

@@ -0,0 +1,157 @@
+import asyncio
+from functools import partial
+from sqlalchemy.util.concurrency import await_only
+from greenlet import getcurrent
+
+
+class AsyncCursor:
+    def __init__(self, sync_cursor, loop):
+        self._sync_cursor = sync_cursor
+        self._loop = loop
+
+    def _exec(self, func, *args, **kwargs):
+        # Проверяем, находимся ли мы в контексте greenlet, созданном SQLAlchemy
+        if getattr(getcurrent(), "__sqlalchemy_greenlet_provider__", None):
+            return await_only(self._loop.run_in_executor(None, partial(func, *args, **kwargs)))
+        else:
+            # Если нет, вызываем синхронно (например, внутри run_sync)
+            return func(*args, **kwargs)
+
+    def execute(self, operation, parameters=None):
+        if parameters is None:
+            return self._exec(self._sync_cursor.execute, operation)
+        else:
+            return self._exec(self._sync_cursor.execute, operation, parameters)
+
+    def executemany(self, operation, seq_of_parameters):
+        return self._exec(self._sync_cursor.executemany, operation, seq_of_parameters)
+
+    def fetchone(self):
+        return self._exec(self._sync_cursor.fetchone)
+
+    def fetchmany(self, size=None):
+        if size is None:
+            return self._exec(self._sync_cursor.fetchmany)
+        return self._exec(self._sync_cursor.fetchmany, size)
+
+    def fetchall(self):
+        return self._exec(self._sync_cursor.fetchall)
+
+    def close(self):
+        return self._exec(self._sync_cursor.close)
+    
+    async def _async_soft_close(self):
+        pass
+    
+    def nextset(self):
+        return self._exec(self._sync_cursor.nextset)
+
+    def __getattr__(self, name):
+        return getattr(self._sync_cursor, name)
+
+
+class AsyncConnection:
+    def __init__(self, sync_connection, loop):
+        self._sync_connection = sync_connection
+        self._loop = loop
+
+    def _exec(self, func, *args, **kwargs):
+        if getattr(getcurrent(), "__sqlalchemy_greenlet_provider__", None):
+            return await_only(self._loop.run_in_executor(None, partial(func, *args, **kwargs)))
+        else:
+            return func(*args, **kwargs)
+
+    def cursor(self):
+        return AsyncCursor(self._sync_connection.cursor(), self._loop)
+
+    def commit(self):
+        return self._exec(self._sync_connection.commit)
+
+    def rollback(self):
+        return self._exec(self._sync_connection.rollback)
+
+    def close(self):
+        return self._exec(self._sync_connection.close)
+
+    def __getattr__(self, name):
+        return getattr(self._sync_connection, name)
+
+
+class AsyncDBAPI:
+    def __init__(self, sync_dbapi):
+        self._sync_dbapi = sync_dbapi
+        self.paramstyle = getattr(sync_dbapi, "paramstyle", "qmark")
+        self.apilevel = getattr(sync_dbapi, "apilevel", "2.0")
+        self.threadsafety = getattr(sync_dbapi, "threadsafety", 0)
+        for attr in (
+            "Warning",
+            "Error",
+            "InterfaceError",
+            "DatabaseError",
+            "DataError",
+            "OperationalError",
+            "IntegrityError",
+            "InternalError",
+            "ProgrammingError",
+            "NotSupportedError",
+        ):
+            if hasattr(sync_dbapi, attr):
+                setattr(self, attr, getattr(sync_dbapi, attr))
+
+    def connect(self, *args, **kwargs):
+        async_creator_fn = kwargs.pop("async_creator_fn", None)
+        loop = asyncio.get_running_loop()
+        
+        def _connect():
+            if async_creator_fn is not None:
+                # Здесь мы не можем просто так вызвать await_only, если creator асинхронный
+                # Но fdb синхронный, так что всё ок.
+                # Если передан async_creator, то это для firebirdsql, но мы в fdb.py
+                return async_creator_fn(*args, **kwargs) # вернет корутину? нет, это коллбек
+            else:
+                return self._sync_dbapi.connect(*args, **kwargs)
+
+        if getattr(getcurrent(), "__sqlalchemy_greenlet_provider__", None):
+            # Если async_creator_fn возвращает корутину, то await_only ее дождется
+            # Но для fdb это синхронный вызов, поэтому run_in_executor
+             sync_conn = await_only(loop.run_in_executor(None, partial(self._sync_dbapi.connect, *args, **kwargs)))
+        else:
+             sync_conn = self._sync_dbapi.connect(*args, **kwargs)
+            
+        return AsyncConnection(sync_conn, loop)
+
+from sqlalchemy.pool import AsyncAdaptedQueuePool
+import sqlalchemy_firebird.fdb as fdb
+from .compiler import PatchedFBTypeCompiler
+
+
+class AsyncFDBDialect(fdb.FBDialect_fdb):
+    name = "firebird.fdb_async"
+    driver = "fdb_async"
+    is_async = True
+    supports_statement_cache = False
+    poolclass = AsyncAdaptedQueuePool
+    # Explicitly set type compiler to ensure our patch is used
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.type_compiler_instance = PatchedFBTypeCompiler(self)
+        self.type_compiler = self.type_compiler_instance
+
+    def is_disconnect(self, e, connection, cursor):
+        # Handle fdb disconnect errors which store error code in args[1]
+        # Base implementation checks for self.driver == "fdb"
+        if isinstance(e, self.dbapi.DatabaseError):
+             # We are essentially fdb
+             return (e.args[1] in (335546001, 335546003, 335546005)) or \
+                    ("Error writing data to the connection" in str(e))
+        return super().is_disconnect(e, connection, cursor)
+
+    @classmethod
+    def import_dbapi(cls):
+        import fdb as sync_fdb
+
+        return AsyncDBAPI(sync_fdb)
+
+    @classmethod
+    def dbapi(cls):
+        return cls.import_dbapi()

sqlalchemy_firebird_async-0.2.0/src/sqlalchemy_firebird_async/firebird_driver.py

@@ -0,0 +1,135 @@
+import asyncio
+from functools import partial
+from sqlalchemy.util.concurrency import await_only
+from greenlet import getcurrent
+from sqlalchemy.pool import AsyncAdaptedQueuePool
+import sqlalchemy_firebird.firebird as firebird_sync
+import firebird.driver as sync_driver
+
+
+class AsyncCursor:
+    def __init__(self, sync_cursor, loop):
+        self._sync_cursor = sync_cursor
+        self._loop = loop
+
+    def _exec(self, func, *args, **kwargs):
+        if getattr(getcurrent(), "__sqlalchemy_greenlet_provider__", None):
+            return await_only(self._loop.run_in_executor(None, partial(func, *args, **kwargs)))
+        else:
+            return func(*args, **kwargs)
+
+    def execute(self, operation, parameters=None):
+        if parameters is None:
+            return self._exec(self._sync_cursor.execute, operation)
+        else:
+            return self._exec(self._sync_cursor.execute, operation, parameters)
+
+    def executemany(self, operation, seq_of_parameters):
+        return self._exec(self._sync_cursor.executemany, operation, seq_of_parameters)
+
+    def fetchone(self):
+        return self._exec(self._sync_cursor.fetchone)
+
+    def fetchmany(self, size=None):
+        if size is None:
+            return self._exec(self._sync_cursor.fetchmany)
+        return self._exec(self._sync_cursor.fetchmany, size)
+
+    def fetchall(self):
+        return self._exec(self._sync_cursor.fetchall)
+
+    def close(self):
+        return self._exec(self._sync_cursor.close)
+    
+    async def _async_soft_close(self):
+        pass
+    
+    def nextset(self):
+        return self._exec(self._sync_cursor.nextset)
+
+    def __getattr__(self, name):
+        return getattr(self._sync_cursor, name)
+
+
+class AsyncConnection:
+    def __init__(self, sync_connection, loop):
+        self._sync_connection = sync_connection
+        self._loop = loop
+
+    def _exec(self, func, *args, **kwargs):
+        if getattr(getcurrent(), "__sqlalchemy_greenlet_provider__", None):
+            return await_only(self._loop.run_in_executor(None, partial(func, *args, **kwargs)))
+        else:
+            return func(*args, **kwargs)
+
+    def cursor(self):
+        return AsyncCursor(self._sync_connection.cursor(), self._loop)
+
+    def commit(self):
+        return self._exec(self._sync_connection.commit)
+
+    def rollback(self):
+        return self._exec(self._sync_connection.rollback)
+
+    def close(self):
+        return self._exec(self._sync_connection.close)
+
+    def __getattr__(self, name):
+        return getattr(self._sync_connection, name)
+
+
+class AsyncDBAPI:
+    def __init__(self, sync_dbapi):
+        self._sync_dbapi = sync_dbapi
+        self.paramstyle = getattr(sync_dbapi, "paramstyle", "qmark")
+        self.apilevel = getattr(sync_dbapi, "apilevel", "2.0")
+        self.threadsafety = getattr(sync_dbapi, "threadsafety", 1)
+        for attr in (
+            "Warning",
+            "Error",
+            "InterfaceError",
+            "DatabaseError",
+            "DataError",
+            "OperationalError",
+            "IntegrityError",
+            "InternalError",
+            "ProgrammingError",
+            "NotSupportedError",
+        ):
+            if hasattr(sync_dbapi, attr):
+                setattr(self, attr, getattr(sync_dbapi, attr))
+
+    def connect(self, *args, **kwargs):
+        async_creator_fn = kwargs.pop("async_creator_fn", None)
+        loop = asyncio.get_running_loop()
+        
+        if getattr(getcurrent(), "__sqlalchemy_greenlet_provider__", None):
+            sync_conn = await_only(loop.run_in_executor(None, partial(self._sync_dbapi.connect, *args, **kwargs)))
+        else:
+            sync_conn = self._sync_dbapi.connect(*args, **kwargs)
+            
+        return AsyncConnection(sync_conn, loop)
+
+
+from .compiler import PatchedFBTypeCompiler
+
+
+class AsyncFirebirdDialect(firebird_sync.FBDialect_firebird):
+    name = "firebird.firebird_async"
+    driver = "firebird_async"
+    is_async = True
+    supports_statement_cache = False
+    poolclass = AsyncAdaptedQueuePool
+    
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.type_compiler_instance = PatchedFBTypeCompiler(self)
+        self.type_compiler = self.type_compiler_instance
+
+    @classmethod
+    def import_dbapi(cls):
+        return AsyncDBAPI(sync_driver)
+
+    @classmethod
+    def dbapi(cls):
+        return cls.import_dbapi()