sqlarec 0.1.0__py3-none-any.whl

sqlarec/__init__.py

@@ -0,0 +1,27 @@
+"""A context-aware Active Record API for synchronous SQLAlchemy.
+
+Applications remain responsible for creating and registering a session, and for
+committing or rolling back transactions.
+"""
+
+from sqlarec.core import (
+    BaseModel,
+    ModelQuery,
+    ModelUpdate,
+    RowQuery,
+    RowUpdate,
+)
+from sqlarec.database import get_engine, init_engine, new_session
+
+__all__ = [
+    "BaseModel",
+    "ModelQuery",
+    "ModelUpdate",
+    "RowQuery",
+    "RowUpdate",
+    "get_engine",
+    "init_engine",
+    "new_session",
+]
+
+__version__ = "0.1.0"

sqlarec/core/__init__.py

@@ -0,0 +1,13 @@
+"""Core model and statement wrapper implementations."""
+
+from .base_model import BaseModel
+from .query import ModelQuery, RowQuery
+from .update import ModelUpdate, RowUpdate
+
+__all__ = [
+    "BaseModel",
+    "ModelQuery",
+    "ModelUpdate",
+    "RowQuery",
+    "RowUpdate",
+]

sqlarec/core/base_model.py

@@ -0,0 +1,244 @@
+"""Declarative base model with context-aware persistence helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any, ClassVar, Generic, Self, TypeVar, cast, overload
+
+from sqlalchemy import Integer, inspect, select, update
+from sqlalchemy import Sequence as SQLSequence
+from sqlalchemy.orm import DeclarativeBase, Session
+
+from sqlarec.core.query import ModelQuery, RowQuery, _ModelQueryProperty
+from sqlarec.core.update import Update
+from sqlarec.utils import generate_identifier
+
+ValueT = TypeVar("ValueT")
+
+
+class _ClassProperty(Generic[ValueT]):
+    """Read-only descriptor for a value computed from a class."""
+
+    def __init__(self, getter: Callable[[Any], ValueT]) -> None:
+        self.getter = getter
+
+    def __get__(
+        self,
+        instance: object | None,
+        owner: type[Any],
+    ) -> ValueT:
+        return self.getter(owner)
+
+
+class BaseModel(DeclarativeBase):
+    """Base for SQLAlchemy models with query and persistence conveniences.
+
+    Register a session provider before using model operations. Write helpers
+    flush changes but never commit, so the application retains control of the
+    transaction boundary.
+    """
+
+    __abstract__ = True
+
+    _session_provider: ClassVar[Callable[[], Session] | None] = None
+    query = _ModelQueryProperty()
+
+    @classmethod
+    def register_session_provider(cls, provider: Callable[[], Session]) -> None:
+        """Register the callback used to obtain the current session.
+
+        The provider is shared by every model that inherits from ``BaseModel``.
+
+        Args:
+            provider: Zero-argument callable that returns the current synchronous
+                SQLAlchemy session.
+        """
+        BaseModel._session_provider = provider
+
+    @_ClassProperty
+    def session(cls) -> Session:
+        """Return the current session supplied by the registered provider.
+
+        Raises:
+            RuntimeError: If no session provider has been registered.
+        """
+        provider = BaseModel._session_provider
+        if provider is None:
+            raise RuntimeError(
+                "No session provider registered. Call "
+                "BaseModel.register_session_provider() at app startup."
+            )
+        return provider()
+
+    @overload
+    @classmethod
+    def select(cls) -> ModelQuery[Self]: ...
+
+    @overload
+    @classmethod
+    def select(cls, *entities: Any) -> RowQuery: ...
+
+    @classmethod
+    def select(cls, *entities: Any) -> ModelQuery[Self] | RowQuery:
+        """Create an entity query or a row query for selected expressions."""
+        if entities:
+            return RowQuery(select(*entities), cls.session)
+        return ModelQuery(select(cls), cls.session)
+
+    @classmethod
+    def update(cls) -> Update:
+        """Create an immutable update wrapper for this model."""
+        return Update(update(cls), cls.session)
+
+    @classmethod
+    def create(cls, **values: Any) -> Self:
+        """Construct, add, and flush a model without committing.
+
+        A string-compatible single primary key receives a UUID hex identifier
+        when it has no supplied value, auto-increment behavior, or default.
+        """
+        if (
+            cls.has_one_primary_key()
+            and cls.get_primary_key_name() not in values
+            and not cls.is_auto_increment()
+            and not cls.has_primary_key_default()
+        ):
+            values[cls.get_primary_key_name()] = generate_identifier()
+        return cls.create_instance(**values)
+
+    @classmethod
+    def create_instance(cls, **values: Any) -> Self:
+        """Construct, add, and flush a model without generating an identifier."""
+        instance = cls(**values)
+        return instance.save()
+
+    def save(self) -> Self:
+        """Add and flush this model without committing the transaction."""
+        self.session.add(self)
+        self.session.flush()
+        return self
+
+    def delete(self) -> None:
+        """Delete and flush this model without committing the transaction."""
+        self.session.delete(self)
+        self.session.flush()
+
+    @classmethod
+    def get_by_pk(cls, value: Any) -> Self | None:
+        """Return the model with a primary-key identity, or ``None``."""
+        return cls.session.get(cls, value)
+
+    @classmethod
+    def exists(cls, value: Any) -> bool:
+        """Return whether a model exists for a primary-key identity."""
+        return cls.get_by_pk(value) is not None
+
+    @classmethod
+    def get_or_create(cls, **values: Any) -> Self:
+        """Return a matching model or create and flush a new one."""
+        primary_key_names = cls.get_primary_key_names()
+        if all(name in values for name in primary_key_names):
+            identity_values = tuple(values[name] for name in primary_key_names)
+            identity = (
+                identity_values[0] if len(identity_values) == 1 else identity_values
+            )
+            instance = cls.get_by_pk(identity)
+        else:
+            instance = cls.get_instance_by_keys(**values)
+        return cls.create(**values) if instance is None else instance
+
+    @classmethod
+    def all(cls) -> Sequence[Self]:
+        """Return every row mapped by this model."""
+        return cls.query.all()
+
+    @classmethod
+    def get_instance_by_keys(cls, **values: Any) -> Self | None:
+        """Return zero or one model matching mapped attribute values.
+
+        SQLAlchemy raises ``MultipleResultsFound`` when the supplied attributes
+        do not identify at most one row.
+        """
+        return cls.query.filter_by(**values).one_or_none()
+
+    @classmethod
+    def filter_by_keys(cls, **values: Any) -> Sequence[Self]:
+        """Return all models matching mapped attribute values."""
+        return cls.query.filter_by(**values).all()
+
+    def get_id(self) -> Any:
+        """Return the model's primary-key value or composite-key tuple."""
+        return self.get_primary_key_value()
+
+    def get_primary_key_value(self) -> Any:
+        """Return the primary-key value in mapper-defined column order."""
+        values = tuple(getattr(self, name) for name in self.get_primary_key_names())
+        return values[0] if len(values) == 1 else values
+
+    @classmethod
+    def get_primary_key_name(cls) -> str:
+        """Return the primary-key name for a single-key model.
+
+        Raises:
+            RuntimeError: If the model uses a composite primary key.
+        """
+        names = cls.get_primary_key_names()
+        if len(names) != 1:
+            raise RuntimeError(
+                f"{cls.__name__} must have exactly one primary key column"
+            )
+        return names[0]
+
+    @classmethod
+    def get_primary_key_names(cls) -> tuple[str, ...]:
+        """Return primary-key names in mapper-defined order."""
+        return tuple(cast(str, column.key) for column in inspect(cls).primary_key)
+
+    @classmethod
+    def has_one_primary_key(cls) -> bool:
+        """Return whether the model has one primary-key column."""
+        return len(inspect(cls).primary_key) == 1
+
+    @classmethod
+    def is_auto_increment(cls) -> bool:
+        """Return whether the single primary key uses integer auto-increment."""
+        if not cls.has_one_primary_key():
+            return False
+        primary_key = inspect(cls).primary_key[0]
+        return primary_key.autoincrement is True or (
+            primary_key.autoincrement == "auto"
+            and isinstance(primary_key.type, Integer)
+            and not primary_key.foreign_keys
+        )
+
+    @classmethod
+    def has_primary_key_default(cls) -> bool:
+        """Return whether the single primary key defines a client/server default."""
+        if not cls.has_one_primary_key():
+            return False
+        primary_key = inspect(cls).primary_key[0]
+        return primary_key.default is not None or primary_key.server_default is not None
+
+    @classmethod
+    def is_following_sequence(cls) -> bool:
+        """Return whether the single primary key uses a default or sequence."""
+        if not cls.has_one_primary_key():
+            return False
+        primary_key = inspect(cls).primary_key[0]
+        return primary_key.server_default is not None or isinstance(
+            primary_key.default,
+            SQLSequence,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return mapped column values keyed by column name."""
+        return {
+            column.key: getattr(self, column.key) for column in self.__table__.columns
+        }
+
+    def __repr__(self) -> str:
+        values = ", ".join(
+            f"{column.key}={getattr(self, column.key)!r}"
+            for column in self.__table__.columns
+        )
+        return f"{type(self).__name__}({values})"

sqlarec/core/query.py

@@ -0,0 +1,177 @@
+"""Immutable wrappers around SQLAlchemy select statements."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Generic, Self, TypeVar, cast
+
+from sqlalchemy import Select, select, union, union_all
+from sqlalchemy.engine import MappingResult, Result, Row, ScalarResult
+from sqlalchemy.orm import Session, aliased
+
+ModelT = TypeVar("ModelT")
+
+
+class Query:
+    """Build a select statement without mutating earlier query objects."""
+
+    def __init__(
+        self,
+        statement: Any,
+        session: Session,
+    ) -> None:
+        """Initialize a query for a statement and its execution session."""
+        self.statement = statement
+        self.session = session
+
+    def _new(self, statement: Any) -> Self:
+        return self.__class__(statement, self.session)
+
+    def where(self, *criteria: Any) -> Self:
+        """Return a query with SQL ``WHERE`` criteria applied."""
+        return self._new(self.statement.where(*criteria))
+
+    def filter_by(self, **kwargs: Any) -> Self:
+        """Return a query filtered by mapped attribute names."""
+        return self._new(self.statement.filter_by(**kwargs))
+
+    def order_by(self, *clauses: Any) -> Self:
+        """Return a query with SQL ``ORDER BY`` clauses applied."""
+        return self._new(self.statement.order_by(*clauses))
+
+    def group_by(self, *clauses: Any) -> Self:
+        """Return a query with SQL ``GROUP BY`` clauses applied."""
+        return self._new(self.statement.group_by(*clauses))
+
+    def having(self, *criteria: Any) -> Self:
+        """Return a query with SQL ``HAVING`` criteria applied."""
+        return self._new(self.statement.having(*criteria))
+
+    def join(self, target: Any, *props: Any, **kwargs: Any) -> Self:
+        """Return a query with an inner join applied."""
+        return self._new(self.statement.join(target, *props, **kwargs))
+
+    def outerjoin(self, target: Any, *props: Any, **kwargs: Any) -> Self:
+        """Return a query with a left outer join applied."""
+        return self._new(self.statement.outerjoin(target, *props, **kwargs))
+
+    def limit(self, limit: int | None) -> Self:
+        """Return a query limited to at most ``limit`` rows."""
+        return self._new(self.statement.limit(limit))
+
+    def offset(self, offset: int | None) -> Self:
+        """Return a query with a row offset applied."""
+        return self._new(self.statement.offset(offset))
+
+    def distinct(self, *expressions: Any) -> Self:
+        """Return a query with SQL ``DISTINCT`` applied."""
+        return self._new(self.statement.distinct(*expressions))
+
+    def options(self, *options: Any) -> Self:
+        """Return a query with SQLAlchemy ORM loader options applied."""
+        return self._new(self.statement.options(*options))
+
+    def union(self, *others: Query | Select[Any]) -> Self:
+        """Return a query that unions this statement with other statements."""
+        statements = [
+            other.statement if isinstance(other, Query) else other for other in others
+        ]
+        return self._new(union(self.statement, *statements))
+
+    def union_all(self, *others: Query | Select[Any]) -> Self:
+        """Return a query that unions all rows from the supplied statements."""
+        statements = [
+            other.statement if isinstance(other, Query) else other for other in others
+        ]
+        return self._new(union_all(self.statement, *statements))
+
+    def compile(self, *args: Any, **kwargs: Any) -> Any:
+        """Compile the wrapped statement with SQLAlchemy."""
+        return self.statement.compile(*args, **kwargs)
+
+
+class ModelQuery(Query, Generic[ModelT]):
+    """Execute a select statement and return mapped model instances."""
+
+    def _compound_query(
+        self,
+        operation: Any,
+        *others: Query | Select[Any],
+    ) -> Self:
+        entity = self.statement.column_descriptions[0]["entity"]
+        statements = [
+            other.statement if isinstance(other, Query) else other for other in others
+        ]
+        compound_subquery = operation(self.statement, *statements).subquery()
+        entity_alias = aliased(entity, compound_subquery)
+        return self.__class__(select(entity_alias), self.session)
+
+    def union(self, *others: Query | Select[Any]) -> Self:
+        """Return an entity query containing distinct rows from all statements."""
+        return self._compound_query(union, *others)
+
+    def union_all(self, *others: Query | Select[Any]) -> Self:
+        """Return an entity query containing every row from all statements."""
+        return self._compound_query(union_all, *others)
+
+    def execute(self) -> ScalarResult[ModelT]:
+        """Execute the statement and return its scalar result."""
+        return self.session.scalars(self.statement)
+
+    def all(self) -> Sequence[ModelT]:
+        """Return all matching model instances."""
+        return self.execute().all()
+
+    def first(self) -> ModelT | None:
+        """Return the first matching model, or ``None``."""
+        return self.session.scalars(self.statement.limit(1)).first()
+
+    def one(self) -> ModelT:
+        """Return exactly one model or raise a SQLAlchemy result error."""
+        return self.execute().one()
+
+    def one_or_none(self) -> ModelT | None:
+        """Return zero or one model or raise when multiple rows match."""
+        return self.execute().one_or_none()
+
+
+class RowQuery(Query):
+    """Execute a select statement and return SQLAlchemy rows."""
+
+    def execute(self) -> Result[Any]:
+        """Execute the statement and return its row result."""
+        return self.session.execute(self.statement)
+
+    def all(self) -> Sequence[Row[Any]]:
+        """Return all matching rows."""
+        return self.execute().all()
+
+    def first(self) -> Row[Any] | None:
+        """Return the first matching row, or ``None``."""
+        return self.session.execute(self.statement.limit(1)).first()
+
+    def one(self) -> Row[Any]:
+        """Return exactly one row or raise a SQLAlchemy result error."""
+        return self.execute().one()
+
+    def one_or_none(self) -> Row[Any] | None:
+        """Return zero or one row or raise when multiple rows match."""
+        return self.execute().one_or_none()
+
+    def mappings(self) -> MappingResult:
+        """Execute the statement and return mapping-style rows."""
+        return self.execute().mappings()
+
+
+class _ModelQueryProperty:
+    """Descriptor that creates a fresh model query on every access."""
+
+    def __get__(
+        self,
+        instance: object | None,
+        owner: type[ModelT],
+    ) -> ModelQuery[ModelT]:
+        return ModelQuery(
+            select(cast(Any, owner)),
+            cast(Any, owner).session,
+        )

sqlarec/core/update.py

@@ -0,0 +1,135 @@
+"""Immutable wrappers around SQLAlchemy update statements."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Generic, Self, TypeVar, cast, overload
+
+from sqlalchemy import Update as SQLUpdate
+from sqlalchemy import inspect
+from sqlalchemy.engine import CursorResult, MappingResult, Result, Row, ScalarResult
+from sqlalchemy.orm import Mapper, Session
+
+ModelT = TypeVar("ModelT")
+
+
+class UpdateBuilder:
+    """Build an update statement without mutating earlier wrapper objects."""
+
+    def __init__(self, statement: SQLUpdate, session: Session) -> None:
+        """Initialize a wrapper for a statement and its execution session."""
+        self.statement = statement
+        self.session = session
+
+    def _new(self, statement: SQLUpdate) -> Self:
+        return self.__class__(statement, self.session)
+
+    def where(self, *criteria: Any) -> Self:
+        """Return an update with SQL ``WHERE`` criteria applied."""
+        return self._new(self.statement.where(*criteria))
+
+    def values(self, *args: Any, **kwargs: Any) -> Self:
+        """Return an update with new column values applied."""
+        return self._new(self.statement.values(*args, **kwargs))
+
+    def execution_options(self, **kwargs: Any) -> Self:
+        """Return an update with SQLAlchemy execution options applied."""
+        return self._new(self.statement.execution_options(**kwargs))
+
+    def compile(self, *args: Any, **kwargs: Any) -> Any:
+        """Compile the wrapped statement with SQLAlchemy."""
+        return self.statement.compile(*args, **kwargs)
+
+
+class Update(UpdateBuilder):
+    """Execute an update or choose a typed wrapper for returned values."""
+
+    @overload
+    def returning(
+        self,
+        entity: type[ModelT],
+        /,
+        **kwargs: Any,
+    ) -> ModelUpdate[ModelT]: ...
+
+    @overload
+    def returning(
+        self,
+        column: Any,
+        /,
+        *columns: Any,
+        **kwargs: Any,
+    ) -> RowUpdate: ...
+
+    def returning(
+        self,
+        entity_or_column: Any,
+        /,
+        *columns: Any,
+        **kwargs: Any,
+    ) -> ModelUpdate[Any] | RowUpdate:
+        """Return an entity or row update based on the returning expression."""
+        expressions = (entity_or_column, *columns)
+        statement = self.statement.returning(*expressions, **kwargs)
+        if len(expressions) == 1 and isinstance(
+            inspect(entity_or_column, raiseerr=False),
+            Mapper,
+        ):
+            return ModelUpdate(statement, self.session)
+        return RowUpdate(statement, self.session)
+
+    def execute(self) -> CursorResult[Any]:
+        """Execute the update and return its cursor result."""
+        return cast(CursorResult[Any], self.session.execute(self.statement))
+
+
+class ModelUpdate(UpdateBuilder, Generic[ModelT]):
+    """Execute an update that returns mapped model instances."""
+
+    def execute(self) -> ScalarResult[ModelT]:
+        """Execute the update and return its scalar result."""
+        return self.session.scalars(self.statement)
+
+    def all(self) -> Sequence[ModelT]:
+        """Return all updated model instances."""
+        return self.execute().all()
+
+    def first(self) -> ModelT | None:
+        """Return the first updated model, or ``None``."""
+        return self.execute().first()
+
+    def one(self) -> ModelT:
+        """Return exactly one updated model."""
+        return self.execute().one()
+
+    def one_or_none(self) -> ModelT | None:
+        """Return zero or one updated model."""
+        return self.execute().one_or_none()
+
+
+class RowUpdate(UpdateBuilder):
+    """Execute an update that returns SQLAlchemy rows."""
+
+    def execute(self) -> Result[Any]:
+        """Execute the update and return its row result."""
+        return self.session.execute(self.statement)
+
+    def all(self) -> Sequence[Row[Any]]:
+        """Return all rows produced by the update."""
+        return self.execute().all()
+
+    def first(self) -> Row[Any] | None:
+        """Return the first produced row, or ``None``."""
+        return self.execute().first()
+
+    def one(self) -> Row[Any]:
+        """Return exactly one produced row."""
+        return self.execute().one()
+
+    def one_or_none(self) -> Row[Any] | None:
+        """Return zero or one produced row."""
+        return self.execute().one_or_none()
+
+    def mappings(self) -> MappingResult:
+        """Execute the update and return mapping-style rows."""
+        return self.execute().mappings()

sqlarec/database.py

@@ -0,0 +1,60 @@
+"""Engine and session helpers for synchronous SQLAlchemy applications."""
+
+from typing import Any
+
+from sqlalchemy import create_engine
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session, sessionmaker
+
+_engine: Engine | None = None
+
+
+def init_engine(database_uri: str, **kwargs: Any) -> Engine:
+    """Create and register the package's default SQLAlchemy engine.
+
+    Args:
+        database_uri: SQLAlchemy database URL.
+        **kwargs: Additional keyword arguments passed to
+            :func:`sqlalchemy.create_engine`.
+
+    Returns:
+        The newly created synchronous engine.
+
+    Note:
+        Calling this function replaces the registered default engine. Existing
+        sessions continue to use the engine to which they were originally bound.
+    """
+    global _engine
+    _engine = create_engine(database_uri, **kwargs)
+    return _engine
+
+
+def get_engine() -> Engine:
+    """Return the registered default engine.
+
+    Raises:
+        RuntimeError: If :func:`init_engine` has not been called.
+    """
+    if _engine is None:
+        raise RuntimeError("Database engine not initialized; call init_engine() first")
+    return _engine
+
+
+def new_session(engine: Engine | None = None) -> Session:
+    """Create a synchronous session without opening a transaction eagerly.
+
+    Args:
+        engine: Engine to bind. The registered default engine is used when this
+            argument is omitted.
+
+    Returns:
+        A session configured with ``autoflush=False`` and
+        ``expire_on_commit=False``.
+    """
+    bind = get_engine() if engine is None else engine
+    factory = sessionmaker(
+        bind=bind,
+        autoflush=False,
+        expire_on_commit=False,
+    )
+    return factory()

sqlarec/py.typed

@@ -0,0 +1 @@
+

sqlarec/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Internal helpers shared by sqlarec modules."""
+
+from .identifiers import generate_identifier
+
+__all__ = ["generate_identifier"]

sqlarec/utils/identifiers.py

@@ -0,0 +1,8 @@
+"""Identifier generation helpers."""
+
+from uuid import uuid4
+
+
+def generate_identifier() -> str:
+    """Return a random UUID encoded as 32 lowercase hexadecimal characters."""
+    return uuid4().hex

sqlarec-0.1.0.dist-info/METADATA

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: sqlarec
+Version: 0.1.0
+Summary: A context-aware Active Record API for synchronous SQLAlchemy 2.
+Author: Hamza Senhaji Rhazi
+Keywords: active-record,orm,sql,sqlalchemy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: sqlalchemy<3,>=2.0
+Description-Content-Type: text/markdown
+
+# sqlarec
+
+`sqlarec` adds a small, context-aware Active Record API on top of synchronous
+SQLAlchemy 2. It keeps model operations concise without forcing your application
+to pass a `Session` through every service and repository call.
+
+It is designed for applications that want concise model operations:
+
+```python
+user = User.query.where(User.email == "hamza@example.com").one_or_none()
+users = User.query.order_by(User.name).all()
+user = User.create(name="Hamza", email="hamza@example.com")
+```
+
+## Why sqlarec
+
+Regular SQLAlchemy makes session ownership explicit, but passing the same session
+through every layer can become repetitive:
+
+```python
+def find_user(session, email):
+    return session.scalars(select(User).where(User.email == email)).one_or_none()
+```
+
+`sqlarec` lets your application register a session-provider callback once. Models
+resolve the current session only when they execute an operation:
+
+```python
+user = User.query.where(User.email == email).one_or_none()
+```
+
+This separates two responsibilities:
+
+- Your application creates the session and decides when to commit, roll back, and
+  close it.
+- Your models use the current session without receiving it as an argument on
+  every call.
+
+Register the provider once in your application setup, away from model and
+business logic. A command runner, background-job worker, or web middleware can
+then create the current session and manage its transaction lifecycle. Models use
+that session through `User.query`, `User.create()`, or `User.session` without
+requiring every function to accept and forward a session argument.
+
+The following framework-neutral middleware sketch shows the principle:
+
+```python
+from contextvars import ContextVar
+
+from sqlalchemy.orm import Session
+
+from sqlarec import BaseModel, new_session
+
+current_session = ContextVar[Session]("current_session")
+
+# Register this once during application startup.
+BaseModel.register_session_provider(current_session.get)
+
+
+def database_middleware(handler):
+    def wrapped(request):
+        session = new_session()
+        token = current_session.set(session)
+        try:
+            response = handler(request)
+            session.commit()
+            return response
+        except Exception:
+            session.rollback()
+            raise
+        finally:
+            current_session.reset(token)
+            session.close()
+
+    return wrapped
+```
+
+Code executed inside that middleware can use a model from anywhere in the
+application:
+
+```python
+@database_middleware
+def get_user(request):
+    return User.query.where(User.email == request.email).one_or_none()
+```
+
+The handler does not receive a session. `User.query` resolves the session bound
+by the middleware to the current execution context, so concurrent requests do
+not share sessions.
+
+As a result, business code remains focused on model operations while the
+application retains an explicit and reliable transaction boundary. `sqlarec`
+does not depend on a web framework and never commits inside model methods.
+
+## Requirements
+
+- Python 3.11 or later
+- SQLAlchemy 2
+- A synchronous SQLAlchemy `Session`
+- [uv](https://docs.astral.sh/uv/) for development
+
+## Install the package
+
+Install the project and development tools:
+
+```bash
+uv sync
+```
+
+Install only runtime dependencies:
+
+```bash
+uv sync --no-dev
+```
+
+## Create your first model
+
+Models inherit from `BaseModel` and use standard SQLAlchemy mapped columns:
+
+```python
+from sqlalchemy import Boolean, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from sqlarec import BaseModel, init_engine, new_session
+
+
+class User(BaseModel):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(100))
+    email: Mapped[str] = mapped_column(String(255), unique=True)
+    active: Mapped[bool] = mapped_column(Boolean, default=True)
+
+
+engine = init_engine("sqlite:///:memory:")
+BaseModel.metadata.create_all(engine)
+
+session = new_session()
+BaseModel.register_session_provider(lambda: session)
+
+User.create(name="Hamza", email="hamza@example.com")
+session.commit()
+
+user = User.query.one()
+print(user.email)
+```
+
+Expected output:
+
+```text
+hamza@example.com
+```
+
+`BaseModel` inherits from SQLAlchemy's `DeclarativeBase`. Relationships,
+constraints, indexes, and mapper configuration continue to use normal SQLAlchemy
+APIs.
+
+## Register the current session
+
+Register a zero-argument callback that returns the session your application wants
+models to use:
+
+```python
+from sqlarec import BaseModel
+
+
+def get_session():
+    return session
+
+
+BaseModel.register_session_provider(get_session)
+```
+
+Register the provider during application startup, not separately for every
+concurrent request. The provider itself can retrieve a request-, job-, or
+context-local session:
+
+```python
+from contextvars import ContextVar
+
+from sqlalchemy.orm import Session
+
+from sqlarec import BaseModel
+
+current_session: ContextVar[Session] = ContextVar("current_session")
+
+BaseModel.register_session_provider(current_session.get)
+```
+
+Middleware can set and reset this context variable around each request. This
+keeps concurrent request sessions isolated while allowing model calls to resolve
+the correct session. Only synchronous sessions are supported.
+
+## Query models and rows
+
+`Model.query` and `Model.select()` return immutable `ModelQuery` wrappers. Their
+result methods return mapped instances:
+
+```python
+users = User.query.all()
+user = User.query.where(User.email == "hamza@example.com").one_or_none()
+active = User.query.filter_by(active=True).order_by(User.name).limit(20).all()
+```
+
+Passing columns to `Model.select()` returns a `RowQuery`:
+
+```python
+rows = User.select(User.id, User.email).order_by(User.id).all()
+mappings = User.select(User.id, User.email).mappings().all()
+```
+
+The result behavior remains explicit:
+
+```text
+User.query.all()                       -> Sequence[User]
+User.select().all()                    -> Sequence[User]
+User.select(User.id, User.email).all() -> Sequence[Row]
+```
+
+Query builders include `where()`, `filter_by()`, `order_by()`, `group_by()`,
+`having()`, `join()`, `outerjoin()`, `limit()`, `offset()`, `distinct()`,
+`options()`, `union()`, and `union_all()`.
+
+## Create, update, and delete models
+
+Model writes flush the current session but never commit:
+
+```python
+user = User.create(name="Hamza", email="hamza@example.com")
+
+user.name = "Hamza S."
+user.save()
+
+User.update().where(User.active.is_(False)).values(active=True).execute()
+
+user.delete()
+session.commit()
+```
+
+Keeping the transaction boundary outside model methods lets an application commit
+or roll back a complete unit of work atomically.
+
+Single primary keys support direct lookup:
+
+```python
+user = User.get_by_pk(42)
+exists = User.exists(42)
+```
+
+String primary keys without a Python or database default receive a generated UUID
+hex value. Composite primary-key lookup accepts a tuple in mapper-defined key
+order.
+
+## Use SQLAlchemy directly when needed
+
+Every query and update wrapper exposes its underlying SQLAlchemy statement:
+
+```python
+query = User.query.where(User.active.is_(True))
+statement = query.statement
+```
+
+Use the registered session for operations the wrappers do not cover:
+
+```python
+result = User.session.execute(custom_statement)
+```
+
+`sqlarec` is an ergonomic layer, not a replacement for SQLAlchemy.
+
+## Develop the library
+
+```text
+sqlarec/
+├── src/sqlarec/
+│   ├── __init__.py
+│   ├── database.py
+│   ├── core/
+│   │   ├── base_model.py
+│   │   ├── query.py
+│   │   └── update.py
+│   └── utils/
+│       └── identifiers.py
+├── tests/
+├── Makefile
+├── pyproject.toml
+└── uv.lock
+```
+
+| Command               | Purpose                                       |
+| --------------------- | --------------------------------------------- |
+| `make install`      | Install runtime and development dependencies. |
+| `make install-prod` | Install runtime dependencies only.            |
+| `make test`         | Run pytest.                                   |
+| `make lint`         | Check source and tests with Ruff.             |
+| `make typecheck`    | Check package types with mypy.                |
+| `make format`       | Format source and tests with Ruff.            |
+| `make clean`        | Remove Python, pytest, and Ruff caches.       |
+
+## Current limitations
+
+- You must register a session provider before model operations.
+- Only synchronous SQLAlchemy sessions are supported.
+- Query wrappers cover common operations; use the underlying statement for
+  advanced SQLAlchemy features.

sqlarec-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+sqlarec/__init__.py,sha256=cLfw8P6tujMFM8n5YxFSTPJyIzl3d9SZb5-MBOSo1a0,545
+sqlarec/database.py,sha256=fs-xXs8WRGGJ48gNnpzCHkZbOkPALE3ic8R5TxsGl3U,1727
+sqlarec/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+sqlarec/core/__init__.py,sha256=sOVhOV2IBnItyziRM3Zex_OXFej0FhVfjVZehmMANbE,276
+sqlarec/core/base_model.py,sha256=F7i1z1qqGTLAo4zaUKJ0Hac2EMWK0VfzNub8roIakQs,8710
+sqlarec/core/query.py,sha256=-jdJAeiyb3_5otUpr0J1yMhw1lHURXUFY-_wMOOPlz4,6708
+sqlarec/core/update.py,sha256=Q7DfdcDOuCVbStOSWCR8KD6WkSsfo7W_8gT1Z-W9P94,4481
+sqlarec/utils/__init__.py,sha256=A52FzxKyUHOMDYL1lVAZk20LvHBjArBqvyoZ45qlMqE,131
+sqlarec/utils/identifiers.py,sha256=bPH7JwPiIj-gZZE6Do_BZGuUXx_cobrMDAFXD74FUZs,199
+sqlarec-0.1.0.dist-info/METADATA,sha256=eA_LZZ91UMAiUA7HS3sv_gcS-ovnSZZBku4lmoGE8yk,9296
+sqlarec-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+sqlarec-0.1.0.dist-info/RECORD,,

sqlarec-0.1.0.dist-info/WHEEL

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