sqlphilosophy 0.1.0__py3-none-any.whl

sqlphilosophy/aio/repository.py

@@ -0,0 +1,400 @@
+"""Generic async session-bound repository for ORM CRUD."""
+
+from __future__ import annotations
+from collections.abc import Sequence
+from typing import Any
+from typing import cast
+from sqlalchemy import delete
+from sqlalchemy import func
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy import select
+from sqlalchemy import update
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.orm.interfaces import LoaderOption
+from sqlphilosophy.aio.protocols import AsyncRepositoryFactory
+from sqlphilosophy.aio.query import AsyncSqlAlchemyStatementBuilder
+from sqlphilosophy.aio.query import AsyncStatementQueryBuilder
+from sqlphilosophy.audit.model import AuditMixin
+from sqlphilosophy.sorting import ListQuery
+from sqlphilosophy.sorting import SortConfig
+from sqlphilosophy.sql import rows_mapping
+from sqlphilosophy.types import IdList
+from sqlphilosophy.types import PrimaryKey
+from sqlphilosophy.types import RowMapping
+from sqlphilosophy.types import RowValue
+from sqlphilosophy.types import SqlBindParams
+from sqlphilosophy.types import SqlSelect
+
+LoadRelations = Sequence[LoaderOption]
+
+
+class AsyncBaseRepository[T: DeclarativeBase]:
+    """Async session-scoped CRUD helpers for a single mapped model."""
+
+    def __init__(
+        self,
+        model: type[T],
+        session: AsyncSession,
+        factory: AsyncRepositoryFactory | None = None,
+    ) -> None:
+        self.model = model
+        self.session = session
+        self._factory = factory
+        pk_cols = self.inspect_model(model).primary_key
+        if len(pk_cols) != 1:
+            raise TypeError(f"{model.__name__} must have a single-column primary key")
+        self._pk_column = pk_cols[0]
+
+    @classmethod
+    def inspect_model(cls, model: type[DeclarativeBase]) -> Any:
+        """Return SQLAlchemy ORM mapper inspection for ``model``."""
+        return sa_inspect(model)
+
+    def inspect(self) -> Any:
+        """Return SQLAlchemy ORM mapper inspection for this repository's model."""
+        return self.inspect_model(self.model)
+
+    async def list_table_names(self) -> frozenset[str]:
+        """Return visible table names on the session connection."""
+        connection = await self.session.connection()
+
+        def _names(sync_conn: object) -> frozenset[str]:
+            return frozenset(sa_inspect(sync_conn).get_table_names())
+
+        return await connection.run_sync(_names)
+
+    async def has_table(self, table_name: str) -> bool:
+        """True when ``table_name`` exists on the session connection."""
+        return table_name in await self.list_table_names()
+
+    def _apply_load_relations(self, stmt: Any, load_relations: LoadRelations | None) -> Any:
+        if load_relations:
+            return stmt.options(*load_relations)
+        return stmt
+
+    async def _scalar_result(self, stmt: Any, *, unique: bool = False) -> Any:
+        result = await self.session.scalars(stmt)
+        if unique:
+            return result.unique()
+        return result
+
+    async def fetch_statement_mappings(
+        self, stmt: Any, params: RowMapping | None = None
+    ) -> list[RowMapping]:
+        """Execute ``stmt`` and return all rows as mappings."""
+        result = await self.session.execute(stmt, params or {})
+        mapped = result.mappings()
+        rows = mapped.all() if hasattr(mapped, "all") else mapped
+        return rows_mapping(rows)
+
+    async def scalar_count(self, stmt: SqlSelect, params: SqlBindParams | None = None) -> int:
+        """Execute a scalar count/select statement and return ``int``."""
+        result = await self.session.execute(stmt, params or {})
+        return int(result.scalar_one())
+
+    async def iter_mappings(self, stmt: SqlSelect, params: SqlBindParams | None = None):
+        """Yield each result row as a plain ``dict``."""
+        result = await self.session.execute(stmt, params or {})
+        for row in result.mappings():
+            yield dict(row)
+
+    async def fetch_mapping_first(
+        self, stmt: SqlSelect, params: SqlBindParams | None = None
+    ) -> RowMapping | None:
+        """Execute ``stmt`` and return the first row as a mapping, or ``None``."""
+        result = await self.session.execute(stmt, params or {})
+        row = result.mappings().first()
+        return dict(row) if row is not None else None
+
+    async def fetch_mapping_one(
+        self, stmt: SqlSelect, params: SqlBindParams | None = None
+    ) -> RowMapping:
+        """Execute ``stmt`` and return exactly one row as a mapping."""
+        result = await self.session.execute(stmt, params or {})
+        return dict(result.mappings().one())
+
+    async def fetch_mappings_page(
+        self,
+        stmt: Any,
+        *,
+        limit: int,
+        offset: int,
+        params: RowMapping | None = None,
+    ) -> list[RowMapping]:
+        """Execute ``stmt`` with limit/offset; return normalized row mappings."""
+        if limit < 0:
+            raise ValueError("limit must be >= 0")
+        if offset < 0:
+            raise ValueError("offset must be >= 0")
+        paged = stmt.limit(limit).offset(offset)
+        return await self.fetch_statement_mappings(paged, params)
+
+    async def fetch_sorted_mappings(
+        self,
+        stmt: Any,
+        *,
+        list_query: ListQuery,
+        params: RowMapping | None = None,
+        sort: SortConfig | None = None,
+    ) -> list[RowMapping]:
+        """Apply optional sort, then return one page of row mappings."""
+        if sort is not None:
+            stmt = stmt.order_by(*sort.order_clauses(list_query.order_by))
+        return await self.fetch_mappings_page(
+            stmt,
+            limit=list_query.limit,
+            offset=list_query.offset,
+            params=params,
+        )
+
+    async def get_by_id(
+        self, obj_id: PrimaryKey, load_relations: LoadRelations | None = None
+    ) -> T | None:
+        """Fetch a single record by primary key with optional eager loading."""
+        stmt = select(self.model).where(self._pk_column == obj_id)
+        stmt = self._apply_load_relations(stmt, load_relations)
+        result = await self.session.scalars(stmt)
+        return result.first()
+
+    async def exists(self, obj_id: PrimaryKey) -> bool:
+        """True when a row exists for the primary key."""
+        return await self.get_by_id(obj_id) is not None
+
+    async def exists_where(self, **filters: object) -> bool:
+        """True when at least one row matches optional equality filters."""
+        return await self.count(**filters) > 0
+
+    async def count(self, **filters: object) -> int:
+        """Count rows matching optional equality filters."""
+        stmt = select(func.count()).select_from(self.model)
+        if filters:
+            stmt = stmt.filter_by(**filters)
+        result = await self.session.scalar(stmt)
+        return int(result or 0)
+
+    async def first(
+        self, load_relations: LoadRelations | None = None, **filters: object
+    ) -> T | None:
+        """Return the first row matching filters, with optional eager loading."""
+        stmt = select(self.model).filter_by(**filters).limit(1)
+        stmt = self._apply_load_relations(stmt, load_relations)
+        result = await self.session.scalars(stmt)
+        return result.first()
+
+    async def get(self, obj_id: PrimaryKey, load_relations: LoadRelations | None = None) -> T:
+        """Fetch a single record by primary key; raise if missing."""
+        obj = await self.get_by_id(obj_id, load_relations=load_relations)
+        if obj is None:
+            raise LookupError(f"{self.model.__name__} matching id={obj_id!r} not found")
+        return obj
+
+    async def get_many(
+        self, ids: Sequence[PrimaryKey], load_relations: LoadRelations | None = None
+    ) -> Sequence[T]:
+        """Fetch multiple records by primary key."""
+        if not ids:
+            return []
+        stmt = select(self.model).where(self._pk_column.in_(ids))
+        stmt = self._apply_load_relations(stmt, load_relations)
+        result = await self._scalar_result(stmt, unique=load_relations is not None)
+        return result.all()
+
+    async def filter(
+        self,
+        *,
+        page: int = 1,
+        limit: int | None = None,
+        load_relations: LoadRelations | None = None,
+        **filters: object,
+    ) -> Sequence[T]:
+        """Return rows matching optional equality filters, optionally paginated."""
+        if page < 1:
+            raise ValueError("page must be >= 1")
+        if limit is not None and limit < 1:
+            raise ValueError("limit must be >= 1")
+        stmt = select(self.model).filter_by(**filters).order_by(self._pk_column)
+        if limit is not None:
+            stmt = stmt.limit(limit).offset((page - 1) * limit)
+        stmt = self._apply_load_relations(stmt, load_relations)
+        result = await self._scalar_result(stmt, unique=load_relations is not None)
+        return result.all()
+
+    async def get_all(
+        self,
+        *,
+        page: int = 1,
+        limit: int | None = None,
+        load_relations: LoadRelations | None = None,
+    ) -> Sequence[T]:
+        """Fetch records for this model type, optionally paginated by ``page`` and ``limit``."""
+        if page < 1:
+            raise ValueError("page must be >= 1")
+        if limit is not None and limit < 1:
+            raise ValueError("limit must be >= 1")
+        statement = select(self.model).order_by(self._pk_column)
+        if limit is not None:
+            statement = statement.limit(limit).offset((page - 1) * limit)
+        statement = self._apply_load_relations(statement, load_relations)
+        result = await self._scalar_result(statement, unique=load_relations is not None)
+        return result.all()
+
+    async def get_with_join(
+        self,
+        target_model: type[Any],
+        *filter_expressions: Any,
+        join_on: Any = None,
+    ) -> Sequence[tuple[T, Any]]:
+        """Explicit INNER JOIN returning ``(base_row, target_row)`` tuples."""
+        stmt = select(self.model, target_model)
+        if join_on is not None:
+            stmt = stmt.join(target_model, join_on)
+        else:
+            stmt = stmt.join(target_model)  # pragma: no cover
+        if filter_expressions:
+            stmt = stmt.where(*filter_expressions)
+        result = await self.session.execute(stmt)
+        return result.all()
+
+    async def create(self, **fields: object) -> T:
+        """Construct, stage, and flush a new instance."""
+        return await self.add(self.model(**fields))
+
+    async def get_or_create(
+        self,
+        *,
+        defaults: RowMapping | None = None,
+        **lookup: object,
+    ) -> tuple[T, bool]:
+        """Return ``(instance, created)`` for equality ``lookup`` filters."""
+        existing = await self.first(**lookup)
+        if existing is not None:
+            return existing, False
+        payload: RowMapping = {**(defaults or {}), **lookup}
+        return await self.create(**payload), True
+
+    async def add(self, obj: T) -> T:
+        """Stage a new instance; caller commits in the orchestration layer."""
+        self.session.add(obj)
+        await self.session.flush()
+        return obj
+
+    async def update_partial(
+        self,
+        obj_id: PrimaryKey,
+        fields: RowMapping,
+        writable: frozenset[str],
+        *,
+        touch_updated_on: bool = False,
+    ) -> int:
+        """Apply a partial update; returns affected row count (0 if none)."""
+        if issubclass(self.model, AuditMixin):
+            audit_updates = {k: v for k, v in fields.items() if k in writable}
+            if not audit_updates:
+                return 0
+            row = await self.session.get(self.model, obj_id)
+            if row is None:
+                return 0
+            for key, value in audit_updates.items():
+                setattr(row, key, value)
+            await self.session.flush()
+            return 1
+        core_updates: RowMapping = {k: v for k, v in fields.items() if k in writable}
+        if not core_updates:
+            return 0
+        if touch_updated_on:
+            core_updates = cast(
+                RowMapping,
+                {**dict(core_updates), "updated_on": cast(RowValue, func.now())},
+            )
+        pk_col = self._pk_column
+        stmt = update(self.model).where(pk_col == obj_id).values(**core_updates)
+        result = await self.session.execute(stmt)
+        return int(result.rowcount or 0)
+
+    async def update_where(
+        self,
+        *,
+        criteria: Sequence[object],
+        values: RowMapping,
+        params: SqlBindParams | None = None,
+    ) -> int:
+        """Bulk UPDATE rows matching ``criteria``; returns affected row count."""
+        if not values:
+            return 0
+        stmt = update(self.model).where(*criteria).values(**values)
+        result = await self.session.execute(stmt, params or {})
+        return int(result.rowcount or 0)
+
+    async def delete_where(
+        self,
+        *,
+        criteria: Sequence[object],
+        params: SqlBindParams | None = None,
+    ) -> int:
+        """Delete rows matching ``criteria`` via PK lookup + ``delete_many``."""
+        if not criteria:
+            return 0
+        pk_key = self._pk_column.key
+        builder = self.statement().select_columns(self._pk_column).where(*criteria)
+        if params:
+            builder = builder.with_params(params)
+        rows = await builder.mappings().all()
+        ids = [row[pk_key] for row in rows]
+        return await self.delete_many(ids)
+
+    async def remove(self, obj_id: PrimaryKey) -> bool:
+        """Delete a record by primary key."""
+        statement = delete(self.model).where(self._pk_column == obj_id)
+        result = await self.session.execute(statement)
+        return bool(result.rowcount)
+
+    async def delete_many(self, ids: IdList) -> int:
+        """Delete multiple records by primary key."""
+        if not ids:
+            return 0
+        stmt = delete(self.model).where(self._pk_column.in_(ids))
+        result = await self.session.execute(stmt)
+        return int(result.rowcount or 0)
+
+    async def delete_all(self) -> int:
+        """Delete every row for this model. Dev/ops only — prefer ``delete_where`` in app code."""
+        result = await self.session.execute(delete(self.model))
+        return int(result.rowcount or 0)
+
+    async def batched_purge_ids(
+        self,
+        *,
+        criteria: list[object],
+        batch_size: int,
+    ) -> int:
+        """Delete rows matching ``criteria`` in ``batch_size`` chunks, committing each batch."""
+        pk_key = self._pk_column.key
+        total = 0
+        while True:
+            rows = await (
+                self.statement()
+                .select_columns(self._pk_column)
+                .where(*criteria)
+                .limit(batch_size)
+                .mappings()
+                .all()
+            )
+            ids = [row[pk_key] for row in rows]
+            if not ids:
+                break
+            total += await self.delete_many(ids)
+            await self.session.commit()
+        return total
+
+    def statement(self) -> AsyncStatementQueryBuilder[T]:
+        """Return a fluent statement builder for reads on this model (default read path)."""
+        if self._factory is not None:
+            return self._factory.create_statement(self.model)
+        return AsyncSqlAlchemyStatementBuilder(self.session, self.model)
+
+    def for_repo[R](self, repo_class: type[R]) -> R:
+        """Return a typed entity repository sharing this session and factory."""
+        if self._factory is None:
+            raise RuntimeError("for_repo() requires an AsyncRepositoryFactory")
+        return self._factory.get_repository(repo_class)

