ormate 0.1.0__py3-none-any.whl

ormate/__init__.py

@@ -0,0 +1,12 @@
+from .adapters import SQLAlchemyAdapter, SQLModelAdapter, StorageAdapter
+from .repository import ModelRepository
+from .sqlalchemy.database import AsyncDatabase, Database
+
+__all__ = [
+    "AsyncDatabase",
+    "Database",
+    "ModelRepository",
+    "SQLAlchemyAdapter",
+    "SQLModelAdapter",
+    "StorageAdapter",
+]

ormate/adapters/__init__.py

@@ -0,0 +1,5 @@
+from .base import StorageAdapter
+from .sqlalchemy import SQLAlchemyAdapter
+from .sqlmodel import SQLModelAdapter
+
+__all__ = ["SQLAlchemyAdapter", "SQLModelAdapter", "StorageAdapter"]

ormate/adapters/base.py

@@ -0,0 +1,35 @@
+from collections.abc import Mapping, Sequence
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class StorageAdapter(Protocol):
+    """Backend contract used by ModelRepository."""
+
+    def storage_name(self, model: type[Any]) -> str: ...
+
+    async def create(self, model: type[Any], items: Sequence[Mapping[str, Any]]) -> list[Any]: ...
+
+    async def read(
+        self,
+        model: type[Any],
+        query: Any = None,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        statement: Any = None,
+    ) -> list[Any]: ...
+
+    async def update(self, model: type[Any], query: Any, values: Mapping[str, Any]) -> list[Any]: ...
+
+    async def delete(self, model: type[Any], query: Any) -> list[Any]: ...
+
+    async def count(self, model: type[Any], query: Any = None, *, statement: Any = None) -> int: ...
+
+    async def exists(self, model: type[Any], query: Any = None) -> bool: ...
+
+    def primary_key_query(self, model: type[Any], primary_key: Any) -> Any: ...
+
+    def primary_keys_query(self, model: type[Any], primary_keys: Sequence[Any]) -> Any: ...
+
+    async def execute(self, statement: Any, params: Any = None, **kwargs: Any) -> Any: ...

ormate/adapters/elasticsearch.py

@@ -0,0 +1,133 @@
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+class ElasticsearchAdapter:
+    """Async Elasticsearch adapter using native Query DSL dictionaries."""
+
+    def __init__(self, client: Any, *, refresh: bool | str = False, default_size: int = 1000) -> None:
+        if default_size < 1:
+            raise ValueError("default_size must be greater than zero")
+        self.client = client
+        self.refresh = refresh
+        self.default_size = default_size
+
+    def storage_name(self, model: type[Any]) -> str:
+        index_name = getattr(model, "index_name", None)
+        if not isinstance(index_name, str) or not index_name:
+            raise TypeError("Elasticsearch document model must define a non-empty index_name")
+        return index_name
+
+    def _document(self, model: type[Any], values: Mapping[str, Any]) -> Any:
+        validator = getattr(model, "model_validate", None)
+        if not callable(validator):
+            raise TypeError("Elasticsearch document model must provide model_validate()")
+        return validator(values)
+
+    def _source(self, document: Any) -> dict[str, Any]:
+        serializer = getattr(document, "document_source", None)
+        if not callable(serializer):
+            raise TypeError("Elasticsearch document must provide document_source()")
+        return dict(serializer())
+
+    def _from_hit(self, model: type[Any], hit: Mapping[str, Any]) -> Any:
+        factory = getattr(model, "from_hit", None)
+        if not callable(factory):
+            raise TypeError("Elasticsearch document model must provide from_hit()")
+        return factory(dict(hit))
+
+    def primary_key_query(self, model: type[Any], primary_key: Any) -> dict[str, Any]:
+        return {"ids": {"values": [str(primary_key)]}}
+
+    def primary_keys_query(self, model: type[Any], primary_keys: Sequence[Any]) -> dict[str, Any]:
+        return {"ids": {"values": [str(primary_key) for primary_key in primary_keys]}}
+
+    async def create(self, model: type[Any], items: Sequence[Mapping[str, Any]]) -> list[Any]:
+        index_name = self.storage_name(model)
+        results = []
+        for values in items:
+            document = self._document(model, values)
+            response = await self.client.index(
+                index=index_name,
+                id=getattr(document, "id", None),
+                document=self._source(document),
+                refresh=self.refresh,
+            )
+            result_values = {"id": response.get("_id"), **self._source(document)}
+            results.append(self._document(model, result_values))
+        return results
+
+    async def read(
+        self,
+        model: type[Any],
+        query: Any = None,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        statement: Any = None,
+    ) -> list[Any]:
+        if statement is not None and not isinstance(statement, Mapping):
+            raise TypeError("Elasticsearch statement must be a search keyword mapping")
+        search_options = dict(statement or {})
+        search_options.setdefault("query", query or {"match_all": {}})
+        search_options.setdefault("from_", offset or 0)
+        search_options.setdefault("size", limit if limit is not None else self.default_size)
+        response = await self.client.search(index=self.storage_name(model), **search_options)
+        return [self._from_hit(model, hit) for hit in response["hits"]["hits"]]
+
+    async def update(self, model: type[Any], query: Any, values: Mapping[str, Any]) -> list[Any]:
+        documents = await self.read(model, query)
+        index_name = self.storage_name(model)
+        results = []
+        for document in documents:
+            document_id = getattr(document, "id", None)
+            if document_id is None:
+                continue
+            await self.client.update(
+                index=index_name,
+                id=document_id,
+                doc=dict(values),
+                refresh=self.refresh,
+            )
+            merged = {"id": document_id, **self._source(document), **values}
+            results.append(self._document(model, merged))
+        return results
+
+    async def delete(self, model: type[Any], query: Any) -> list[Any]:
+        documents = await self.read(model, query)
+        index_name = self.storage_name(model)
+        for document in documents:
+            document_id = getattr(document, "id", None)
+            if document_id is not None:
+                await self.client.delete(index=index_name, id=document_id, refresh=self.refresh)
+        return documents
+
+    async def count(self, model: type[Any], query: Any = None, *, statement: Any = None) -> int:
+        if statement is not None:
+            raise TypeError("Elasticsearch count does not accept a statement; pass Query DSL through query")
+        response = await self.client.count(index=self.storage_name(model), query=query or {"match_all": {}})
+        return int(response["count"])
+
+    async def exists(self, model: type[Any], query: Any = None) -> bool:
+        return await self.count(model, query) > 0
+
+    async def execute(self, statement: Any, params: Any = None, **kwargs: Any) -> Any:
+        if not isinstance(statement, str):
+            raise TypeError("Elasticsearch native execute statement must be a client method name")
+        method = getattr(self.client, statement, None)
+        if not callable(method):
+            raise ValueError(f"Unknown Elasticsearch client method: {statement}")
+        call_options = dict(params or {})
+        call_options.update(kwargs)
+        return await method(**call_options)
+
+    async def search(self, model: type[Any], query: Mapping[str, Any], **kwargs: Any) -> Any:
+        return await self.client.search(index=self.storage_name(model), query=query, **kwargs)
+
+    async def aggregate(self, model: type[Any], aggregations: Mapping[str, Any], query: Any = None) -> Any:
+        return await self.client.search(
+            index=self.storage_name(model),
+            query=query or {"match_all": {}},
+            aggregations=aggregations,
+            size=0,
+        )

