SARepo 0.1.7__tar.gz → 0.1.8__tar.gz

sarepo-0.1.8/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: SARepo
+Version: 0.1.8
+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.
+
+---
+
+## 🚀 Quick Start (Sync)
+
+```python
+from sqlalchemy import create_engine, String
+from sqlalchemy.orm import sessionmaker, DeclarativeBase, Mapped, mapped_column
+
+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))
+
+
+# Setup database
+engine = create_engine("sqlite+pysqlite:///:memory:", echo=False)
+Base.metadata.create_all(engine)
+SessionLocal = sessionmaker(bind=engine, expire_on_commit=False)
+
+# Usage
+with SessionLocal() as session:
+    repo = SARepository(Request, session)
+
+    # Create
+    r = repo.add(Request(title="Hello", status="NEW"))
+    session.commit()
+
+    # Query + 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 / SAAsyncRepository**
+- Clean CRUD operations (`get`, `add`, `update`, `remove`, etc.)
+- `page()` method with total count
+
+✅ **Composable Specs**
+- Combine filters easily (`eq`, `ilike`, `and_specs`, `not_deleted`)
+
+✅ **Soft Delete**
+- Automatically filters out rows with `is_deleted=True` if the model has this column
+
+✅ **Typed Protocol Interface**
+- `CrudRepository` protocol for structural typing & IDE autocompletion
+
+✅ **Unit of Work**
+- Minimal sync & async helpers for transactional operations
+
+---
+
+## 🧩 Example: Spec Composition
+
+```python
+from SARepo.specs import eq, ilike, and_specs
+
+spec = and_specs(
+    eq(Request.status, "NEW"),
+    ilike(Request.title, "%Hello%")
+)
+
+page = repo.page(PageRequest(0, 10), spec=spec)
+```
+
+---
+
+## 📜 License
+
+**MIT License**  
+Copyright (c) 2025  
+
+---
+
+## 🧭 Project Structure (Example)
+
+```
+SARepo/
+│
+├── sa_repo.py         # Core Repository classes (sync & async)
+├── base.py            # Pagination, PageRequest, DTO helpers
+├── specs.py           # Composable query specs
+├── uow.py             # Optional Unit of Work layer
+├── __init__.py
+```
+
+---
+
+### ✅ Philosophy
+
+- No ORM “magic” — only explicit SQLAlchemy 2.0 APIs  
+- One repository → one model  
+- Predictable transaction scope  
+- Works with Pydantic DTOs or dataclasses  
+- 100 % type-safe

sarepo-0.1.8/README.md

@@ -0,0 +1,145 @@
+# 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.
+
+---
+
+## 🚀 Quick Start (Sync)
+
+```python
+from sqlalchemy import create_engine, String
+from sqlalchemy.orm import sessionmaker, DeclarativeBase, Mapped, mapped_column
+
+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))
+
+
+# Setup database
+engine = create_engine("sqlite+pysqlite:///:memory:", echo=False)
+Base.metadata.create_all(engine)
+SessionLocal = sessionmaker(bind=engine, expire_on_commit=False)
+
+# Usage
+with SessionLocal() as session:
+    repo = SARepository(Request, session)
+
+    # Create
+    r = repo.add(Request(title="Hello", status="NEW"))
+    session.commit()
+
+    # Query + 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 / SAAsyncRepository**
+- Clean CRUD operations (`get`, `add`, `update`, `remove`, etc.)
+- `page()` method with total count
+
+✅ **Composable Specs**
+- Combine filters easily (`eq`, `ilike`, `and_specs`, `not_deleted`)
+
+✅ **Soft Delete**
+- Automatically filters out rows with `is_deleted=True` if the model has this column
+
+✅ **Typed Protocol Interface**
+- `CrudRepository` protocol for structural typing & IDE autocompletion
+
+✅ **Unit of Work**
+- Minimal sync & async helpers for transactional operations
+
+---
+
+## 🧩 Example: Spec Composition
+
+```python
+from SARepo.specs import eq, ilike, and_specs
+
+spec = and_specs(
+    eq(Request.status, "NEW"),
+    ilike(Request.title, "%Hello%")
+)
+
+page = repo.page(PageRequest(0, 10), spec=spec)
+```
+
+---
+
+## 📜 License
+
+**MIT License**  
+Copyright (c) 2025  
+
+---
+
+## 🧭 Project Structure (Example)
+
+```
+SARepo/
+│
+├── sa_repo.py         # Core Repository classes (sync & async)
+├── base.py            # Pagination, PageRequest, DTO helpers
+├── specs.py           # Composable query specs
+├── uow.py             # Optional Unit of Work layer
+├── __init__.py
+```
+
+---
+
+### ✅ Philosophy
+
+- No ORM “magic” — only explicit SQLAlchemy 2.0 APIs  
+- One repository → one model  
+- Predictable transaction scope  
+- Works with Pydantic DTOs or dataclasses  
+- 100 % type-safe

