SARepo 0.1.0__py3-none-any.whl

SARepo/__init__.py

@@ -0,0 +1,5 @@
+
+from .base import Page, PageRequest, NotFoundError, ConcurrencyError
+from .sa_repo import SARepository, SAAsyncRepository
+from .uow import UoW, AsyncUoW
+from . import specs as specs

SARepo/base.py

@@ -0,0 +1,31 @@
+
+from typing import Generic, TypeVar, Sequence
+T = TypeVar("T")
+
+class NotFoundError(Exception):
+    """Raised when entity not found."""
+    pass
+
+class ConcurrencyError(Exception):
+    """Raised when optimistic lock/version conflicts occur."""
+    pass
+
+class PageRequest:
+    def __init__(self, page: int = 0, size: int = 10):
+        if page < 0:
+            raise ValueError("page must be >= 0")
+        if not (1 <= size <= 10000):
+            raise ValueError("size must be in [1, 10000]")
+        self.page = page
+        self.size = size
+
+class Page(Generic[T]):
+    def __init__(self, items: Sequence[T], total: int, page: int, size: int):
+        self.items = list(items)
+        self.total = int(total)
+        self.page = int(page)
+        self.size = int(size)
+
+    @property
+    def pages(self) -> int:
+        return (self.total + self.size - 1) // self.size

SARepo/models.py

@@ -0,0 +1,14 @@
+
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy import func, DateTime, Boolean
+
+class Base(DeclarativeBase):
+    """Base for user models if you don't want to declare your own."""
+    pass
+
+class TimeStamped:
+    created_at: Mapped["datetime"] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped["datetime"] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+class SoftDelete:
+    is_deleted: Mapped[bool] = mapped_column(Boolean, default=False, index=True)

SARepo/repo.py

@@ -0,0 +1,14 @@
+
+from typing import Generic, TypeVar, Type, Optional, Any, Protocol
+from .base import Page, PageRequest
+
+T = TypeVar("T")
+
+class CrudRepository(Protocol, Generic[T]):
+    model: Type[T]
+    def get(self, id_: Any) -> T: ...
+    def try_get(self, id_: Any) -> Optional[T]: ...
+    def add(self, entity: T) -> T: ...
+    def update(self, entity: T) -> T: ...
+    def remove(self, entity: T) -> None: ...
+    def page(self, page: PageRequest, spec=None, order_by=None) -> Page[T]: ...

SARepo/sa_repo.py