ormate/adapters/sqlalchemy.py

@@ -0,0 +1,147 @@
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from sqlalchemy import Select, and_, false, func, inspect, or_, select
+from sqlalchemy.engine import Result
+from sqlalchemy.orm import Session
+from sqlalchemy.sql import Executable
+
+from ormate.sqlalchemy.database import AsyncDatabase, DatabaseLike, EngineLike, ensure_database
+
+
+class SQLAlchemyAdapter:
+    """Storage adapter for SQLAlchemy Declarative and SQLModel table models."""
+
+    def __init__(self, database: EngineLike) -> None:
+        self.database: DatabaseLike = ensure_database(database)
+
+    def select(self, model: type[Any]) -> Select[tuple[Any]]:
+        return select(model)
+
+    def _mapper(self, model: type[Any]) -> Any:
+        mapper = inspect(model)
+        if mapper is None:
+            raise TypeError(f"{model!r} is not a mapped SQLAlchemy model")
+        return mapper
+
+    def storage_name(self, model: type[Any]) -> str:
+        return str(self._mapper(model).local_table.name)
+
+    def primary_key_query(self, model: type[Any], primary_key: Any) -> Any:
+        primary_keys = tuple(self._mapper(model).primary_key)
+        if len(primary_keys) == 1:
+            values = (primary_key,)
+        elif isinstance(primary_key, Mapping):
+            try:
+                values = tuple(primary_key[column.key] for column in primary_keys)
+            except KeyError as exc:
+                raise ValueError(f"Missing composite primary-key field: {exc.args[0]}") from exc
+        elif isinstance(primary_key, tuple) and len(primary_key) == len(primary_keys):
+            values = primary_key
+        else:
+            raise ValueError("Composite primary keys require a mapping or a tuple with one value per key")
+        return and_(*(column == value for column, value in zip(primary_keys, values, strict=True)))
+
+    def primary_keys_query(self, model: type[Any], primary_keys: Sequence[Any]) -> Any:
+        if not primary_keys:
+            return false()
+        mapped_keys = tuple(self._mapper(model).primary_key)
+        if len(mapped_keys) == 1:
+            return mapped_keys[0].in_(primary_keys)
+        return or_(*(self.primary_key_query(model, primary_key) for primary_key in primary_keys))
+
+    async def create(self, model: type[Any], items: Sequence[Mapping[str, Any]]) -> list[Any]:
+        def operation(session: Session) -> list[Any]:
+            objects = [model(**values) for values in items]
+            session.add_all(objects)
+            session.flush()
+            for obj in objects:
+                session.refresh(obj)
+            return objects
+
+        return await self.database.async_run(operation)
+
+    async def read(
+        self,
+        model: type[Any],
+        query: Any = None,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        statement: Select[Any] | None = None,
+    ) -> list[Any]:
+        stmt = statement if statement is not None else self.select(model)
+        if query is not None:
+            stmt = stmt.where(query)
+        if offset is not None:
+            stmt = stmt.offset(offset)
+        if limit is not None:
+            stmt = stmt.limit(limit)
+
+        def operation(session: Session) -> list[Any]:
+            return list(session.scalars(stmt).all())
+
+        return await self.database.async_run(operation)
+
+    async def update(self, model: type[Any], query: Any, values: Mapping[str, Any]) -> list[Any]:
+        mapper = self._mapper(model)
+        mapped_fields = {attribute.key for attribute in mapper.column_attrs}
+
+        def operation(session: Session) -> list[Any]:
+            objects = list(session.scalars(self.select(model).where(query)).all())
+            for obj in objects:
+                for key, value in values.items():
+                    if key in mapped_fields:
+                        setattr(obj, key, value)
+            session.flush()
+            for obj in objects:
+                session.refresh(obj)
+            return objects
+
+        return await self.database.async_run(operation)
+
+    async def delete(self, model: type[Any], query: Any) -> list[Any]:
+        def operation(session: Session) -> list[Any]:
+            objects = list(session.scalars(self.select(model).where(query)).all())
+            for obj in objects:
+                session.delete(obj)
+            session.flush()
+            return objects
+
+        return await self.database.async_run(operation)
+
+    async def count(self, model: type[Any], query: Any = None, *, statement: Select[Any] | None = None) -> int:
+        stmt = statement if statement is not None else self.select(model)
+        if query is not None:
+            stmt = stmt.where(query)
+
+        def operation(session: Session) -> int:
+            count_statement = select(func.count()).select_from(stmt.order_by(None).subquery())
+            return int(session.scalar(count_statement) or 0)
+
+        return await self.database.async_run(operation)
+
+    async def exists(self, model: type[Any], query: Any = None) -> bool:
+        statement = select(1).select_from(model)
+        if query is not None:
+            statement = statement.where(query)
+        statement = statement.limit(1)
+
+        def operation(session: Session) -> bool:
+            return session.scalar(statement) is not None
+
+        return await self.database.async_run(operation)
+
+    async def execute(
+        self,
+        statement: Executable,
+        params: Mapping[str, Any] | Sequence[Mapping[str, Any]] | None = None,
+        **kwargs: Any,
+    ) -> Result[Any]:
+        def operation(session: Session) -> Result[Any]:
+            return session.execute(statement, params=params, **kwargs)
+
+        if isinstance(self.database, AsyncDatabase):
+            async with self.database.session_generator() as session:
+                return await session.execute(statement, params=params, **kwargs)
+        return await self.database.async_run(operation)