sarepo-0.1.8/SARepo/repo.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from typing import Any, Generic, List, Optional, Protocol, Type, TypeVar, runtime_checkable
+
+from SARepo.sa_repo import Spec
+from .base import Page, PageRequest
+
+T = TypeVar("T")
+
+
+@runtime_checkable
+class CrudRepository(Protocol, Generic[T]):
+    """
+    Контракт CRUD-репозитория для SQLAlchemy-подобной реализации.
+    Реализация должна соответствовать сигнатурам ниже.
+    """
+
+    model: Type[T]
+
+
+    def getAll(
+        self,
+        limit: Optional[int] = None,
+        *,
+        include_deleted: bool = False,
+        order_by=None,
+        **filters: Any,
+    ) -> List[T]:
+        ...
+
+    def get(self, id_: Any = None, *, include_deleted: bool = False, **filters: Any) -> T:
+        """
+        Должен вернуть объект T или бросить исключение (например, NotFoundError),
+        если объект не найден. Если хочешь Optional — измени сигнатуру.
+        """
+        ...
+
+    def try_get(self, id_: Any = None, *, include_deleted: bool = False, **filters: Any) -> Optional[T]:
+        ...
+
+    def add(self, entity: T) -> T:
+        ...
+
+    def update(self, entity: T) -> T:
+        ...
+
+    def remove(self, entity: Optional[T] = None, id: Optional[Any] = None) -> bool:
+        ...
+
+    def delete_by_id(self, id_: Any) -> bool:
+        ...
+
+    def page(
+        self,
+        page: PageRequest,
+        spec: Optional[Spec] = None,
+        order_by=None,
+        *,
+        include_deleted: bool = False,
+    ) -> Page[T]:
+        ...
+
+    def get_all_by_column(
+        self,
+        column_name: str,
+        value: Any,
+        *,
+        limit: Optional[int] = None,
+        order_by=None,
+        include_deleted: bool = False,
+        **extra_filters: Any,
+    ) -> list[T]:
+        ...
+
+    def find_all_by_column(
+        self,
+        column_name: str,
+        value: Any,
+        *,
+        limit: Optional[int] = None,
+        order_by=None,
+        include_deleted: bool = False,
+        **extra_filters: Any,
+    ) -> list[T]:
+        ...
+
+    def get_or_create(self, defaults: Optional[dict] = None, **unique_filters: Any) -> tuple[T, bool]:
+        ...
+
+    def raw_query(self, sql: str, params: Optional[dict] = None) -> list[dict]:
+        ...
+
+    def aggregate_avg(self, column_name: str, **filters: Any) -> Optional[float]:
+        ...
+
+    def aggregate_min(self, column_name: str, **filters: Any):
+        ...
+
+    def aggregate_max(self, column_name: str, **filters: Any):
+        ...
+
+    def aggregate_sum(self, column_name: str, **filters: Any):
+        ...
+
+    def count(self, **filters: Any) -> int:
+        ...
+
+    def restore(self, id_: Any) -> bool:
+        ...