sqlphilosophy/audit/__init__.py

@@ -0,0 +1,3 @@
+"""SQLAlchemy audit mixins and listeners."""
+
+__all__: list[str] = []

sqlphilosophy/audit/context.py

@@ -0,0 +1,37 @@
+"""Request-scoped audit actor context."""
+
+from __future__ import annotations
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AuditContext:
+    actor_id: int | str | None = None
+
+
+_audit_context: ContextVar[AuditContext | None] = ContextVar("audit_context", default=None)
+
+
+def get_audit_context() -> AuditContext | None:
+    return _audit_context.get()
+
+
+def get_audit_actor_id() -> int | str | None:
+    ctx = get_audit_context()
+    return ctx.actor_id if ctx is not None else None
+
+
+def set_audit_context(ctx: AuditContext | None) -> None:
+    _audit_context.set(ctx)
+
+
+@contextmanager
+def audit_context(actor_id: int | str | None) -> Iterator[None]:
+    token = _audit_context.set(AuditContext(actor_id=actor_id))
+    try:
+        yield
+    finally:
+        _audit_context.reset(token)

sqlphilosophy/audit/fields.py

@@ -0,0 +1,24 @@
+"""Logical audit column names for listener stamping."""
+
+from __future__ import annotations
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AuditColumns:
+    created: str = "created_on"
+    updated: str = "updated_on"
+    created_by: str = "created_by_id"
+    updated_by: str = "updated_by_id"
+    deleted: str = "deleted_on"
+    deleted_by: str = "deleted_by_id"
+
+    @classmethod
+    def for_model(cls, model_type: type) -> AuditColumns:
+        return cls()
+
+
+def is_audit_model(instance: object) -> bool:
+    from sqlphilosophy.audit.model import AuditMixin
+
+    return isinstance(instance, AuditMixin)