ormate/adapters/sqlmodel.py

@@ -0,0 +1,6 @@
+from .sqlalchemy import SQLAlchemyAdapter
+
+
+class SQLModelAdapter(SQLAlchemyAdapter):
+    """Semantic SQLModel adapter backed entirely by SQLAlchemy behavior."""
+

ormate/elasticsearch/__init__.py

@@ -0,0 +1,12 @@
+try:
+    import elasticsearch as _elasticsearch  # noqa: F401
+    import pydantic as _pydantic  # noqa: F401
+except ImportError as exc:
+    raise ImportError("Elasticsearch support requires 'ormate[elasticsearch]'.") from exc
+
+from ormate.adapters.elasticsearch import ElasticsearchAdapter
+
+from .document import ElasticsearchDocument
+
+__all__ = ["ElasticsearchAdapter", "ElasticsearchDocument"]
+

ormate/elasticsearch/document.py

@@ -0,0 +1,20 @@
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ElasticsearchDocument(BaseModel):
+    """Base model for Elasticsearch `_source` documents."""
+
+    model_config = ConfigDict(extra="allow")
+
+    index_name: ClassVar[str]
+    id: str | None = None
+
+    def document_source(self) -> dict[str, Any]:
+        return self.model_dump(exclude={"id"}, exclude_none=True)
+
+    @classmethod
+    def from_hit(cls, hit: dict[str, Any]) -> "ElasticsearchDocument":
+        return cls.model_validate({"id": hit.get("_id"), **hit.get("_source", {})})
+

ormate/protocols.py

@@ -0,0 +1,17 @@
+from collections.abc import Mapping, Sequence
+from typing import Any, Protocol, runtime_checkable
+
+ExecuteParams = Mapping[str, Any] | Sequence[Mapping[str, Any]]
+
+
+@runtime_checkable
+class DumpableModel(Protocol):
+    def model_dump(self, *, exclude_unset: bool = ...) -> dict[str, Any]: ...
+
+
+class ValidatableModel(Protocol):
+    @classmethod
+    def model_validate(cls, obj: Any, *, from_attributes: bool = ...) -> Any: ...
+
+
+type ModelInput = Mapping[str, Any] | DumpableModel

ormate/py.typed

@@ -0,0 +1 @@
+

ormate/repository.py

