s-ormkit 0.0.1__tar.gz

s_ormkit-0.0.1/.gitignore

@@ -0,0 +1,6 @@
+dist/
+.venv
+__pycache__/
+.pytest_cache/
+*.egg-info/
+.coverage

s_ormkit-0.0.1/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+Все значительные изменения этого проекта будут документироваться в этом файле.
+
+Формат основан на [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+и этот проект соответствует [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-07-04
+
+### Added
+
+- **Declarative-база и миксины** (`Base`, `IntPkMixin`, `TimestampMixin`): общий
+  SQLAlchemy 2.0 declarative base и переиспользуемые миксины (int-PK, диалект-нейтральные
+  временные метки через `func.now()`)
+- **Движок из DB-URL** (`make_engine`, `make_session_factory`, `init_schema`, `drop_schema`,
+  `dispose_engine`): резолв URL (аргумент → env `ORMKIT_DB_URL` → default), ленивое
+  создание движка (postgres-URL без коннекта), автоматический `PRAGMA foreign_keys=ON` для
+  sqlite
+- **Repository-паттерн** (`BaseRepository[TModel, TDomain]`): generic CRUD
+  (`add / get / get_or_none / list / update / remove / count`) с маппингом ORM <-> domain
+  через переопределяемые хуки `to_domain` / `to_orm`
+- **Транзакционная граница** (`UnitOfWork`): контекст-менеджер с rollback при исключении,
+  гарантированным `close` и явным `commit`
+- **DIP-контракты** (`RepositoryProtocol`, `UnitOfWorkProtocol`): Protocol'ы для зависимости
+  прикладного слоя от абстракций, а не от `BaseRepository` / SQLAlchemy
+- **Исключения** (`OrmKitError`, `NotFoundError`)
+- **Тесты** (unit + integration, coverage ≥ 80%): резолв DB-URL, FK enforcement на sqlite,
+  round-trip CRUD, транзакции UoW, диалект-нейтральность временных меток; демо-модели
+  объявлены в самих тестах
+
+### Notes
+
+- Первый релиз кита `s-ormkit` как generic БД/ORM-инфраструктуры для экосистемы S-kits
+- 0 завязок на конкретное приложение: только чистая инфраструктура
+- Зависит ТОЛЬКО от SQLAlchemy>=2.0
+- Диалект-нейтрально: движок заменяется через DB-URL (sqlite → postgres → mysql) без правок кода

s_ormkit-0.0.1/LICENSE

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

s_ormkit-0.0.1/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: s-ormkit
+Version: 0.0.1
+Summary: Generic БД/ORM-инфраструктура на SQLAlchemy 2.0: диалект-нейтральный движок из DB-URL, Repository + UnitOfWork + DIP-протоколы. 0 завязок на конкретное приложение.
+Author: Dmitry
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# s-ormkit
+
+Generic БД/ORM-инфраструктура для экосистемы S-kits на SQLAlchemy 2.0: диалект-нейтральный
+движок из DB-URL, Repository + UnitOfWork + DIP-протоколы.
+
+**Версия:** 0.0.1 (первый релиз)  
+**Лицензия:** MIT  
+**Зависимости:** `SQLAlchemy>=2.0` (и ничего больше)
+
+Кит НЕ знает ни о каком приложении. Прикладная логика получает БД-слой через ORM так,
+что не зависит от sqlite/диалекта: движок конфигурируется через DB-URL и заменяется на
+`postgresql://.../mysql://...` **без изменения кода**.
+
+## Что входит
+
+### Declarative-база и миксины (`base.py`)
+- `Base` — общий declarative base для моделей-наследников
+- `IntPkMixin` — целочисленный автоинкрементный первичный ключ
+- `TimestampMixin` — `created_at` / `updated_at` через `func.now()` (диалект-нейтрально)
+
+### Движок из DB-URL (`engine.py`)
+- `make_engine` — резолв URL (аргумент → env → default), для sqlite включает
+  `PRAGMA foreign_keys=ON`; `create_engine` ленив (postgres-URL создаётся без коннекта)
+- `make_session_factory` — `sessionmaker(expire_on_commit=False)`
+- `init_schema` / `drop_schema` — создать/удалить таблицы
+- `dispose_engine` — освободить пул соединений
+
+### Repository-паттерн (`repository.py`)
+- `BaseRepository[TModel, TDomain]` — generic CRUD: `add / get / get_or_none / list /
+  update / remove / count`
+- Маппинг ORM <-> domain через переопределяемые хуки `to_domain` / `to_orm`
+- Не коммитит сам (это делает `UnitOfWork`) — только `flush` для получения id
+
+### Транзакционная граница (`unit_of_work.py`)
+- `UnitOfWork` — контекст-менеджер: rollback при исключении, `close` всегда, `commit` явный
+
+### DIP-контракты (`protocols.py`)
+- `RepositoryProtocol` / `UnitOfWorkProtocol` — чтобы сервисы зависели от абстракций,
+  а не от `BaseRepository` / SQLAlchemy
+
+## Быстрый старт
+
+Кит generic — вы объявляете **свои** модели поверх `Base` и миксинов:
+
+```python
+from dataclasses import dataclass
+
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from ormkit import (
+    Base, IntPkMixin, TimestampMixin,
+    BaseRepository, UnitOfWork,
+    make_engine, make_session_factory, init_schema,
+)
+
+
+# 1. Свои ORM-модели
+class User(Base, IntPkMixin, TimestampMixin):
+    __tablename__ = "users"
+    name: Mapped[str] = mapped_column(String(100))
+
+
+# 2. Свой доменный объект (dataclass / pydantic / dict — кит не знает тип)
+@dataclass
+class UserDTO:
+    name: str
+    id: int | None = None
+
+
+# 3. Свой репозиторий — переопределяем ТОЛЬКО хуки маппинга
+class UserRepository(BaseRepository[User, UserDTO]):
+    def to_domain(self, obj: User) -> UserDTO:
+        return UserDTO(id=obj.id, name=obj.name)
+
+    def to_orm(self, domain: UserDTO) -> User:
+        return User(name=domain.name)
+```
+
+### Конфигурация движка через DB-URL
+
+```python
+# sqlite по умолчанию (для локали / тестов), FK enforcement включён автоматически
+engine = make_engine("sqlite:///app.db")
+
+# та же строка кода на проде — просто другой URL, коду всё равно:
+engine = make_engine(default="postgresql://user:pass@host/db")
+# или через переменную окружения ORMKIT_DB_URL:
+engine = make_engine()
+
+init_schema(engine)
+session_factory = make_session_factory(engine)
+```
+
+### Работа через UnitOfWork
+
+```python
+with UnitOfWork(session_factory) as uow:
+    repo = UserRepository(uow.session, User)
+
+    saved = repo.add(UserDTO(name="Алиса"))        # flush -> id проставлен
+    found = repo.get(saved.id)                      # NotFoundError, если нет
+    everyone = repo.list()                          # фильтр: repo.list(name="Алиса")
+    repo.update(saved.id, name="Алиса Смит")
+    total = repo.count()
+
+    uow.commit()   # без commit транзакция не персистится
+# исключение в блоке -> автоматический rollback; сессия всегда закрывается
+```
+
+### DIP: сервис зависит от абстракции
+
+```python
+from ormkit import RepositoryProtocol
+
+def register_user(repo: RepositoryProtocol[UserDTO], name: str) -> UserDTO:
+    return repo.add(UserDTO(name=name))
+# в проде — UserRepository, в тестах — in-memory фейк, реализующий тот же протокол
+```
+
+## Архитектура
+
+```
+ormkit/
+├── __init__.py          # Public API + __version__
+├── exceptions.py        # OrmKitError, NotFoundError
+├── base.py              # Base, IntPkMixin, TimestampMixin
+├── engine.py            # make_engine, make_session_factory, init/drop_schema, dispose
+├── repository.py        # BaseRepository[TModel, TDomain]
+├── unit_of_work.py      # UnitOfWork
+└── protocols.py         # RepositoryProtocol, UnitOfWorkProtocol
+```
+
+## Тестирование
+
+```bash
+uv sync --extra dev
+uv run pytest -q          # зелёный, coverage >= 80%
+uv run ruff check .       # чисто
+```
+
+Тесты объявляют **собственные** демо-модели (`_User`, `_Post`) прямо в `conftest.py` —
+это доказывает, что кит generic и не тянет никакого приложения.
+
+## Диалект-нейтральность
+
+- **Один код — любая СУБД.** Меняется только DB-URL: `sqlite://` ↔ `postgresql://` ↔
+  `mysql://`. Прикладной код не трогается.
+- **sqlite FK enforcement.** Для sqlite `make_engine` навешивает `PRAGMA foreign_keys=ON`
+  (иначе sqlite молча игнорирует внешние ключи). Отключается флагом `foreign_keys=False`.
+- **Временные метки.** `TimestampMixin` использует `func.now()`, работающий и в sqlite,
+  и в postgres/mysql.
+- **Ленивое создание.** `make_engine("postgresql://...")` не коннектится — движок создаётся
+  без живого сервера.
+
+## Лицензия
+
+MIT

s_ormkit-0.0.1/README.md

@@ -0,0 +1,158 @@
+# s-ormkit
+
+Generic БД/ORM-инфраструктура для экосистемы S-kits на SQLAlchemy 2.0: диалект-нейтральный
+движок из DB-URL, Repository + UnitOfWork + DIP-протоколы.
+
+**Версия:** 0.0.1 (первый релиз)  
+**Лицензия:** MIT  
+**Зависимости:** `SQLAlchemy>=2.0` (и ничего больше)
+
+Кит НЕ знает ни о каком приложении. Прикладная логика получает БД-слой через ORM так,
+что не зависит от sqlite/диалекта: движок конфигурируется через DB-URL и заменяется на
+`postgresql://.../mysql://...` **без изменения кода**.
+
+## Что входит
+
+### Declarative-база и миксины (`base.py`)
+- `Base` — общий declarative base для моделей-наследников
+- `IntPkMixin` — целочисленный автоинкрементный первичный ключ
+- `TimestampMixin` — `created_at` / `updated_at` через `func.now()` (диалект-нейтрально)
+
+### Движок из DB-URL (`engine.py`)
+- `make_engine` — резолв URL (аргумент → env → default), для sqlite включает
+  `PRAGMA foreign_keys=ON`; `create_engine` ленив (postgres-URL создаётся без коннекта)
+- `make_session_factory` — `sessionmaker(expire_on_commit=False)`
+- `init_schema` / `drop_schema` — создать/удалить таблицы
+- `dispose_engine` — освободить пул соединений
+
+### Repository-паттерн (`repository.py`)
+- `BaseRepository[TModel, TDomain]` — generic CRUD: `add / get / get_or_none / list /
+  update / remove / count`
+- Маппинг ORM <-> domain через переопределяемые хуки `to_domain` / `to_orm`
+- Не коммитит сам (это делает `UnitOfWork`) — только `flush` для получения id
+
+### Транзакционная граница (`unit_of_work.py`)
+- `UnitOfWork` — контекст-менеджер: rollback при исключении, `close` всегда, `commit` явный
+
+### DIP-контракты (`protocols.py`)
+- `RepositoryProtocol` / `UnitOfWorkProtocol` — чтобы сервисы зависели от абстракций,
+  а не от `BaseRepository` / SQLAlchemy
+
+## Быстрый старт
+
+Кит generic — вы объявляете **свои** модели поверх `Base` и миксинов:
+
+```python
+from dataclasses import dataclass
+
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from ormkit import (
+    Base, IntPkMixin, TimestampMixin,
+    BaseRepository, UnitOfWork,
+    make_engine, make_session_factory, init_schema,
+)
+
+
+# 1. Свои ORM-модели
+class User(Base, IntPkMixin, TimestampMixin):
+    __tablename__ = "users"
+    name: Mapped[str] = mapped_column(String(100))
+
+
+# 2. Свой доменный объект (dataclass / pydantic / dict — кит не знает тип)
+@dataclass
+class UserDTO:
+    name: str
+    id: int | None = None
+
+
+# 3. Свой репозиторий — переопределяем ТОЛЬКО хуки маппинга
+class UserRepository(BaseRepository[User, UserDTO]):
+    def to_domain(self, obj: User) -> UserDTO:
+        return UserDTO(id=obj.id, name=obj.name)
+
+    def to_orm(self, domain: UserDTO) -> User:
+        return User(name=domain.name)
+```
+
+### Конфигурация движка через DB-URL
+
+```python
+# sqlite по умолчанию (для локали / тестов), FK enforcement включён автоматически
+engine = make_engine("sqlite:///app.db")
+
+# та же строка кода на проде — просто другой URL, коду всё равно:
+engine = make_engine(default="postgresql://user:pass@host/db")
+# или через переменную окружения ORMKIT_DB_URL:
+engine = make_engine()
+
+init_schema(engine)
+session_factory = make_session_factory(engine)
+```
+
+### Работа через UnitOfWork
+
+```python
+with UnitOfWork(session_factory) as uow:
+    repo = UserRepository(uow.session, User)
+
+    saved = repo.add(UserDTO(name="Алиса"))        # flush -> id проставлен
+    found = repo.get(saved.id)                      # NotFoundError, если нет
+    everyone = repo.list()                          # фильтр: repo.list(name="Алиса")
+    repo.update(saved.id, name="Алиса Смит")
+    total = repo.count()
+
+    uow.commit()   # без commit транзакция не персистится
+# исключение в блоке -> автоматический rollback; сессия всегда закрывается
+```
+
+### DIP: сервис зависит от абстракции
+
+```python
+from ormkit import RepositoryProtocol
+
+def register_user(repo: RepositoryProtocol[UserDTO], name: str) -> UserDTO:
+    return repo.add(UserDTO(name=name))
+# в проде — UserRepository, в тестах — in-memory фейк, реализующий тот же протокол
+```
+
+## Архитектура
+
+```
+ormkit/
+├── __init__.py          # Public API + __version__
+├── exceptions.py        # OrmKitError, NotFoundError
+├── base.py              # Base, IntPkMixin, TimestampMixin
+├── engine.py            # make_engine, make_session_factory, init/drop_schema, dispose
+├── repository.py        # BaseRepository[TModel, TDomain]
+├── unit_of_work.py      # UnitOfWork
+└── protocols.py         # RepositoryProtocol, UnitOfWorkProtocol
+```
+
+## Тестирование
+
+```bash
+uv sync --extra dev
+uv run pytest -q          # зелёный, coverage >= 80%
+uv run ruff check .       # чисто
+```
+
+Тесты объявляют **собственные** демо-модели (`_User`, `_Post`) прямо в `conftest.py` —
+это доказывает, что кит generic и не тянет никакого приложения.
+
+## Диалект-нейтральность
+
+- **Один код — любая СУБД.** Меняется только DB-URL: `sqlite://` ↔ `postgresql://` ↔
+  `mysql://`. Прикладной код не трогается.
+- **sqlite FK enforcement.** Для sqlite `make_engine` навешивает `PRAGMA foreign_keys=ON`
+  (иначе sqlite молча игнорирует внешние ключи). Отключается флагом `foreign_keys=False`.
+- **Временные метки.** `TimestampMixin` использует `func.now()`, работающий и в sqlite,
+  и в postgres/mysql.
+- **Ленивое создание.** `make_engine("postgresql://...")` не коннектится — движок создаётся
+  без живого сервера.
+
+## Лицензия
+
+MIT

s_ormkit-0.0.1/ormkit/__init__.py

@@ -0,0 +1,56 @@
+"""s-ormkit — generic БД/ORM-инфраструктура для экосистемы S-kits.
+
+Чистый инфраструктурный кит на SQLAlchemy 2.0 БЕЗ завязок на конкретное приложение.
+Задача — дать прикладной логике БД-слой через ORM так, чтобы она НЕ знала про
+sqlite/диалект: движок конфигурируется через DB-URL и заменяется на
+`postgresql://.../mysql://...` без изменения кода.
+
+**Ядро (v0.0.1):**
+- Declarative-база и миксины: `Base`, `IntPkMixin`, `TimestampMixin`
+- Движок из DB-URL, диалект-нейтрально: `make_engine`, `make_session_factory`,
+  `init_schema`, `drop_schema`, `dispose_engine`
+- Repository-паттерн: `BaseRepository` (маппинг ORM <-> domain через хуки)
+- Транзакционная граница: `UnitOfWork`
+- DIP-контракты: `RepositoryProtocol`, `UnitOfWorkProtocol`
+
+Зависимости: SQLAlchemy>=2.0 (и ничего больше).
+"""
+from __future__ import annotations
+
+from ormkit.base import Base, IntPkMixin, TimestampMixin
+from ormkit.engine import (
+    dispose_engine,
+    drop_schema,
+    init_schema,
+    make_engine,
+    make_session_factory,
+)
+from ormkit.exceptions import NotFoundError, OrmKitError
+from ormkit.protocols import RepositoryProtocol, UnitOfWorkProtocol
+from ormkit.repository import BaseRepository
+from ormkit.unit_of_work import UnitOfWork
+
+__version__ = "0.0.1"
+
+__all__ = [
+    # base
+    "Base",
+    "IntPkMixin",
+    "TimestampMixin",
+    # engine
+    "make_engine",
+    "make_session_factory",
+    "init_schema",
+    "drop_schema",
+    "dispose_engine",
+    # repository
+    "BaseRepository",
+    # unit of work
+    "UnitOfWork",
+    # protocols
+    "RepositoryProtocol",
+    "UnitOfWorkProtocol",
+    # exceptions
+    "OrmKitError",
+    "NotFoundError",
+]

s_ormkit-0.0.1/ormkit/base.py

@@ -0,0 +1,50 @@
+"""Declarative-база SQLAlchemy 2.0 и переиспользуемые миксины для моделей.
+
+Диалект-нейтрально: `func.now()` работает и в sqlite, и в postgres/mysql, поэтому
+модели наследников не завязаны на конкретную СУБД.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, func
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    """Общий declarative base для всех моделей-наследников кита."""
+
+    pass
+
+
+class IntPkMixin:
+    """Миксин целочисленного автоинкрементного первичного ключа."""
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+
+
+class TimestampMixin:
+    """Миксин временных меток создания/обновления.
+
+    `created_at` проставляется БД на INSERT, `updated_at` — на INSERT и на UPDATE.
+    Использует `func.now()`, что диалект-нейтрально.
+    """
+
+    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(),
+    )
+
+
+__all__ = [
+    "Base",
+    "IntPkMixin",
+    "TimestampMixin",
+    "Mapped",
+    "mapped_column",
+]

s_ormkit-0.0.1/ormkit/engine.py

@@ -0,0 +1,86 @@
+"""Создание движка и фабрики сессий из DB-URL, диалект-нейтрально.
+
+Движок конфигурируется через DB-URL: по умолчанию можно подать sqlite, заменяемо на
+`postgresql://.../mysql://...` БЕЗ изменения прикладного кода. `create_engine` ленив —
+движок к postgres/mysql создаётся без живого сервера и без коннекта.
+"""
+from __future__ import annotations
+
+import os
+
+from sqlalchemy import Engine, create_engine, event
+from sqlalchemy.orm import Session, sessionmaker
+
+from ormkit.base import Base
+from ormkit.exceptions import OrmKitError
+
+
+def make_engine(
+    url: str | None = None,
+    *,
+    env_var: str = "ORMKIT_DB_URL",
+    default: str | None = None,
+    echo: bool = False,
+    foreign_keys: bool = True,
+) -> Engine:
+    """Создать движок из DB-URL.
+
+    Резолв URL по приоритету: явный аргумент → `os.environ[env_var]` → `default`.
+    Если ничего не задано — `OrmKitError`.
+
+    Для sqlite при `foreign_keys=True` навешивается обработчик `connect`, выполняющий
+    `PRAGMA foreign_keys=ON` (иначе sqlite молча игнорирует внешние ключи). Для прочих
+    диалектов PRAGMA не применяется.
+
+    `create_engine` ленив: движок к недоступному postgres/mysql создаётся без коннекта.
+    """
+    resolved = url if url is not None else os.environ.get(env_var, default)
+    if not resolved:
+        raise OrmKitError(
+            "Не задан DB-URL: передайте url аргументом, "
+            f"установите переменную окружения {env_var} или задайте default."
+        )
+
+    engine = create_engine(resolved, echo=echo)
+
+    if foreign_keys and engine.dialect.name == "sqlite":
+
+        @event.listens_for(engine, "connect")
+        def _enable_sqlite_fk(dbapi_connection, connection_record):
+            cursor = dbapi_connection.cursor()
+            cursor.execute("PRAGMA foreign_keys=ON")
+            cursor.close()
+
+    return engine
+
+
+def make_session_factory(engine: Engine) -> sessionmaker[Session]:
+    """Создать фабрику сессий, привязанную к движку.
+
+    `expire_on_commit=False`, чтобы объекты оставались доступны после commit.
+    """
+    return sessionmaker(bind=engine, expire_on_commit=False)
+
+
+def init_schema(engine: Engine, base: type = Base) -> None:
+    """Создать все таблицы, зарегистрированные в metadata указанного base."""
+    base.metadata.create_all(engine)
+
+
+def drop_schema(engine: Engine, base: type = Base) -> None:
+    """Удалить все таблицы, зарегистрированные в metadata указанного base."""
+    base.metadata.drop_all(engine)
+
+
+def dispose_engine(engine: Engine) -> None:
+    """Освободить пул соединений движка."""
+    engine.dispose()
+
+
+__all__ = [
+    "make_engine",
+    "make_session_factory",
+    "init_schema",
+    "drop_schema",
+    "dispose_engine",
+]

s_ormkit-0.0.1/ormkit/exceptions.py

@@ -0,0 +1,20 @@
+"""Исключения кита ormkit."""
+from __future__ import annotations
+
+
+class OrmKitError(Exception):
+    """Базовое исключение кита ormkit."""
+
+    pass
+
+
+class NotFoundError(OrmKitError):
+    """Сущность не найдена по первичному ключу."""
+
+    pass
+
+
+__all__ = [
+    "OrmKitError",
+    "NotFoundError",
+]

s_ormkit-0.0.1/ormkit/protocols.py

@@ -0,0 +1,54 @@
+"""DIP-контракты: прикладные сервисы зависят от абстракций, а не от BaseRepository/SQLAlchemy.
+
+Protocol'ы позволяют внедрять любую реализацию репозитория/UoW (в т.ч. in-memory фейки
+для тестов), не завязываясь на конкретный класс кита.
+"""
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any, Protocol, TypeVar, runtime_checkable
+
+TDomain = TypeVar("TDomain")
+
+
+@runtime_checkable
+class RepositoryProtocol(Protocol[TDomain]):
+    """Контракт репозитория для прикладного слоя."""
+
+    def add(self, domain: TDomain) -> TDomain: ...
+
+    def get(self, id: Any) -> TDomain: ...
+
+    def get_or_none(self, id: Any) -> TDomain | None: ...
+
+    def list(self, **filters: Any) -> list[TDomain]: ...
+
+    def update(self, id: Any, **changes: Any) -> TDomain: ...
+
+    def remove(self, id: Any) -> None: ...
+
+    def count(self, **filters: Any) -> int: ...
+
+
+@runtime_checkable
+class UnitOfWorkProtocol(Protocol):
+    """Контракт транзакционной границы для прикладного слоя."""
+
+    def __enter__(self) -> UnitOfWorkProtocol: ...
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None: ...
+
+    def commit(self) -> None: ...
+
+    def rollback(self) -> None: ...
+
+
+__all__ = [
+    "RepositoryProtocol",
+    "UnitOfWorkProtocol",
+]