python3-commons 0.20.2__tar.gz → 0.20.4__tar.gz

{python3_commons-0.20.2/src/python3_commons.egg-info → python3_commons-0.20.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python3-commons
-Version: 0.20.2
+Version: 0.20.4
 Summary: Re-usable Python3 code
 Author-email: Oleg Korsak <kamikaze.is.waiting.you@gmail.com>
 License-Expression: GPL-3.0
@@ -36,7 +36,7 @@ Provides-Extra: cache
 Requires-Dist: valkey[libvalkey]~=6.1.1; extra == "cache"
 Provides-Extra: database
 Requires-Dist: asyncpg~=0.31.0; extra == "database"
-Requires-Dist: SQLAlchemy[asyncio]~=2.0.50; extra == "database"
+Requires-Dist: SQLAlchemy[asyncio]~=2.0.49; extra == "database"
 Provides-Extra: object-storage
 Requires-Dist: aiobotocore~=3.7.0; extra == "object-storage"
 Requires-Dist: object-storage-client==0.0.30; extra == "object-storage"

{python3_commons-0.20.2 → python3_commons-0.20.4}/pyproject.toml

@@ -51,7 +51,7 @@ cache = [
 ]
 database = [
     "asyncpg~=0.31.0",
-    "SQLAlchemy[asyncio]~=2.0.50"
+    "SQLAlchemy[asyncio]~=2.0.49"
 ]
 object-storage = [
     "aiobotocore~=3.7.0",

python3_commons-0.20.4/src/python3_commons/db/__init__.py

@@ -0,0 +1,262 @@
+import asyncio
+import contextlib
+import logging
+import time
+from collections.abc import AsyncGenerator, Callable, Mapping
+from typing import TYPE_CHECKING
+
+try:
+    from sqlalchemy import MetaData, text
+    from sqlalchemy.exc import OperationalError, SQLAlchemyError
+    from sqlalchemy.exc import TimeoutError as SATimeoutError
+    from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_engine_from_config
+    from sqlalchemy.ext.asyncio.session import async_sessionmaker
+    from sqlalchemy.orm import declarative_base
+except ImportError as e:
+    msg = 'Install python3-commons[database] to use this feature'
+    raise RuntimeError(msg) from e
+
+if TYPE_CHECKING:
+    from python3_commons.conf import DBSettings
+
+logger = logging.getLogger(__name__)
+
+metadata = MetaData()
+Base = declarative_base(metadata=metadata)
+
+# How long (seconds) to wait for a connection from the pool before giving up.
+# This is the main guard against silent hangs.
+_DEFAULT_POOL_ACQUIRE_TIMEOUT = 10
+# Timeout passed to asyncpg for the TCP connect itself.
+_DEFAULT_CONNECT_TIMEOUT = 5
+# Timeout for the health-check query.
+_DEFAULT_HEALTH_CHECK_TIMEOUT = 5
+
+
+class DatabaseError(Exception):
+    """Base class for session-manager errors."""
+
+
+class EngineCreationError(DatabaseError):
+    """Raised when an engine cannot be created."""
+
+
+class SessionAcquireError(DatabaseError):
+    """Raised when a session cannot be acquired within the allotted time."""
+
+
+class AsyncSessionManager:
+    def __init__(
+        self,
+        db_configs: Mapping[str, DBSettings],
+        pool_acquire_timeout: float = _DEFAULT_POOL_ACQUIRE_TIMEOUT,
+    ) -> None:
+        self.db_configs: Mapping[str, DBSettings] = db_configs
+        self.pool_acquire_timeout = pool_acquire_timeout
+        self.engines: dict[str, AsyncEngine] = {}
+        self.session_makers: dict[str, async_sessionmaker] = {}
+
+    def get_db_config(self, name: str) -> DBSettings:
+        try:
+            return self.db_configs[name]
+        except KeyError:
+            logger.exception('Missing database config for key %r. Available: %s', name, list(self.db_configs))
+            raise
+
+    def _build_engine(self, name: str) -> AsyncEngine:
+        db_config = self.get_db_config(name)
+        dsn = db_config.dsn
+
+        logger.debug('Building engine for %r (dsn=%s)', name, dsn)
+
+        configuration = {
+            'url': dsn,
+            'echo': db_config.echo,
+            'pool_size': db_config.pool_size,
+            'max_overflow': db_config.max_overflow,
+            # pool_timeout: seconds to wait for a conn from the pool.
+            # Falls back to default so the pool never blocks forever.
+            'pool_timeout': getattr(db_config, 'pool_timeout', _DEFAULT_POOL_ACQUIRE_TIMEOUT),
+            'pool_recycle': db_config.pool_recycle,
+            'pool_pre_ping': db_config.pool_pre_ping,
+        }
+        connect_args = {'timeout': _DEFAULT_CONNECT_TIMEOUT}
+        # For asyncpg, command_timeout provides a per-statement timeout.
+        if 'postgresql' in dsn:
+            connect_args['command_timeout'] = float(db_config.statement_timeout)
+
+        try:
+            engine = async_engine_from_config(
+                configuration,
+                prefix='',
+                connect_args=connect_args,
+            )
+        except Exception as e:
+            logger.exception('Failed to create engine for %r', name)
+
+            msg = f'Could not create engine for {name!r}'
+            raise EngineCreationError(msg) from e
+
+        logger.info(
+            'Engine created for %r (pool_size=%s, max_overflow=%s, pool_timeout=%s)',
+            name,
+            configuration['pool_size'],
+            configuration['max_overflow'],
+            configuration['pool_timeout'],
+        )
+
+        return engine
+
+    def get_engine(self, name: str) -> AsyncEngine:
+        try:
+            return self.engines[name]
+        except KeyError:
+            engine = self._build_engine(name)
+            self.engines[name] = engine
+
+            return engine
+
+    async def dispose_engine(self, name: str) -> None:
+        """Gracefully close all pooled connections for *name*."""
+        engine = self.engines.pop(name, None)
+        self.session_makers.pop(name, None)
+
+        if engine is not None:
+            logger.info('Disposing engine for %r', name)
+
+            await engine.dispose()
+
+    async def dispose_all(self) -> None:
+        """Gracefully close every managed engine."""
+        for name in list(self.engines):
+            await self.dispose_engine(name)
+
+    def get_session_maker(self, name: str) -> async_sessionmaker:
+        try:
+            return self.session_makers[name]
+        except KeyError:
+            logger.debug('Creating session maker for %r', name)
+            engine = self.get_engine(name)
+            session_maker = async_sessionmaker(engine, expire_on_commit=False)
+            self.session_makers[name] = session_maker
+
+            return session_maker
+
+    def get_async_session(self, name: str) -> Callable[[], AsyncGenerator[AsyncSession]]:
+        """
+        Return a dependency-injection-friendly async generator that yields a
+        session, wrapped in an outer timeout so it can never hang silently.
+
+        Usage (FastAPI / any DI framework):
+            session: AsyncSession = Depends(manager.get_async_session("default"))
+        """
+
+        async def get_session() -> AsyncGenerator[AsyncSession]:
+            session_acquired = False
+            session_maker = self.get_session_maker(name)
+            t0 = time.monotonic()
+            logger.debug('Acquiring session for %r', name)
+
+            try:
+                async with asyncio.timeout(self.pool_acquire_timeout):
+                    async with session_maker() as session:
+                        session_acquired = True
+                        elapsed = time.monotonic() - t0
+                        logger.debug('Session acquired for %r in %.3fs', name, elapsed)
+
+                        try:
+                            yield session
+                        except Exception:
+                            logger.exception('Database communication error for %r; rolling back', name)
+                            await session.rollback()
+
+                            raise
+            except TimeoutError as e:
+                if session_acquired:
+                    raise
+
+                elapsed = time.monotonic() - t0
+                logger.exception(
+                    'Timed out waiting for a session for %r after %.3fs (limit=%.1fs)',
+                    name,
+                    elapsed,
+                    self.pool_acquire_timeout,
+                )
+
+                msg = f'Could not acquire a session for {name!r} within {self.pool_acquire_timeout}s'
+                raise SessionAcquireError(msg) from e
+            except (OperationalError, SATimeoutError) as e:
+                if session_acquired:
+                    raise
+
+                elapsed = time.monotonic() - t0
+
+                logger.exception('DB error acquiring session for %r after %.3fs', name, elapsed)
+
+                msg = f'DB error for {name!r}: {e}'
+                raise SessionAcquireError(msg) from e
+            except SQLAlchemyError as e:
+                if session_acquired:
+                    raise
+
+                logger.exception('Unexpected SQLAlchemy error for %r', name)
+
+                msg = f'SQLAlchemy error for {name!r}'
+
+                raise SessionAcquireError(msg) from e
+
+        return get_session
+
+    def get_session_context(self, name: str):
+        """
+        Return an async context manager that yields a session.
+
+        Usage:
+            async with manager.get_session_context("default") as session:
+                ...
+        """
+        return contextlib.asynccontextmanager(self.get_async_session(name))
+
+
+async def is_healthy(
+    engine: AsyncEngine,
+    timeout: float = _DEFAULT_HEALTH_CHECK_TIMEOUT,
+) -> bool:
+    """
+    Return True only if the engine can execute a trivial query within *timeout*
+    seconds.  All failures are caught and logged; never raises.
+    """
+    t0 = time.monotonic()
+
+    try:
+        async with asyncio.timeout(timeout):
+            async with engine.begin() as conn:
+                result = await conn.execute(text('SELECT 1'))
+                healthy = result.scalar() == 1
+
+        elapsed = time.monotonic() - t0
+
+        if healthy:
+            logger.debug('Health check passed in %.3fs', elapsed)
+        else:
+            logger.warning('Health check query returned unexpected result')
+    except TimeoutError:
+        elapsed = time.monotonic() - t0
+        logger.exception('Health check timed out after %.3fs (limit=%.1fs)', elapsed, timeout)
+
+        return False
+    except OperationalError as e:
+        msg = f'Health check failed: DB not reachable: {e}'
+        logger.exception(msg)
+
+        return False
+    except SQLAlchemyError:
+        logger.exception('Health check failed: SQLAlchemy error')
+
+        return False
+    except Exception:
+        logger.exception('Health check failed: unexpected error')
+
+        return False
+
+    return healthy

{python3_commons-0.20.2 → python3_commons-0.20.4/src/python3_commons.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python3-commons
-Version: 0.20.2
+Version: 0.20.4
 Summary: Re-usable Python3 code
 Author-email: Oleg Korsak <kamikaze.is.waiting.you@gmail.com>
 License-Expression: GPL-3.0
@@ -36,7 +36,7 @@ Provides-Extra: cache
 Requires-Dist: valkey[libvalkey]~=6.1.1; extra == "cache"
 Provides-Extra: database
 Requires-Dist: asyncpg~=0.31.0; extra == "database"
-Requires-Dist: SQLAlchemy[asyncio]~=2.0.50; extra == "database"
+Requires-Dist: SQLAlchemy[asyncio]~=2.0.49; extra == "database"
 Provides-Extra: object-storage
 Requires-Dist: aiobotocore~=3.7.0; extra == "object-storage"
 Requires-Dist: object-storage-client==0.0.30; extra == "object-storage"

{python3_commons-0.20.2 → python3_commons-0.20.4}/src/python3_commons.egg-info/SOURCES.txt

@@ -70,5 +70,7 @@ tests/unit/test_audit.py
 tests/unit/test_helpers.py
 tests/unit/test_msgpack.py
 tests/unit/test_msgspec.py
+tests/unit/db/__init__.py
+tests/unit/db/test_async_session_manager.py
 tests/unit/log/__init__.py
 tests/unit/log/test_formatters.py

{python3_commons-0.20.2 → python3_commons-0.20.4}/src/python3_commons.egg-info/requires.txt

@@ -29,7 +29,7 @@ valkey[libvalkey]~=6.1.1
 
 [database]
 asyncpg~=0.31.0
-SQLAlchemy[asyncio]~=2.0.50
+SQLAlchemy[asyncio]~=2.0.49
 
 [object-storage]
 aiobotocore~=3.7.0

python3_commons-0.20.4/tests/unit/db/test_async_session_manager.py

@@ -0,0 +1,75 @@
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from python3_commons.conf import DBSettings
+from python3_commons.db import AsyncSessionManager
+
+
+@pytest.mark.asyncio
+async def test_async_session_manager_timeout(mocker, caplog):
+    # Mock DBSettings
+    db_config = DBSettings(dsn='postgresql+asyncpg://user:pass@localhost/db', statement_timeout=1)
+
+    manager = AsyncSessionManager(db_configs={'default': db_config})
+
+    # Mock session and session maker
+    mock_session = AsyncMock()
+    mock_session_maker = MagicMock()
+    # session_maker() returns a context manager
+    mock_session_maker.return_value.__aenter__.return_value = mock_session
+
+    mocker.patch.object(manager, 'get_session_maker', return_value=mock_session_maker)
+
+    # Mock a driver-level timeout (TimeoutError)
+    mock_session.execute.side_effect = TimeoutError()
+
+    get_session_ctx_func = manager.get_session_context('default')
+
+    # We want to verify that TimeoutError from the driver is caught,
+    # logged as "Database communication error", rolled back, and re-raised.
+    with pytest.raises(TimeoutError):
+        async with get_session_ctx_func() as session:
+            await session.execute('SELECT 1')
+
+    assert 'Database communication error' in caplog.text
+
+
+@pytest.mark.asyncio
+async def test_async_session_manager_engine_config(mocker):
+    db_config = DBSettings(dsn='postgresql+asyncpg://user:pass@localhost/db', statement_timeout=42)
+    manager = AsyncSessionManager(db_configs={'default': db_config})
+
+    mock_engine_from_config = mocker.patch('python3_commons.db.async_engine_from_config')
+
+    manager.get_engine('default')
+
+    # Check that command_timeout was passed to connect_args for asyncpg
+    _, kwargs = mock_engine_from_config.call_args
+    assert kwargs['connect_args']['command_timeout'] == 42.0
+
+
+@pytest.mark.asyncio
+async def test_async_session_manager_logging(mocker, caplog):
+    # Mock DBSettings
+    db_config = DBSettings(dsn='postgresql+asyncpg://user:pass@localhost/db', statement_timeout=1)
+
+    manager = AsyncSessionManager(db_configs={'default': db_config})
+
+    # Mock session and session maker
+    mock_session = AsyncMock()
+    mock_session_maker = MagicMock()
+    mock_session_maker.return_value.__aenter__.return_value = mock_session
+
+    mocker.patch.object(manager, 'get_session_maker', return_value=mock_session_maker)
+
+    # Mock a session method to fail
+    mock_session.execute.side_effect = Exception('DB Error')
+
+    get_session_ctx_func = manager.get_session_context('default')
+
+    with pytest.raises(Exception, match='DB Error'):
+        async with get_session_ctx_func() as session:
+            await session.execute('SELECT 1')
+
+    assert 'Database communication error' in caplog.text

{python3_commons-0.20.2 → python3_commons-0.20.4}/uv.lock

@@ -1171,7 +1171,7 @@ requires-dist = [
     { name = "python3-commons", extras = ["database"], marker = "extra == 'authz'" },
     { name = "python3-commons", extras = ["object-storage"], marker = "extra == 'audit'" },
     { name = "requests", marker = "extra == 'soap-client'", specifier = "~=2.34.2" },
-    { name = "sqlalchemy", extras = ["asyncio"], marker = "extra == 'database'", specifier = "~=2.0.50" },
+    { name = "sqlalchemy", extras = ["asyncio"], marker = "extra == 'database'", specifier = "~=2.0.49" },
     { name = "valkey", extras = ["libvalkey"], marker = "extra == 'cache'", specifier = "~=6.1.1" },
     { name = "zeep", extras = ["async"], marker = "extra == 'audit'", specifier = "~=4.3.2" },
     { name = "zeep", extras = ["async"], marker = "extra == 'soap-client'", specifier = "~=4.3.2" },

python3_commons-0.20.2/src/python3_commons/db/__init__.py

@@ -1,101 +0,0 @@
-import contextlib
-import logging
-from collections.abc import AsyncGenerator, Callable, Mapping
-from typing import TYPE_CHECKING
-
-try:
-    from sqlalchemy import MetaData
-    from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_engine_from_config
-    from sqlalchemy.ext.asyncio.session import async_sessionmaker
-    from sqlalchemy.orm import declarative_base
-except ImportError as e:
-    msg = 'Install python3-commons[database] to use this feature'
-    raise RuntimeError(msg) from e
-
-if TYPE_CHECKING:
-    from python3_commons.conf import DBSettings
-
-logger = logging.getLogger(__name__)
-metadata = MetaData()
-Base = declarative_base(metadata=metadata)
-
-
-class AsyncSessionManager:
-    def __init__(self, db_configs: Mapping[str, DBSettings]) -> None:
-        self.db_configs: Mapping[str, DBSettings] = db_configs
-        self.engines: dict[str, AsyncEngine] = {}
-        self.session_makers: dict = {}
-
-    def get_db_config(self, name: str) -> DBSettings:
-        try:
-            return self.db_configs[name]
-        except KeyError:
-            logger.exception('Missing database settings: %s', name)
-
-            raise
-
-    def async_engine_from_db_config(self, name):
-        db_config = self.get_db_config(name)
-        configuration = {
-            'url': str(db_config.dsn),
-            'echo': db_config.echo,
-            'pool_size': db_config.pool_size,
-            'max_overflow': db_config.max_overflow,
-            'pool_timeout': db_config.pool_timeout,
-            'pool_recycle': db_config.pool_recycle,
-            'pool_pre_ping': db_config.pool_pre_ping,
-        }
-
-        return async_engine_from_config(
-            configuration,
-            prefix='',
-            connect_args={
-                'timeout': 5,  # asyncpg timeout
-            },
-        )
-
-    def get_engine(self, name: str) -> AsyncEngine:
-        try:
-            engine = self.engines[name]
-        except KeyError:
-            logger.debug('Creating engine: %s', name)
-            engine = self.async_engine_from_db_config(name)
-            self.engines[name] = engine
-
-        return engine
-
-    def get_session_maker(self, name: str):
-        try:
-            session_maker = self.session_makers[name]
-        except KeyError:
-            logger.debug('Creating session maker: %s', name)
-            engine = self.get_engine(name)
-            session_maker = async_sessionmaker(engine, expire_on_commit=False)
-            self.session_makers[name] = session_maker
-
-        return session_maker
-
-    def get_async_session(self, name: str) -> Callable[[], AsyncGenerator[AsyncSession]]:
-        async def get_session() -> AsyncGenerator[AsyncSession]:
-            session_maker = self.get_session_maker(name)
-
-            async with session_maker() as session:
-                yield session
-
-        return get_session
-
-    def get_session_context(self, name: str):
-        # TODO: cache
-        return contextlib.asynccontextmanager(self.get_async_session(name))
-
-
-async def is_healthy(engine: AsyncEngine) -> bool:
-    try:
-        async with engine.begin() as conn:
-            result = await conn.execute('SELECT 1;')
-
-            return result.scalar() == 1
-    except Exception:
-        logger.exception('Database connection is not healthy.')
-
-        return False