@@ -0,0 +1,142 @@
+from collections.abc import Mapping, Sequence
+from typing import Any, cast
+
+from .adapters.base import StorageAdapter
+from .protocols import DumpableModel
+
+
+class ModelRepository[TableModel, ReadModel]:
+    """Backend-independent repository with separate write and read models."""
+
+    def __init__(
+        self,
+        adapter: StorageAdapter,
+        model: type[TableModel],
+        read_model: type[ReadModel] | None = None,
+    ) -> None:
+        if not isinstance(adapter, StorageAdapter):
+            raise TypeError("adapter must implement StorageAdapter")
+        self.adapter = adapter
+        self.model = model
+        self.read_model = read_model
+
+    @property
+    def storage_name(self) -> str:
+        return self.adapter.storage_name(self.model)
+
+    def to_dict(self, item: Mapping[str, Any] | DumpableModel) -> dict[str, Any]:
+        if isinstance(item, Mapping):
+            return dict(item)
+        if isinstance(item, DumpableModel):
+            return item.model_dump(exclude_unset=True)
+        raise TypeError(f"Expected a mapping or model_dump()-compatible object, got {type(item).__name__}")
+
+    def encode_for_storage(self, values: dict[str, Any]) -> dict[str, Any]:
+        hook = getattr(self.model, "encode_for_storage", None)
+        return dict(hook(dict(values))) if callable(hook) else values
+
+    def decode_from_storage(self, values: dict[str, Any]) -> dict[str, Any]:
+        hook = getattr(self.read_model, "decode_from_storage", None)
+        return dict(hook(dict(values))) if callable(hook) else values
+
+    def to_read_model(self, obj: TableModel | Mapping[str, Any]) -> ReadModel | TableModel:
+        if self.read_model is None:
+            return cast(TableModel, obj)
+        model_fields = getattr(self.read_model, "model_fields", None)
+        field_names = model_fields.keys() if isinstance(model_fields, Mapping) else ()
+        if isinstance(obj, Mapping):
+            values = dict(obj)
+        else:
+            values = {field: getattr(obj, field) for field in field_names if hasattr(obj, field)}
+            if not values:
+                values = {key: value for key, value in vars(obj).items() if not key.startswith("_")}
+        values = self.decode_from_storage(values)
+        validator = getattr(self.read_model, "model_validate", None)
+        if not callable(validator):
+            raise TypeError("read_model must provide model_validate()")
+        return cast(ReadModel, validator(values, from_attributes=True))
+
+    async def create_item(self, item: Mapping[str, Any] | DumpableModel) -> ReadModel | TableModel:
+        return (await self.create_items([item]))[0]
+
+    async def create_items(self, items: Sequence[Mapping[str, Any] | DumpableModel]) -> list[ReadModel | TableModel]:
+        if not items:
+            return []
+        values = [self.encode_for_storage(self.to_dict(item)) for item in items]
+        objects = await self.adapter.create(self.model, values)
+        return [self.to_read_model(obj) for obj in objects]
+
+    async def read_items(
+        self,
+        query: Any = None,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        statement: Any = None,
+    ) -> list[ReadModel | TableModel]:
+        objects = await self.adapter.read(
+            self.model,
+            query,
+            limit=limit,
+            offset=offset,
+            statement=statement,
+        )
+        return [self.to_read_model(obj) for obj in objects]
+
+    async def read_one_item(self, query: Any = None) -> ReadModel | TableModel | None:
+        items = await self.read_items(query, limit=1)
+        return items[0] if items else None
+
+    async def read_item_by_primary_key(self, primary_key: Any) -> ReadModel | TableModel | None:
+        return await self.read_one_item(self.adapter.primary_key_query(self.model, primary_key))
+
+    async def read_items_by_primary_keys(self, primary_keys: Sequence[Any]) -> list[ReadModel | TableModel]:
+        return await self.read_items(self.adapter.primary_keys_query(self.model, primary_keys))
+
+    async def update_items_by_query(
+        self,
+        query: Any,
+        item: Mapping[str, Any] | DumpableModel,
+    ) -> list[ReadModel | TableModel]:
+        values = self.encode_for_storage(self.to_dict(item))
+        objects = await self.adapter.update(self.model, query, values)
+        return [self.to_read_model(obj) for obj in objects]
+
+    async def update_item_by_primary_key(
+        self,
+        primary_key: Any,
+        item: Mapping[str, Any] | DumpableModel,
+    ) -> ReadModel | TableModel | None:
+        results = await self.update_items_by_query(self.adapter.primary_key_query(self.model, primary_key), item)
+        return results[0] if results else None
+
+    async def update_items_by_primary_keys(
+        self,
+        primary_keys: Sequence[Any],
+        item: Mapping[str, Any] | DumpableModel,
+    ) -> list[ReadModel | TableModel]:
+        if not primary_keys:
+            return []
+        return await self.update_items_by_query(self.adapter.primary_keys_query(self.model, primary_keys), item)
+
+    async def delete_items_by_query(self, query: Any) -> list[ReadModel | TableModel]:
+        objects = await self.adapter.delete(self.model, query)
+        return [self.to_read_model(obj) for obj in objects]
+
+    async def delete_item_by_primary_key(self, primary_key: Any) -> ReadModel | TableModel | None:
+        results = await self.delete_items_by_query(self.adapter.primary_key_query(self.model, primary_key))
+        return results[0] if results else None
+
+    async def delete_items_by_primary_keys(self, primary_keys: Sequence[Any]) -> list[ReadModel | TableModel]:
+        if not primary_keys:
+            return []
+        return await self.delete_items_by_query(self.adapter.primary_keys_query(self.model, primary_keys))
+
+    async def count(self, query: Any = None, *, statement: Any = None) -> int:
+        return await self.adapter.count(self.model, query, statement=statement)
+
+    async def exists(self, query: Any = None) -> bool:
+        return await self.adapter.exists(self.model, query)
+
+    async def execute(self, statement: Any, params: Any = None, **kwargs: Any) -> Any:
+        return await self.adapter.execute(statement, params=params, **kwargs)

ormate/sqlalchemy/__init__.py

