standard-rdbms 0.2.3__py3-none-any.whl

standard_rdbms-0.2.3.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.5
+Name: standard-rdbms
+Version: 0.2.3
+Summary: Async relational database helpers for the Standard Python library
+Project-URL: Documentation, https://appunni-m.github.io/python-standard/rdbms/
+Project-URL: Repository, https://github.com/appunni-m/python-standard
+Author: Standard contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: database,mysql,postgresql,sqlalchemy,sqlite,standard
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiomysql<1,>=0.2
+Requires-Dist: aiosqlite<1,>=0.19
+Requires-Dist: asyncpg<1,>=0.29
+Requires-Dist: cryptography>=41
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: sqlalchemy[asyncio]<3,>=2.0
+Requires-Dist: standard==0.2.3
+Description-Content-Type: text/markdown
+
+# standard-rdbms
+
+Async SQLAlchemy helpers for the [`standard`](https://pypi.org/project/standard/)
+Python library. The package provides `DatabaseConfig`, managed async sessions,
+SQLite, PostgreSQL, MySQL, and the `ensure_utc` property decorator under
+`std.rdbms`.
+
+After publication, install the integration directly:
+
+```console
+python -m pip install standard-rdbms
+```
+
+For local development from this repository:
+
+```console
+python -m pip install -e packages/standard-rdbms
+```
+
+```python
+from std.rdbms import DatabaseConfig, SQLiteMemDatabase
+
+database = SQLiteMemDatabase(DatabaseConfig(driver="sqlite+aiosqlite"))
+```
+
+See the [RDBMS guide](https://appunni-m.github.io/python-standard/rdbms/)
+for transactions, backend configuration, datetime behavior, and test commands.

standard_rdbms-0.2.3.dist-info/RECORD

@@ -0,0 +1,12 @@
+std/rdbms/__init__.py,sha256=3da93qO8FI73ZnVZiS0T97-3EEUP646TAJuXRhPCsp8,503
+std/rdbms/config.py,sha256=L3_GpLaAd1CXvgcnFOSxz5pmbJs-zVcJS78RZgR3Ky0,3721
+std/rdbms/database.py,sha256=m6LH7cy59FtCpcQeAv7j-SELbTToFhp9z1Y9rEjPBrs,3208
+std/rdbms/datetime_utils.py,sha256=FjHezM_U-Dzz-GTURBjima22hb0VTZ2_CJNrSqsro9E,960
+std/rdbms/mysql.py,sha256=GcV5cU1mAvr9NOvWnXHZ0CxcN0JlOsZc9ayu56BbLA4,1366
+std/rdbms/postgres.py,sha256=1_D3yS3VZHmjisp8h7tFV-FzSoy4VvzwRsoclhoPiD8,1386
+std/rdbms/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+std/rdbms/sqlite.py,sha256=i6dkkhk--_UTDF7VGqbmu2yxAhV5cnzJFrWPi5Tu1jA,2443
+standard_rdbms-0.2.3.dist-info/METADATA,sha256=XTgY3wUIfoPR2Y79VAQ34bE0cbly8uSxAyxYjzLf6Hc,1968
+standard_rdbms-0.2.3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+standard_rdbms-0.2.3.dist-info/licenses/LICENSE,sha256=sTIUP5MvMnfCSD0TdNTwjyFwBdAsnTBG2PfgodF7c9k,1078
+standard_rdbms-0.2.3.dist-info/RECORD,,

standard_rdbms-0.2.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

standard_rdbms-0.2.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Standard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

std/rdbms/__init__.py

@@ -0,0 +1,18 @@
+"""Async relational database helpers for Standard."""
+
+from std.rdbms.config import DatabaseConfig
+from std.rdbms.database import Database
+from std.rdbms.datetime_utils import ensure_utc
+from std.rdbms.mysql import MySQLDatabase
+from std.rdbms.postgres import PostgresDatabase
+from std.rdbms.sqlite import SQLiteDatabase, SQLiteMemDatabase
+
+__all__ = [
+    "Database",
+    "DatabaseConfig",
+    "MySQLDatabase",
+    "PostgresDatabase",
+    "SQLiteDatabase",
+    "SQLiteMemDatabase",
+    "ensure_utc",
+]

std/rdbms/config.py

@@ -0,0 +1,89 @@
+"""Validated settings and SQLAlchemy URL construction for relational databases."""
+
+from __future__ import annotations
+
+from pathlib import Path, PureWindowsPath
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from sqlalchemy.engine import URL
+
+
+class DatabaseConfig(BaseModel):
+    """Connection and pool settings shared by the async database managers.
+
+    The ``url`` property is computed from the current fields. It includes the
+    password when one is configured, so treat the returned string as a secret.
+    The password is excluded from the model representation and serialization.
+    """
+
+    model_config = ConfigDict(validate_assignment=True, extra="forbid")
+
+    driver: str = Field(default="mysql+aiomysql", description="SQLAlchemy async dialect and driver")
+    host: str = Field(default="localhost", description="Database server hostname")
+    port: int | None = Field(default=None, ge=1, le=65535, description="Database server port")
+    user: str | None = Field(default=None, description="Database username")
+    password: str | None = Field(
+        default=None,
+        repr=False,
+        exclude=True,
+        description="Database password",
+    )
+    name: str = Field(default="agent_framework", description="Database name or SQLite path")
+    echo: bool = Field(default=False, description="Echo SQL statements for debugging")
+    pool_size: int = Field(default=5, ge=0, description="Number of persistent connections")
+    max_overflow: int = Field(default=10, ge=-1, description="Connections beyond the pool size")
+    pool_timeout: float = Field(default=30.0, ge=0, description="Seconds to wait for a connection")
+    pool_recycle: int = Field(
+        default=1800, ge=-1, description="Recycle connections after this many seconds"
+    )
+    connect_args: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Driver-specific connection arguments",
+    )
+
+    @field_validator("driver", "host", "name")
+    @classmethod
+    def require_non_empty_text(cls, value: str) -> str:
+        """Reject empty strings before they become malformed connection URLs."""
+        if not value.strip():
+            raise ValueError("must not be empty")
+        return value
+
+    @property
+    def url(self) -> str:
+        """Return a SQLAlchemy URL string built with proper credential escaping."""
+        if self.driver.startswith("sqlite") and self.name == ":memory:":
+            return f"{self.driver}:///:memory:"
+        return self._sqlalchemy_url().render_as_string(hide_password=False)
+
+    def _sqlalchemy_url(self) -> URL:
+        """Build a structured SQLAlchemy URL without hand-escaping credentials."""
+        if self.driver.startswith("sqlite"):
+            database = self.name
+            if database != ":memory:":
+                is_absolute = (
+                    Path(database).is_absolute() or PureWindowsPath(database).is_absolute()
+                )
+                if not is_absolute and not database.startswith(("./", ".\\")):
+                    database = f"./{database}"
+            return URL.create(drivername=self.driver, database=database)
+
+        port = self.port
+        if port is None:
+            if "mysql" in self.driver:
+                port = 3306
+            elif "postgres" in self.driver:
+                port = 5432
+            else:
+                # Preserve the original fallback for custom network dialects.
+                port = 3306
+
+        return URL.create(
+            drivername=self.driver,
+            username=self.user or None,
+            password=self.password if self.user else None,
+            host=self.host,
+            port=port,
+            database=self.name,
+        )

std/rdbms/database.py

@@ -0,0 +1,90 @@
+"""Async SQLAlchemy database lifecycle and transaction management."""
+
+from __future__ import annotations
+
+import sys
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
+
+from std.rdbms.config import DatabaseConfig
+
+
+class Database(ABC):
+    """Own an async engine and provide commit-on-success session scopes.
+
+    Each session is intended for one asyncio task at a time. A successful
+    ``session()`` scope commits; any exception, including cancellation, rolls
+    back and re-raises. The session is closed in either case.
+    """
+
+    def __init__(self, settings: DatabaseConfig) -> None:
+        """Create the engine and its session factory without opening a connection."""
+        self.settings = settings
+        self._engine = self._create_engine()
+        self._session_factory = async_sessionmaker(
+            self._engine,
+            class_=AsyncSession,
+            expire_on_commit=False,
+            autoflush=False,
+        )
+        self._disposed = False
+
+    @property
+    def engine(self) -> AsyncEngine:
+        """Return the SQLAlchemy engine for migrations and explicit transactions."""
+        return self._engine
+
+    @abstractmethod
+    def _create_engine(self) -> AsyncEngine:
+        """Create the backend-specific async SQLAlchemy engine."""
+        raise NotImplementedError
+
+    @asynccontextmanager
+    async def session(self) -> AsyncIterator[AsyncSession]:
+        """Yield a session that commits on success and rolls back on failure."""
+        if self._disposed:
+            raise RuntimeError("Database has been disposed")
+
+        session = self._session_factory()
+        try:
+            yield session
+            await session.commit()
+        except BaseException as error:
+            try:
+                await session.rollback()
+            except BaseException as rollback_error:
+                error.add_note(
+                    "Session rollback also failed: "
+                    f"{type(rollback_error).__name__}: {rollback_error}"
+                )
+            raise
+        finally:
+            active_error = sys.exception()
+            try:
+                await session.close()
+            except BaseException as close_error:
+                if active_error is None:
+                    raise
+                active_error.add_note(
+                    f"Session close also failed: {type(close_error).__name__}: {close_error}"
+                )
+
+    async def dispose(self) -> None:
+        """Close pooled connections; calling this more than once is safe."""
+        if self._disposed:
+            return
+        await self._engine.dispose()
+        self._disposed = True
+
+    async def __aenter__(self) -> Database:
+        """Return this database for use as an async resource context manager."""
+        if self._disposed:
+            raise RuntimeError("Database has been disposed")
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        """Dispose the engine when leaving an async resource context."""
+        await self.dispose()

std/rdbms/datetime_utils.py

@@ -0,0 +1,28 @@
+"""Timezone helpers for database-backed model properties."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import UTC, datetime
+from functools import wraps
+
+
+def ensure_utc(function: Callable[..., datetime | None]) -> property:
+    """Decorate a property getter so returned datetimes are UTC-aware.
+
+    Naive values are interpreted as UTC, matching the historical helper
+    contract. Aware values are converted to UTC. ``None`` passes through.
+    """
+
+    @wraps(function)
+    def getter(instance: object) -> datetime | None:
+        value = function(instance)
+        if value is None:
+            return None
+        if not isinstance(value, datetime):
+            raise TypeError("ensure_utc property getter must return datetime or None")
+        if value.tzinfo is None or value.utcoffset() is None:
+            return value.replace(tzinfo=UTC)
+        return value.astimezone(UTC)
+
+    return property(getter)

std/rdbms/mysql.py

@@ -0,0 +1,34 @@
+"""Async MySQL database manager using SQLAlchemy's async dialect."""
+
+from __future__ import annotations
+
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+from std.rdbms.config import DatabaseConfig
+from std.rdbms.database import Database
+
+
+class MySQLDatabase(Database):
+    """Manage MySQL connections with health checks and configured pooling."""
+
+    def __init__(self, config: DatabaseConfig) -> None:
+        """Copy settings and provide safe MySQL charset and transaction defaults."""
+        settings = config.model_copy(deep=True)
+        if not settings.driver.startswith("mysql+"):
+            raise ValueError("MySQLDatabase requires a MySQL async driver")
+        settings.connect_args.setdefault("charset", "utf8mb4")
+        settings.connect_args.setdefault("autocommit", False)
+        super().__init__(settings)
+
+    def _create_engine(self) -> AsyncEngine:
+        """Create a pooled MySQL engine with pre-ping enabled."""
+        return create_async_engine(
+            self.settings.url,
+            echo=self.settings.echo,
+            pool_size=self.settings.pool_size,
+            max_overflow=self.settings.max_overflow,
+            pool_timeout=self.settings.pool_timeout,
+            pool_recycle=self.settings.pool_recycle,
+            pool_pre_ping=True,
+            connect_args=self.settings.connect_args,
+        )

std/rdbms/postgres.py

@@ -0,0 +1,33 @@
+"""Async PostgreSQL database manager using SQLAlchemy's async dialect."""
+
+from __future__ import annotations
+
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+from std.rdbms.config import DatabaseConfig
+from std.rdbms.database import Database
+
+
+class PostgresDatabase(Database):
+    """Manage PostgreSQL connections with health checks and configured pooling."""
+
+    def __init__(self, config: DatabaseConfig) -> None:
+        """Copy settings and provide a recognizable PostgreSQL application name."""
+        settings = config.model_copy(deep=True)
+        if not settings.driver.startswith(("postgresql+", "postgres+")):
+            raise ValueError("PostgresDatabase requires a PostgreSQL async driver")
+        settings.connect_args.setdefault("server_settings", {"application_name": "standard-rdbms"})
+        super().__init__(settings)
+
+    def _create_engine(self) -> AsyncEngine:
+        """Create a pooled PostgreSQL engine with pre-ping enabled."""
+        return create_async_engine(
+            self.settings.url,
+            echo=self.settings.echo,
+            pool_size=self.settings.pool_size,
+            max_overflow=self.settings.max_overflow,
+            pool_timeout=self.settings.pool_timeout,
+            pool_recycle=self.settings.pool_recycle,
+            pool_pre_ping=True,
+            connect_args=self.settings.connect_args,
+        )

std/rdbms/sqlite.py

@@ -0,0 +1,59 @@
+"""Async SQLite managers for persistent files and isolated in-memory databases."""
+
+from __future__ import annotations
+
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+from sqlalchemy.pool import NullPool, StaticPool
+
+from std.rdbms.config import DatabaseConfig
+from std.rdbms.database import Database
+
+
+def _sqlite_settings(config: DatabaseConfig) -> DatabaseConfig:
+    """Copy and validate SQLite settings without mutating the caller's model."""
+    settings = config.model_copy(deep=True)
+    if not settings.driver.startswith("sqlite+aiosqlite"):
+        raise ValueError("SQLite managers require the sqlite+aiosqlite driver")
+    settings.connect_args.setdefault("check_same_thread", False)
+    return settings
+
+
+class SQLiteDatabase(Database):
+    """Manage a file-backed SQLite database with a fresh connection per checkout."""
+
+    def __init__(self, config: DatabaseConfig) -> None:
+        """Create a file-backed database; use ``SQLiteMemDatabase`` for memory."""
+        if config.name == ":memory:":
+            raise ValueError("Use SQLiteMemDatabase for an in-memory SQLite database")
+        super().__init__(_sqlite_settings(config))
+
+    def _create_engine(self) -> AsyncEngine:
+        """Create a file-backed engine with ``NullPool`` and configured connect args."""
+        return create_async_engine(
+            self.settings.url,
+            echo=self.settings.echo,
+            poolclass=NullPool,
+            connect_args=self.settings.connect_args,
+        )
+
+
+class SQLiteMemDatabase(Database):
+    """Manage one shared in-memory SQLite database for the lifetime of its engine."""
+
+    def __init__(self, config: DatabaseConfig) -> None:
+        """Force this manager's copied settings to use one shared in-memory database."""
+        settings = config.model_copy(deep=True)
+        if not settings.driver.startswith("sqlite+aiosqlite"):
+            raise ValueError("SQLite managers require the sqlite+aiosqlite driver")
+        settings.name = ":memory:"
+        settings.connect_args.setdefault("check_same_thread", False)
+        super().__init__(settings)
+
+    def _create_engine(self) -> AsyncEngine:
+        """Create an engine with ``StaticPool`` so sessions see the same memory DB."""
+        return create_async_engine(
+            self.settings.url,
+            echo=self.settings.echo,
+            poolclass=StaticPool,
+            connect_args=self.settings.connect_args,
+        )