SARepo 0.1.0__tar.gz

sarepo-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,78 @@
+
+# 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/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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/SARepo.egg-info/PKG-INFO

@@ -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/SARepo.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+SARepo/__init__.py
+SARepo/base.py
+SARepo/models.py
+SARepo/repo.py
+SARepo/sa_repo.py
+SARepo/specs.py
+SARepo/uow.py
+SARepo.egg-info/PKG-INFO
+SARepo.egg-info/SOURCES.txt
+SARepo.egg-info/dependency_links.txt
+SARepo.egg-info/requires.txt
+SARepo.egg-info/top_level.txt
+tests/test_sync_basic.py

sarepo-0.1.0/SARepo.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sarepo-0.1.0/SARepo.egg-info/requires.txt

@@ -0,0 +1 @@
+SQLAlchemy>=2.0

sarepo-0.1.0/SARepo.egg-info/top_level.txt

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

sarepo-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+
+[project]
+name = "SARepo"
+version = "0.1.0"
+description = "Minimal, explicit Repository & Unit-of-Work layer over SQLAlchemy 2.x"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{name = "nurbergenovv"}]
+license = {text = "MIT"}
+dependencies = [
+  "SQLAlchemy>=2.0"
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["SARepo"]
+include-package-data = true

sarepo-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sarepo-0.1.0/tests/test_sync_basic.py

@@ -0,0 +1,30 @@
+
+import pytest
+from sqlalchemy import create_engine, String
+from sqlalchemy.orm import sessionmaker, DeclarativeBase, Mapped, mapped_column
+from SARepoo.sa_repo import SARepository
+from SARepoo.base import PageRequest
+
+class Base(DeclarativeBase): pass
+
+class Item(Base):
+    __tablename__ = "items"
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    title: Mapped[str] = mapped_column(String(100))
+
+def test_crud_and_pagination():
+    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(Item, session)
+        for i in range(25):
+            repo.add(Item(title=f"t{i}"))
+        session.commit()
+
+        page = repo.page(PageRequest(1, 10))
+        assert page.total == 25
+        assert len(page.items) == 10
+        assert page.page == 1
+        assert page.pages == 3