@@ -0,0 +1,16 @@
+from typing import TYPE_CHECKING, Any
+
+from .database import AsyncDatabase, Database
+
+if TYPE_CHECKING:
+    from ormate.adapters.sqlalchemy import SQLAlchemyAdapter
+
+__all__ = ["AsyncDatabase", "Database", "SQLAlchemyAdapter"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "SQLAlchemyAdapter":
+        from ormate.adapters.sqlalchemy import SQLAlchemyAdapter
+
+        return SQLAlchemyAdapter
+    raise AttributeError(name)

ormate/sqlalchemy/database.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Callable, Iterator, Mapping
+from contextlib import asynccontextmanager, contextmanager
+from contextvars import ContextVar
+from typing import Any, TypeVar
+
+from sqlalchemy import URL, create_engine
+from sqlalchemy.engine import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+from .sessions import AsyncSessionScope, SessionScope
+
+T = TypeVar("T")
+
+
+class Database:
+    def __init__(self, engine: Engine, **session_options: Any) -> None:
+        self.engine = engine
+        session_options.setdefault("expire_on_commit", False)
+        self.session_maker = sessionmaker(bind=engine, class_=Session, **session_options)
+        self._session_context: ContextVar[Session | None] = ContextVar(f"ormate_sync_{id(self)}", default=None)
+        self._scope_stack: ContextVar[tuple[SessionScope, ...]] = ContextVar(
+            f"ormate_sync_scope_stack_{id(self)}", default=()
+        )
+
+    @classmethod
+    def create(
+        cls,
+        url: str | URL,
+        *,
+        session_options: Mapping[str, Any] | None = None,
+        **engine_options: Any,
+    ) -> Database:
+        return cls(create_engine(url, **engine_options), **dict(session_options or {}))
+
+    @property
+    def session(self) -> Session:
+        session = self._session_context.get()
+        if session is None:
+            raise RuntimeError("No active database scope; use 'with db:' or 'with db.session_scope()'.")
+        return session
+
+    def __enter__(self) -> Session:
+        scope = self.session_scope()
+        self._scope_stack.set((*self._scope_stack.get(), scope))
+        return scope.__enter__()
+
+    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        stack = self._scope_stack.get()
+        if not stack:
+            raise RuntimeError("Database scope stack is empty")
+        scope = stack[-1]
+        try:
+            scope.__exit__(exc_type, exc_value, traceback)
+        finally:
+            self._scope_stack.set(stack[:-1])
+
+    def session_scope(self, scope: Any = None) -> SessionScope:
+        return SessionScope(self, scope)
+
+    @contextmanager
+    def session_generator(self) -> Iterator[Session]:
+        current = self._session_context.get()
+        if current is not None:
+            yield current
+            return
+        with self.session_scope() as session:
+            yield session
+
+    def run(self, fn: Callable[..., T], *args: Any, is_session: bool = True, **kwargs: Any) -> T:
+        if is_session:
+            with self.session_generator() as session:
+                return fn(session, *args, **kwargs)
+        with self.engine.begin() as connection:
+            return fn(connection, *args, **kwargs)
+
+    async def async_run(self, fn: Callable[..., T], *args: Any, is_session: bool = True, **kwargs: Any) -> T:
+        return await asyncio.to_thread(lambda: self.run(fn, *args, is_session=is_session, **kwargs))
+
+    def commit(self) -> None:
+        self.session.commit()
+
+    def rollback(self) -> None:
+        self.session.rollback()
+
+    def close(self) -> None:
+        self.engine.dispose()
+
+    async def dispose(self) -> None:
+        await asyncio.to_thread(self.close)
+
+
+class AsyncDatabase:
+    def __init__(self, engine: AsyncEngine, **session_options: Any) -> None:
+        self.engine = engine
+        session_options.setdefault("expire_on_commit", False)
+        self.session_maker = async_sessionmaker(bind=engine, class_=AsyncSession, **session_options)
+        self._session_context: ContextVar[AsyncSession | None] = ContextVar(f"ormate_async_{id(self)}", default=None)
+        self._scope_stack: ContextVar[tuple[AsyncSessionScope, ...]] = ContextVar(
+            f"ormate_async_scope_stack_{id(self)}", default=()
+        )
+
+    @classmethod
+    def create(
+        cls, url: str | URL, *, session_options: Mapping[str, Any] | None = None, **engine_options: Any
+    ) -> AsyncDatabase:
+        return cls(create_async_engine(url, **engine_options), **dict(session_options or {}))
+
+    @property
+    def session(self) -> AsyncSession:
+        session = self._session_context.get()
+        if session is None:
+            raise RuntimeError("No active database scope; use 'async with db'.")
+        return session
+
+    async def __aenter__(self) -> AsyncSession:
+        scope = self.session_scope()
+        self._scope_stack.set((*self._scope_stack.get(), scope))
+        return await scope.__aenter__()
+
+    async def __aexit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        stack = self._scope_stack.get()
+        if not stack:
+            raise RuntimeError("Async database scope stack is empty")
+        scope = stack[-1]
+        try:
+            await scope.__aexit__(exc_type, exc_value, traceback)
+        finally:
+            self._scope_stack.set(stack[:-1])
+
+    def session_scope(self, scope: Any = None) -> AsyncSessionScope:
+        return AsyncSessionScope(self, scope)
+
+    @asynccontextmanager
+    async def session_generator(self) -> AsyncIterator[AsyncSession]:
+        current = self._session_context.get()
+        if current is not None:
+            yield current
+            return
+        async with self.session_scope() as session:
+            yield session
+
+    async def async_run(self, fn: Callable[..., T], *args: Any, is_session: bool = True, **kwargs: Any) -> T:
+        if is_session:
+            async with self.session_generator() as session:
+                return await session.run_sync(fn, *args, **kwargs)
+        async with self.engine.begin() as connection:
+            return await connection.run_sync(fn, *args, **kwargs)
+
+    async def commit(self) -> None:
+        await self.session.commit()
+
+    async def rollback(self) -> None:
+        await self.session.rollback()
+
+    async def dispose(self) -> None:
+        await self.engine.dispose()
+
+
+DatabaseLike = Database | AsyncDatabase
+EngineLike = Engine | AsyncEngine | DatabaseLike
+
+
+def ensure_database(engine: EngineLike) -> DatabaseLike:
+    if isinstance(engine, (Database, AsyncDatabase)):
+        return engine
+    if isinstance(engine, AsyncEngine):
+        return AsyncDatabase(engine)
+    if isinstance(engine, Engine):
+        return Database(engine)
+    raise TypeError(f"Unsupported database engine: {type(engine).__name__}")

ormate/sqlalchemy/sessions.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from contextvars import Token
+from types import TracebackType
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Session
+
+
+class SessionScope:
+    def __init__(self, db: Any, scope: Any = None) -> None:
+        self.db = db
+        self.scope = scope if scope is not None else object()
+        self.token: Token[Any] | None = None
+        self.session: Session | None = None
+        self.owned = False
+
+    def __enter__(self) -> Session:
+        current = self.db._session_context.get()
+        if isinstance(self.scope, Session):
+            self.session = self.scope
+        elif current is not None:
+            self.session = current
+        else:
+            self.session = self.db.session_maker()
+            self.owned = True
+        self.token = self.db._session_context.set(self.session)
+        return self.session
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        try:
+            if self.owned and self.session is not None:
+                if exc_type is None:
+                    self.session.commit()
+                else:
+                    self.session.rollback()
+            elif exc_type is not None and self.session is not None:
+                self.session.rollback()
+        finally:
+            if self.owned and self.session is not None:
+                self.session.close()
+            if self.token is not None:
+                self.db._session_context.reset(self.token)
+
+
+class AsyncSessionScope:
+    def __init__(self, db: Any, scope: Any = None) -> None:
+        self.db = db
+        self.scope = scope if scope is not None else object()
+        self.token: Token[Any] | None = None
+        self.session: AsyncSession | None = None
+        self.owned = False
+
+    async def __aenter__(self) -> AsyncSession:
+        current = self.db._session_context.get()
+        if isinstance(self.scope, AsyncSession):
+            self.session = self.scope
+        elif current is not None:
+            self.session = current
+        else:
+            self.session = self.db.session_maker()
+            self.owned = True
+        self.token = self.db._session_context.set(self.session)
+        return self.session
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        try:
+            if self.owned and self.session is not None:
+                if exc_type is None:
+                    await self.session.commit()
+                else:
+                    await self.session.rollback()
+            elif exc_type is not None and self.session is not None:
+                await self.session.rollback()
+        finally:
+            if self.owned and self.session is not None:
+                await self.session.close()
+            if self.token is not None:
+                self.db._session_context.reset(self.token)

ormate/web/__init__.py

@@ -0,0 +1,8 @@
+try:
+    import starlette as _starlette  # noqa: F401
+except ImportError as exc:
+    raise ImportError("Web support requires 'ormate[web]'.") from exc
+
+from .middleware import DBSessionMiddleware
+
+__all__ = ["DBSessionMiddleware"]

ormate/web/middleware.py

@@ -0,0 +1,43 @@
+from typing import Final
+
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from ormate.sqlalchemy.database import AsyncDatabase, EngineLike, ensure_database
+
+
+class DBSessionMiddleware:
+    """Pure ASGI transaction middleware for an AsyncDatabase."""
+
+    SCOPE_KEY_PREFIX: Final = "ormate.database"
+
+    def __init__(self, app: ASGIApp, db: EngineLike, *, rollback_on_http_error: bool = False) -> None:
+        self.app = app
+        database = ensure_database(db)
+        if not isinstance(database, AsyncDatabase):
+            raise TypeError("DBSessionMiddleware requires an AsyncDatabase or AsyncEngine")
+        self.db = database
+        self.rollback_on_http_error = rollback_on_http_error
+        self.scope_key = f"{self.SCOPE_KEY_PREFIX}:{id(database)}"
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] not in {"http", "websocket"} or scope.get(self.scope_key):
+            await self.app(scope, receive, send)
+            return
+
+        status_code = 200
+
+        async def capture_status(message: Message) -> None:
+            nonlocal status_code
+            if message["type"] == "http.response.start":
+                status_code = message["status"]
+            await send(message)
+
+        async with self.db.session_scope(scope=id(scope)):
+            scope[self.scope_key] = self.db
+            try:
+                await self.app(scope, receive, capture_status)
+                if self.rollback_on_http_error and status_code >= 400:
+                    await self.db.rollback()
+            except Exception:
+                await self.db.rollback()
+                raise