@@ -0,0 +1,108 @@
+
+from typing import Type, Generic, TypeVar, Optional, Sequence, Any, Callable
+from sqlalchemy.orm import Session
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func
+from .base import PageRequest, Page, NotFoundError
+
+T = TypeVar("T")
+Spec = Callable  # aliased to match specs.Spec
+
+class SARepository(Generic[T]):
+    """Synchronous repository implementation for SQLAlchemy 2.x."""
+    def __init__(self, model: Type[T], session: Session):
+        self.model = model
+        self.session = session
+
+    def _select(self):
+        return select(self.model)
+
+    def get(self, id_: Any) -> T:
+        obj = self.session.get(self.model, id_)
+        if not obj:
+            raise NotFoundError(f"{self.model.__name__}({id_}) not found")
+        return obj
+
+    def try_get(self, id_: Any) -> Optional[T]:
+        return self.session.get(self.model, id_)
+
+    def add(self, entity: T) -> T:
+        self.session.add(entity)
+        self.session.flush()
+        self.session.refresh(entity)
+        return entity
+
+    def update(self, entity: T) -> T:
+        self.session.flush()
+        self.session.refresh(entity)
+        return entity
+
+    def remove(self, entity: T) -> None:
+        if hasattr(entity, "is_deleted"):
+            setattr(entity, "is_deleted", True)
+        else:
+            self.session.delete(entity)
+
+    def page(self, page: PageRequest, spec: Optional[Spec] = None, order_by=None) -> Page[T]:
+        stmt = self._select()
+        if spec:
+            stmt = spec(stmt)
+        if order_by is not None:
+            stmt = stmt.order_by(order_by)
+        total = self.session.execute(
+            select(func.count()).select_from(stmt.subquery())
+        ).scalar_one()
+        items = self.session.execute(
+            stmt.offset(page.page * page.size).limit(page.size)
+        ).scalars().all()
+        return Page(items, total, page.page, page.size)
+
+class SAAsyncRepository(Generic[T]):
+    """Async repository implementation for SQLAlchemy 2.x."""
+    def __init__(self, model: Type[T], session: AsyncSession):
+        self.model = model
+        self.session = session
+
+    def _select(self):
+        return select(self.model)
+
+    async def get(self, id_: Any) -> T:
+        obj = await self.session.get(self.model, id_)
+        if not obj:
+            raise NotFoundError(f"{self.model.__name__}({id_}) not found")
+        return obj
+
+    async def try_get(self, id_: Any) -> Optional[T]:
+        return await self.session.get(self.model, id_)
+
+    async def add(self, entity: T) -> T:
+        self.session.add(entity)
+        await self.session.flush()
+        await self.session.refresh(entity)
+        return entity
+
+    async def update(self, entity: T) -> T:
+        await self.session.flush()
+        await self.session.refresh(entity)
+        return entity
+
+    async def remove(self, entity: T) -> None:
+        if hasattr(entity, "is_deleted"):
+            setattr(entity, "is_deleted", True)
+        else:
+            await self.session.delete(entity)
+
+    async def page(self, page: PageRequest, spec: Optional[Spec] = None, order_by=None) -> Page[T]:
+        stmt = self._select()
+        if spec:
+            stmt = spec(stmt)
+        if order_by is not None:
+            stmt = stmt.order_by(order_by)
+        total = (await self.session.execute(
+            select(func.count()).select_from(stmt.subquery())
+        )).scalar_one()
+        res = await self.session.execute(
+            stmt.offset(page.page * page.size).limit(page.size)
+        )
+        items = res.scalars().all()
+        return Page(items, total, page.page, page.size)

SARepo/specs.py

@@ -0,0 +1,27 @@
+
+from typing import Callable
+from sqlalchemy.sql import Select
+
+Spec = Callable[[Select], Select]
+
+def and_specs(*specs: Spec) -> Spec:
+    def _apply(q: Select) -> Select:
+        for s in specs:
+            q = s(q)
+        return q
+    return _apply
+
+def eq(model_attr, value) -> Spec:
+    def _s(q: Select) -> Select:
+        return q.where(model_attr == value)
+    return _s
+
+def ilike(model_attr, pattern: str) -> Spec:
+    def _s(q: Select) -> Select:
+        return q.where(model_attr.ilike(pattern))
+    return _s
+
+def not_deleted(model_cls) -> Spec:
+    def _s(q: Select) -> Select:
+        return q.where(getattr(model_cls, "is_deleted") == False)  # noqa: E712
+    return _s

SARepo/uow.py

@@ -0,0 +1,28 @@
+
+from contextlib import AbstractContextManager
+from sqlalchemy.orm import Session
+from sqlalchemy.ext.asyncio import AsyncSession
+
+class UoW(AbstractContextManager):
+    """Minimal Unit of Work for sync SQLAlchemy sessions."""
+    def __init__(self, session: Session):
+        self.session = session
+    def __enter__(self):
+        return self
+    def __exit__(self, exc_type, *_):
+        if exc_type:
+            self.session.rollback()
+        else:
+            self.session.commit()
+
+class AsyncUoW:
+    """Minimal Unit of Work for async SQLAlchemy sessions."""
+    def __init__(self, session: AsyncSession):
+        self.session = session
+    async def __aenter__(self):
+        return self
+    async def __aexit__(self, exc_type, *_):
+        if exc_type:
+            await self.session.rollback()
+        else:
+            await self.session.commit()