sqlphilosophy/audit/listener.py

@@ -0,0 +1,99 @@
+"""SQLAlchemy audit listeners gated on :class:`AuditMixin`."""
+
+from __future__ import annotations
+from abc import ABC
+from datetime import datetime
+from datetime import timezone
+from typing import Any
+from sqlalchemy import event
+from sqlalchemy.orm import Mapper
+from sqlphilosophy.audit.context import get_audit_context
+from sqlphilosophy.audit.fields import AuditColumns
+from sqlphilosophy.audit.fields import is_audit_model
+from sqlphilosophy.audit.model import AuditMixin
+
+_ATTACHED = False
+
+
+class AuditListener(ABC):
+    def now(self) -> datetime:
+        return datetime.now(timezone.utc)
+
+    def _actor(self) -> int | str | None:
+        ctx = get_audit_context()
+        return ctx.actor_id if ctx is not None else None
+
+    def _has_attr(self, target: object, name: str) -> bool:
+        return hasattr(type(target), name)
+
+    def _set_if_empty(self, target: object, name: str, value: object) -> None:
+        if not self._has_attr(target, name):
+            return
+        current = getattr(target, name)
+        if current is None or current == "":
+            setattr(target, name, value)
+
+    def _set(self, target: object, name: str, value: object) -> None:
+        if self._has_attr(target, name):
+            setattr(target, name, value)
+
+    def stamp_on_insert(self, target: AuditMixin) -> None:
+        fields = AuditColumns.for_model(type(target))
+        ts = self.now()
+        self._set_if_empty(target, fields.created, ts)
+        self._set_if_empty(target, fields.updated, ts)
+        actor = self._actor()
+        if actor is not None:
+            self._set_if_empty(target, fields.created_by, actor)
+            self._set_if_empty(target, fields.updated_by, actor)
+
+    def stamp_on_update(self, target: AuditMixin) -> None:
+        fields = AuditColumns.for_model(type(target))
+        if self._has_attr(target, fields.updated):
+            setattr(target, fields.updated, self.now())
+        actor = self._actor()
+        if actor is not None:
+            self._set(target, fields.updated_by, actor)
+
+    def stamp_on_soft_delete(self, target: AuditMixin, *, actor: int | str | None = None) -> None:
+        fields = AuditColumns.for_model(type(target))
+        self._set(target, fields.deleted, self.now())
+        resolved = actor if actor is not None else self._actor()
+        if resolved is not None:
+            self._set(target, fields.deleted_by, resolved)
+
+    def attach(self) -> None:
+        global _ATTACHED
+        if _ATTACHED:
+            return
+        listener = self
+
+        @event.listens_for(AuditMixin, "before_insert", propagate=True)
+        def _before_insert(mapper: Mapper[Any], connection: object, target: object) -> None:
+            if not is_audit_model(target):
+                return  # pragma: no cover
+            listener.stamp_on_insert(target)
+
+        @event.listens_for(AuditMixin, "before_update", propagate=True)
+        def _before_update(mapper: Mapper[Any], connection: object, target: object) -> None:
+            if not is_audit_model(target):
+                return  # pragma: no cover
+            listener.stamp_on_update(target)
+
+        _ATTACHED = True
+
+
+_default_listener = AuditListener()
+
+
+def get_audit_listener() -> AuditListener:
+    return _default_listener
+
+
+def configure_audit_listeners() -> None:
+    _default_listener.attach()
+
+
+def soft_delete(target: AuditMixin, *, actor: int | str | None = None) -> None:
+    """Stamp soft-delete columns via the configured audit listener."""
+    get_audit_listener().stamp_on_soft_delete(target, actor=actor)