ormate-0.1.0.dist-info/METADATA

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: ormate
+Version: 0.1.0
+Summary: Async repositories with separate read/write models and pluggable storage adapters
+Author: zhangzhanqi
+License: MIT License
+        
+        Copyright (c) 2026 zhangzhanqi
+        
+        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.
+        
+License-File: LICENSE
+Keywords: asyncio,database,elasticsearch,repository,sqlalchemy,sqlmodel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: sqlalchemy<3,>=2.0.36
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: elasticsearch[async]<10,>=8.17; extra == 'dev'
+Requires-Dist: httpx>=0.28; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pydantic>=2.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: sqlmodel>=0.0.22; extra == 'dev'
+Requires-Dist: starlette>=0.41; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Provides-Extra: elasticsearch
+Requires-Dist: elasticsearch[async]<10,>=8.17; extra == 'elasticsearch'
+Requires-Dist: pydantic>=2.10; extra == 'elasticsearch'
+Provides-Extra: mysql
+Requires-Dist: aiomysql>=0.2; extra == 'mysql'
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
+Provides-Extra: postgresql
+Requires-Dist: asyncpg>=0.30; extra == 'postgresql'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'postgresql'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.20; extra == 'sqlite'
+Provides-Extra: sqlmodel
+Requires-Dist: sqlmodel>=0.0.22; extra == 'sqlmodel'
+Provides-Extra: web
+Requires-Dist: starlette>=0.41; extra == 'web'
+Description-Content-Type: text/markdown
+
+# ormate
+
+ormate 是一个异步 Repository 工具包，用同一套 CRUD 接口访问 SQLAlchemy、SQLModel 和 Elasticsearch。Repository 负责输入输出模型转换，Adapter 负责具体的存储操作和查询语法。
+
+项目目前处于 `0.1.0` 阶段，API 在 `1.0` 前仍可能调整。
+
+## 安装
+
+需要 Python 3.13 或更高版本。核心包只依赖 SQLAlchemy：
+
+```bash
+pip install ormate
+```
+
+其他依赖按需安装：
+
+```bash
+pip install "ormate[sqlite]"
+pip install "ormate[sqlmodel]"
+pip install "ormate[postgresql]"
+pip install "ormate[mysql]"
+pip install "ormate[elasticsearch]"
+pip install "ormate[web]"
+```
+
+## SQLAlchemy
+
+```python
+from pydantic import BaseModel
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from ormate import AsyncDatabase, ModelRepository, SQLAlchemyAdapter
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str]
+
+
+class UserCreate(BaseModel):
+    id: int
+    name: str
+
+
+class UserRead(BaseModel):
+    id: int
+    name: str
+
+
+db = AsyncDatabase.create("sqlite+aiosqlite:///app.db")
+repository = ModelRepository(SQLAlchemyAdapter(db), User, UserRead)
+
+async with db.engine.begin() as connection:
+    await connection.run_sync(Base.metadata.create_all)
+
+created = await repository.create_item(UserCreate(id=1, name="Ada"))
+loaded = await repository.read_item_by_primary_key(1)
+updated = await repository.update_item_by_primary_key(1, {"name": "Grace"})
+deleted = await repository.delete_item_by_primary_key(1)
+```
+
+Create 和 Update 参数可以是字典，也可以是实现了 `model_dump(exclude_unset=True)` 的 Pydantic/SQLModel 对象。传入 ReadModel 时，该模型需要提供 `model_validate()`；不传则返回存储模型。
+
+SQLAlchemy 条件查询直接使用 SQLAlchemy 表达式：
+
+```python
+users = await repository.read_items(User.name.contains("Ada"), limit=20)
+total = await repository.count(User.name.contains("Ada"))
+```
+
+## SQLModel 与事务
+
+`SQLModelAdapter` 继承 `SQLAlchemyAdapter`，两者使用相同的 Session 和事务实现。绑定到同一个 `Database` 后，SQLAlchemy 和 SQLModel 的操作可以放在同一个事务中：
+
+```python
+audit_logs = ModelRepository(SQLAlchemyAdapter(db), AuditLog)
+tasks = ModelRepository(SQLModelAdapter(db), Task)
+
+async with db:
+    await audit_logs.create_item({"id": 1, "message": "task created"})
+    await tasks.create_item({"title": "publish package"})
+```
+
+作用域正常退出时提交，发生异常时回滚。同步代码可以使用 `Database` 和 `with db:`。
+
+相关示例：
+
+- `examples/async_sqlalchemy.py`
+- `examples/sync_sqlalchemy.py`
+- `examples/async_sqlmodel.py`
+- `examples/shared_transaction.py`
+
+## Elasticsearch
+
+Elasticsearch 使用 Pydantic 文档模型，查询参数保持原生 Query DSL：
+
+```python
+from ormate import ModelRepository
+from ormate.elasticsearch import ElasticsearchAdapter, ElasticsearchDocument
+
+
+class ArticleDocument(ElasticsearchDocument):
+    index_name = "articles"
+
+    title: str
+    content: str
+
+
+adapter = ElasticsearchAdapter(client, refresh="wait_for")
+articles = ModelRepository(adapter, ArticleDocument)
+
+created = await articles.create_item(
+    {"id": "quickstart", "title": "ormate", "content": "pluggable adapters"}
+)
+matched = await articles.read_items({"match": {"content": "adapters"}}, limit=10)
+updated = await articles.update_item_by_primary_key("quickstart", {"title": "ormate 0.1"})
+deleted = await articles.delete_item_by_primary_key("quickstart")
+```
+
+完整的索引初始化、CRUD、计数、聚合和客户端关闭示例在 `examples/elasticsearch.py`：
+
+```bash
+ELASTICSEARCH_URL=http://localhost:9200 uv run python examples/elasticsearch.py
+```
+
+全文检索和聚合等 ES 专属操作直接通过 `ElasticsearchAdapter` 调用。Elasticsearch 不参与 SQL 事务；SQL 与 ES 双写需要使用 outbox、消息队列或补偿机制。
+
+## Repository 和 Adapter
+
+`ModelRepository` 提供以下通用操作：
+
+- 单项和批量创建
+- 条件查询、主键查询和批量主键查询
+- 条件更新和删除
+- `count`、`exists`、`limit`、`offset`
+- 后端原生命令执行
+
+SQLAlchemy/SQLModel 额外支持复合主键。后端特有的能力不放进通用协议，例如 SQL JOIN 和 ES 聚合分别留在对应 Adapter 中。
+
+实现 `StorageAdapter` 协议可以接入其他存储：
+
+```python
+repository = ModelRepository(custom_adapter, CustomModel, CustomRead)
+```
+
+Adapter 负责持久化、查询、主键条件和存储名称。Repository 负责输入转换、`encode_for_storage()`、`decode_from_storage()` 和 ReadModel 构造。
+
+ormate 不定义 `id`、`created_at`、`updated_at` 等业务字段。SQLAlchemy/SQLModel 继续使用 `__tablename__`，Elasticsearch 使用 `index_name`，统一名称可以从 Repository 获取：
+
+```python
+repository.storage_name
+```
+
+`ElasticsearchDocument.id` 只用于映射 Elasticsearch `_id`。
+
+## Web 中间件
+
+```python
+from ormate.web import DBSessionMiddleware
+
+app.add_middleware(
+    DBSessionMiddleware,
+    db=db,
+    rollback_on_http_error=True,
+)
+```
+
+中间件接受 `AsyncDatabase` 或 `AsyncEngine`，为每个 HTTP/WebSocket 请求建立独立会话作用域。
+
+## 当前限制
+
+- PostgreSQL、MySQL 和真实 Elasticsearch 集群尚未加入自动化集成测试。
+- Elasticsearch 条件批量更新和删除受 `default_size` 限制，默认最多处理 1000 个匹配文档。
+- ES mapping 迁移、bulk、PIT/search_after 和乐观并发控制尚未实现。
+- 不提供 SQL 与 Elasticsearch 之间的分布式事务。
+
+## 路线图
+
+`0.1.x` 用于完成首次 PyPI 发布，当前还需要经过 TestPyPI 安装验证。
+
+`0.2` 主要完善 Elasticsearch：bulk 写入、PIT/search_after、索引 mapping 管理、并发冲突处理和真实集群测试。
+
+`0.3` 主要完善关系型数据库：PostgreSQL/MySQL 测试矩阵、分页结果类型、显式 savepoint API 和批量性能优化。
+
+后续会补充 Adapter 契约测试工具，并评估 MongoDB、RedisJSON 以及 SQL 到 ES 的 outbox 示例。到 `1.0` 前会冻结公共 API，补齐迁移指南和性能基准。
+
+路线图只表示开发方向，不承诺具体发布日期。
+
+## 开发
+
+```bash
+uv sync --all-extras
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv build
+uv run twine check dist/*
+```
+
+发布步骤见 `docs/publishing.md`。
+
+## License
+
+[MIT License](LICENSE)
+