sarepo-0.1.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: SARepo
+Version: 0.1.0
+Summary: Minimal, explicit Repository & Unit-of-Work layer over SQLAlchemy 2.x
+Author: nurbergenovv
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: SQLAlchemy>=2.0
+Dynamic: license-file
+
+
+# SARepo
+
+Minimal, explicit **Repository** + **Unit of Work** layer on top of **SQLAlchemy 2.x** (sync & async).
+No magic method-names, just clean typed APIs, composable specs, pagination, and optional soft-delete.
+
+## Install (editable)
+
+```bash
+pip install -e .
+```
+
+## Quick Start (sync)
+
+```python
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker, Mapped, mapped_column
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy import String
+
+from SARepo.sa_repo import SARepository
+from SARepo.base import PageRequest
+from SARepo.specs import and_specs, ilike
+
+class Base(DeclarativeBase): pass
+
+class Request(Base):
+    __tablename__ = "requests"
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    title: Mapped[str] = mapped_column(String(255))
+    status: Mapped[str] = mapped_column(String(50))
+
+engine = create_engine("sqlite+pysqlite:///:memory:", echo=False)
+Base.metadata.create_all(engine)
+SessionLocal = sessionmaker(bind=engine, expire_on_commit=False)
+
+with SessionLocal() as session:
+    repo = SARepository(Request, session)
+    # create
+    r = repo.add(Request(title="Hello", status="NEW"))
+    session.commit()
+
+    # search + paginate
+    page = repo.page(PageRequest(0, 10), spec=ilike(Request.title, "%He%"))
+    print(page.total, [i.title for i in page.items])
+```
+
+## Async Quick Start
+
+```python
+import asyncio
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+from SARepo.sa_repo import SAAsyncRepository
+from SARepo.base import PageRequest
+
+async def main():
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:", echo=False)
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    SessionLocal = async_sessionmaker(bind=engine, expire_on_commit=False)
+    async with SessionLocal() as session:
+        repo = SAAsyncRepository(Request, session)
+        await repo.add(Request(title="Hello", status="NEW"))
+        await session.commit()
+        page = await repo.page(PageRequest(0, 10))
+        print(page.total)
+
+asyncio.run(main())
+```
+
+## Features
+- `SARepository` and `SAAsyncRepository` (CRUD, `page()` with total count)
+- Composable **specs** (`eq`, `ilike`, `and_specs`, `not_deleted`)
+- Optional **soft-delete** if the entity has `is_deleted: bool`
+- Minimal **Unit of Work** helpers (sync & async)
+
+## License
+MIT

sarepo-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+SARepo/__init__.py,sha256=tNYbuUDloC1qVnXq7uomS3jRcaPUvy0VEZiMdYR6x1M,183
+SARepo/base.py,sha256=UbAdZ9WYh_o93mrCVL3D8Q0tY_8mvm0HspO_L5m0GTQ,874
+SARepo/models.py,sha256=ypSmbKAijvNH4WjSeJBgyNT8mKa_e_7-I5kiNisjGAI,570
+SARepo/repo.py,sha256=vCVQmjYifzlO_ggOFwj3Xdyqt4_7ILDoUtHUAFnFyZU,482
+SARepo/sa_repo.py,sha256=mdTe3RyrGklG3z50jr4pOv4aidWxOZ_6dtdLgr83Osk,3617
+SARepo/specs.py,sha256=e-X1cCkva3e71M37hcfbjNDMezZAaOkkRaPToUzhEeU,687
+SARepo/uow.py,sha256=yPlvi7PoH9x2pLNt6hEin9zT5qG9axUKn_TkZcIuz1s,859
+sarepo-0.1.0.dist-info/licenses/LICENSE,sha256=px90NOQCrnZ77qoFT8IvAiNS1CXQ2OU27uVBKbki9DM,131
+sarepo-0.1.0.dist-info/METADATA,sha256=lHz7KBK2U2CAvoxwUB1ytK9d1LeNoiV0ODlvM7BFjgE,2691
+sarepo-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sarepo-0.1.0.dist-info/top_level.txt,sha256=0k952UYVZLIIv3kZzFlxI0yzBMusZo3-XCQtxms_kS0,7
+sarepo-0.1.0.dist-info/RECORD,,

sarepo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sarepo-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+... (shortened) ...

sarepo-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+SARepo