Initial release: async repository layer over SQLModel

README.md

@@ -0,0 +1,199 @@
+# MetaORM
+
+Async repository layer over [SQLModel](https://sqlmodel.tiangolo.com). Provides a minimal, explicit pattern for database access with optional DTO mapping, automatic transaction management via `contextvars`, and built-in filter / pagination / sort support via `pydantic-filters`.
+
+## Install
+
+```bash
+pip install "git+https://github.com/OlegYurchik/metaorm.git"
+```
+
+Requires Python `>=3.12`.
+
+> **Note:** The package is installed directly from GitHub because `metaorm` depends on a patched version of `pydantic-filters` (from `so-saf/pydantic-filters`) that is not yet available on PyPI.
+
+## Quick start
+
+The simplest mode works with SQLModel tables directly — no DTOs, no generics, no magic:
+
+```python
+from sqlmodel import Field
+from metaorm import BaseRepository, BaseTable, DatabaseSettings
+
+
+class UserTable(BaseTable, table=True):
+    __tablename__ = "users"
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+    email: str = Field(unique=True)
+
+
+class UserRepository(BaseRepository):
+    def get_db_table(self) -> type[UserTable]:
+        return UserTable
+
+
+async def main():
+    repo = UserRepository(
+        settings=DatabaseSettings(dsn="sqlite+aiosqlite:///:memory:"),
+    )
+    await repo.create_tables()
+
+    user = await repo.create_item(
+        UserTable(name="Alice", email="alice@example.com"),
+    )
+    print(user.id, user.name)
+
+    all_users = [u async for u in repo.get_items()]
+    print(len(all_users))
+```
+
+## DTO mapping
+
+When you want repository methods to return separate Pydantic models instead of table instances, override `get_dto_type()` and implement `from_item` / `to_item` on the table:
+
+```python
+from pydantic import BaseModel
+from sqlmodel import Field
+from metaorm import BaseRepository, BaseTable, DatabaseSettings
+
+
+class User(BaseModel):
+    id: int | None = None
+    name: str
+
+
+class UserTable(BaseTable[User], table=True):
+    __tablename__ = "users"
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+
+    @classmethod
+    def from_item(cls, item: User) -> "UserTable":
+        return cls(id=item.id, name=item.name)
+
+    def to_item(self) -> User:
+        return User(id=self.id, name=self.name)
+
+
+class UserRepository(BaseRepository):
+    def get_db_table(self) -> type[UserTable]:
+        return UserTable
+
+    def get_dto_type(self) -> type[User]:
+        return User
+
+
+async def main():
+    repo = UserRepository(
+        settings=DatabaseSettings(dsn="sqlite+aiosqlite:///:memory:"),
+    )
+    await repo.create_tables()
+
+    user = await repo.create_item(User(name="Alice"))
+    # user is a User DTO, not UserTable
+    print(user.model_dump())
+```
+
+## Filters, pagination and sorting
+
+`pydantic-filters` provides `BaseFilter`, `BasePagination` and `BaseSort`. Pass them to `get_items`:
+
+```python
+from pydantic_filters import BaseFilter, BaseSort, OffsetPagination
+
+class BookFilter(BaseFilter):
+    title: str | None = None
+    year: int | None = None
+
+
+class BookRepository(BaseRepository):
+    def get_db_table(self) -> type[BookTable]:
+        return BookTable
+
+    def get_filter_type(self) -> type[BookFilter]:
+        return BookFilter
+
+
+# Exact match filter
+filtered = [
+    item
+    async for item in repo.get_items(filter_=BookFilter(year=2025))
+]
+
+# Pagination
+page = [
+    item
+    async for item in repo.get_items(
+        pagination=OffsetPagination(offset=10, limit=20),
+    )
+]
+
+# Sorting
+sorted_items = [
+    item
+    async for item in repo.get_items(
+        sort=BaseSort(sort_by="year", sort_by_order="desc"),
+    )
+]
+```
+
+## Explicit transactions
+
+Each repository method already runs inside a transaction automatically. If you need an explicit scope (e.g. to read `repository.session`), use `repository.transaction()`:
+
+```python
+async with repo.transaction():
+    user = await repo.create_item(UserTable(name="Alice"))
+    # nested transaction reuses the same session
+    async with repo.transaction():
+        items = [item async for item in repo.get_items()]
+```
+
+## Atomic transactions across multiple repositories
+
+Use `RepositoriesContainer` when you need a single atomic transaction spanning multiple repositories:
+
+```python
+from metaorm import RepositoriesContainer
+
+container = RepositoriesContainer(settings=settings)
+user_repo = container.get_repository(UserRepository)
+order_repo = container.get_repository(OrderRepository)
+
+async with container.transaction():
+    user = await user_repo.create_item(UserTable(name="Alice"))
+    await order_repo.create_item(OrderTable(user_id=user.id, total=100))
+```
+
+`container.transaction()` stores the session in a `contextvars.ContextVar`. All repository operations within the `async with` block automatically reuse that session. Nested `container.transaction()` calls yield the same session.
+
+## Eager loading
+
+`get_items()` and `update_items()` accept an optional `options` parameter for SQLAlchemy eager loading strategies:
+
+```python
+from sqlalchemy.orm import joinedload
+
+books = [
+    item
+    async for item in book_repo.get_items(
+        options=[joinedload(BookTable.author)],
+    )
+]
+```
+
+## Exceptions
+
+```
+DatabaseException
+├── NotFoundError
+├── HaveNoSessionError
+└── AlreadyExistsError
+```
+
+All repository methods raise `DatabaseException` subclasses or SQLAlchemy errors.
+
+## License
+
+MIT