ormate-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+ormate/__init__.py,sha256=8drbFhYVZ7PVR-cDBsKZWmRFLLPec4VLk-EIVYmQbEQ,315
+ormate/protocols.py,sha256=7S10KP0OUcog4193WCord3DCL2n5thOdQfSZdQEzrKY,482
+ormate/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+ormate/repository.py,sha256=fELOUK53SnpmNSV8PrPIaQIel8WdymRQ8p8piVajVcw,6261
+ormate/adapters/__init__.py,sha256=BN5nzhykjq4W94glsiMmOrCVlZnftlcdREjC-Z6HS68,183
+ormate/adapters/base.py,sha256=nT2HI86fzyFVRMRwW_QdIdAd832Gxhjd2Q4s-1K6HsA,1209
+ormate/adapters/elasticsearch.py,sha256=q2C5FgjM-eTh8LgKG6ETNdudghd_ueaCfU1oEaDeiO8,6092
+ormate/adapters/sqlalchemy.py,sha256=6uenSOrj79tFPrbmP-xK4yrxPSOTbS25AYl11l3gB-E,5904
+ormate/adapters/sqlmodel.py,sha256=B3EoS04u31DyQCpfvkQCeY3rtpEeKr3BfMEW0qoHato,163
+ormate/elasticsearch/__init__.py,sha256=NIvBYK46ERKsG413eyrdIY-iMqHi5vvZqVsGx9pTBI8,397
+ormate/elasticsearch/document.py,sha256=yZh4Hw15TncaFCGCiZ_eQBFPXsPqSA9epWPDZ3tnc-E,572
+ormate/sqlalchemy/__init__.py,sha256=HiIAoF64wWYRdw3vjoQZ9zP5jtFYOUpoTuinw8Ixv7c,430
+ormate/sqlalchemy/database.py,sha256=aqxpF-NWc4byHw5uhpvQu5WdxDWsvoHDr7DwKVOs180,6433
+ormate/sqlalchemy/sessions.py,sha256=AlIZHO4dMwemJWBPntA2Mjoql-mrVkaSUK8_eWKf80k,3085
+ormate/web/__init__.py,sha256=GWYqhiQUCqMv3swwP7mELK5zbqcMABxK8Tq7PzFTQrg,231
+ormate/web/middleware.py,sha256=zfhY6eXmwpTxTxjzUWtv_F_lT2KGteRIsdM9k3nsTGw,1670
+ormate-0.1.0.dist-info/METADATA,sha256=A6GTjsblfAwygEvuoHl5qJt7cDnykdJJfISyNR0GkRo,9601
+ormate-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+ormate-0.1.0.dist-info/licenses/LICENSE,sha256=0Qv1NR8OzTBwQvKk3XCtNGnN_35_3K3itnIGI0_QuUQ,1069
+ormate-0.1.0.dist-info/RECORD,,

ormate-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

ormate-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 zhangzhanqi
+
+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.
+