sqlphilosophy/audit/model.py

@@ -0,0 +1,59 @@
+"""Abstract mixins that gate audit listener processing."""
+
+from __future__ import annotations
+from datetime import datetime
+from sqlalchemy import BigInteger
+from sqlalchemy import DateTime
+from sqlalchemy.orm import Mapped
+from sqlalchemy.orm import mapped_column
+
+
+class AuditMixin:
+    """Base marker for audit listener dispatch."""
+
+    __abstract__ = True
+
+
+class CreatedTimestampModel(AuditMixin):
+    """Tables with ``created_on`` only (outbox, audit events, invites)."""
+
+    __abstract__ = True
+
+    created_on: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class UpdatedTimestampModel(AuditMixin):
+    """Tables with ``updated_on`` only."""
+
+    __abstract__ = True
+
+    updated_on: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class TimestampModel(AuditMixin):
+    """Standard created/updated timestamp and actor audit columns."""
+
+    __abstract__ = True
+
+    created_on: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    updated_on: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    created_by_id: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+    updated_by_id: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+
+
+class SoftDeleteTimestampModel(TimestampModel):
+    """Timestamped entities that support soft delete."""
+
+    __abstract__ = True
+
+    deleted_on: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    deleted_by_id: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+
+
+class SoftDeleteModel(AuditMixin):
+    """Soft-delete columns without created/updated timestamps (e.g. Profile)."""
+
+    __abstract__ = True
+
+    deleted_on: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    deleted_by_id: Mapped[int | None] = mapped_column(BigInteger, nullable=True)