nlbone 0.3.3__tar.gz → 0.4.0__tar.gz

{nlbone-0.3.3 → nlbone-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nlbone
-Version: 0.3.3
+Version: 0.4.0
 Summary: Backbone package for interfaces and infrastructure in Python projects
 Author-email: Amir Hosein Kahkbazzadeh <a.khakbazzadeh@gmail.com>
 License: MIT

{nlbone-0.3.3 → nlbone-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nlbone"
-version = "0.3.3"
+version = "0.4.0"
 description = "Backbone package for interfaces and infrastructure in Python projects"
 readme = "README.md"
 requires-python = ">=3.10"

nlbone-0.4.0/src/nlbone/adapters/db/sqlalchemy/__init__.py

@@ -0,0 +1,4 @@
+from .query_builder import get_paginated_response, apply_pagination
+from .engine import init_sync_engine, init_async_engine, sync_ping, sync_session, async_ping, async_session
+from .repository import SqlAlchemyRepository, AsyncSqlAlchemyRepository
+from .uow import SqlAlchemyUnitOfWork, AsyncSqlAlchemyUnitOfWork

{nlbone-0.3.3 → nlbone-0.4.0}/src/nlbone/adapters/db/sqlalchemy/engine.py

@@ -117,3 +117,14 @@ def sync_ping() -> None:
     with eng.connect() as conn:
         conn.execute(text("SELECT 1"))
 
+def get_async_session_factory() -> async_sessionmaker[AsyncSession]:
+    if _async_session_factory is None:
+        init_async_engine()
+    assert _async_session_factory is not None
+    return _async_session_factory
+
+def get_sync_session_factory() -> sessionmaker[Session]:
+    if _sync_session_factory is None:
+        init_sync_engine()
+    assert _sync_session_factory is not None
+    return _sync_session_factory

nlbone-0.4.0/src/nlbone/adapters/db/sqlalchemy/repository.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+from typing import Generic, Iterable, Optional, Type, TypeVar, List
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Session
+from nlbone.core.ports.repo import Repository, AsyncRepository
+
+T = TypeVar("T")
+
+
+class SqlAlchemyRepository(Repository[T], Generic[T]):
+    def __init__(self, session: Session, model: Type[T]) -> None:
+        self.session = session
+        self.model = model
+
+    def get(self, id) -> Optional[T]:
+        return self.session.get(self.model, id)
+
+    def add(self, obj: T) -> None:
+        self.session.add(obj)
+
+    def remove(self, obj: T) -> None:
+        self.session.delete(obj)
+
+    def list(self, *, limit: int | None = None, offset: int = 0) -> Iterable[T]:
+        q = self.session.query(self.model).offset(offset)
+        if limit is not None:
+            q = q.limit(limit)
+        return q.all()
+
+
+class AsyncSqlAlchemyRepository(AsyncRepository, Generic[T]):
+    def __init__(self, session: AsyncSession, model: Type[T]) -> None:
+        self.session = session
+        self.model = model
+
+    async def get(self, id) -> Optional[T]:
+        return await self.session.get(self.model, id)
+
+    def add(self, obj: T) -> None:
+        self.session.add(obj)
+
+    async def remove(self, obj: T) -> None:
+        await self.session.delete(obj)
+
+    async def list(self, *, limit: int | None = None, offset: int = 0) -> List[T]:
+        stmt = select(self.model).offset(offset)
+        if limit is not None:
+            stmt = stmt.limit(limit)
+        res = await self.session.execute(stmt)
+        return list(res.scalars().all())

nlbone-0.4.0/src/nlbone/adapters/db/sqlalchemy/uow.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession
+from sqlalchemy.orm import Session, sessionmaker
+from nlbone.core.ports.uow import UnitOfWork
+from nlbone.core.ports.uow import AsyncUnitOfWork as AsyncUnitOfWorkPort
+
+
+class SqlAlchemyUnitOfWork(UnitOfWork):
+    """sync UoW for SQLAlchemy."""
+
+    def __init__(self, session_factory: sessionmaker) -> None:
+        self._session_factory = session_factory
+        self.session: Session | None = None
+
+    def __enter__(self) -> "SqlAlchemyUnitOfWork":
+        self.session = self._session_factory()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        try:
+            if exc_type is None:
+                self.commit()
+            else:
+                self.rollback()
+        finally:
+            if self.session is not None:
+                self.session.close()
+                self.session = None
+
+    def commit(self) -> None:
+        if self.session:
+            self.session.commit()
+
+    def rollback(self) -> None:
+        if self.session:
+            self.session.rollback()
+
+
+class AsyncSqlAlchemyUnitOfWork(AsyncUnitOfWorkPort):
+    """Transactional boundary for async SQLAlchemy."""
+
+    def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
+        self._sf = session_factory
+        self.session: Optional[AsyncSession] = None
+
+    async def __aenter__(self) -> "AsyncSqlAlchemyUnitOfWork":
+        self.session = self._sf()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        try:
+            if exc_type is None:
+                await self.commit()
+            else:
+                await self.rollback()
+        finally:
+            if self.session is not None:
+                await self.session.close()
+                self.session = None
+
+    async def commit(self) -> None:
+        if self.session:
+            await self.session.commit()
+
+    async def rollback(self) -> None:
+        if self.session:
+            await self.session.rollback()

nlbone-0.4.0/src/nlbone/adapters/messaging/__init__.py

@@ -0,0 +1 @@
+from .event_bus import InMemoryEventBus

nlbone-0.4.0/src/nlbone/adapters/messaging/event_bus.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+from collections import defaultdict
+from typing import Callable, Dict, Iterable, List
+from nlbone.core.domain.base import DomainEvent
+from nlbone.core.ports.event_bus import EventBusPort
+
+class InMemoryEventBus(EventBusPort):
+    def __init__(self) -> None:
+        self._handlers: Dict[str, List[Callable[[DomainEvent], None]]] = defaultdict(list)
+
+    def publish(self, events: Iterable[DomainEvent]) -> None:
+        for evt in events:
+            for h in self._handlers.get(evt.name, []):
+                try:
+                    h(evt)
+                except Exception:
+                    pass
+
+    def subscribe(self, event_name: str, handler: Callable[[DomainEvent], None]) -> None:
+        self._handlers[event_name].append(handler)

{nlbone-0.3.3 → nlbone-0.4.0}/src/nlbone/config/settings.py

@@ -66,11 +66,18 @@ class Settings(BaseSettings):
     POSTGRES_DB_DSN: str = Field(default="postgresql+asyncpg://user:pass@localhost:5432/nlbone",
                                  validation_alias=AliasChoices("NLBONE_POSTGRES_DB_DSN",
                                                                "POSTGRES_DB_DSN", "DATABASE_URL", "DB_DSN"))
+    DB_ECHO: bool = Field(default=False)
+    DB_POOL_SIZE: int = Field(default=5)
+    DB_MAX_OVERFLOW: int = Field(default=10)
 
     # ---------------------------
     # Messaging / Cache
     # ---------------------------
     REDIS_URL: str = Field(default="redis://localhost:6379/0")
+    # --- Event bus / Outbox ---
+    EVENT_BUS_BACKEND: Literal["inmemory"] = Field(default="inmemory")
+    OUTBOX_ENABLED: bool = Field(default=False)
+    OUTBOX_POLL_INTERVAL_MS: int = Field(default=500)
 
     # ---------------------------
     # UPLOADCHI

{nlbone-0.3.3 → nlbone-0.4.0}/src/nlbone/container.py

@@ -3,15 +3,30 @@ from typing import Any, Mapping, Optional
 
 from dependency_injector import containers, providers
 
+from nlbone.adapters.db.sqlalchemy import SqlAlchemyUnitOfWork, AsyncUnitOfWork
+from nlbone.adapters.db.sqlalchemy.engine import get_sync_session_factory, get_async_session_factory
 from nlbone.adapters.http_clients.uploadchi import UploadchiClient
 from nlbone.adapters.http_clients.uploadchi_async import UploadchiAsyncClient
 from nlbone.adapters.auth.keycloak import KeycloakAuthService
+from nlbone.adapters.messaging import InMemoryEventBus
+from nlbone.core.ports import EventBusPort
 from nlbone.core.ports.files import FileServicePort, AsyncFileServicePort
 
 
 class Container(containers.DeclarativeContainer):
     config = providers.Configuration(strict=False)
 
+    sync_session_factory = providers.Singleton(get_sync_session_factory)
+    async_session_factory = providers.Singleton(get_async_session_factory)
+
+    # --- UoW ---
+    uow = providers.Factory(SqlAlchemyUnitOfWork, session_factory=sync_session_factory)
+    async_uow = providers.Factory(AsyncUnitOfWork, session_factory=async_session_factory)
+
+    # --- Event bus ---
+    event_bus: providers.Singleton[EventBusPort] = providers.Singleton(InMemoryEventBus)
+
+    # --- Services ---
     auth: providers.Singleton[KeycloakAuthService] = providers.Singleton(KeycloakAuthService, settings=config)
     file_service: providers.Singleton[FileServicePort] = providers.Singleton(UploadchiClient)
     afiles_service: providers.Singleton[AsyncFileServicePort] = providers.Singleton(UploadchiAsyncClient)

nlbone-0.4.0/src/nlbone/core/application/events.py

@@ -0,0 +1,16 @@
+from typing import Iterable, Sequence
+from nlbone.core.domain.base import AggregateRoot, DomainEvent
+from nlbone.core.ports.event_bus import EventBusPort
+
+def collect_events(*aggregates: Iterable[AggregateRoot]) -> list[DomainEvent]:
+    events: list[DomainEvent] = []
+    for agg in aggregates:
+        if isinstance(agg, AggregateRoot):
+            events.extend(agg.pull_events())
+        else:
+            for a in agg:
+                events.extend(a.pull_events())
+    return events
+
+def publish_events(bus: EventBusPort, events: Sequence[DomainEvent]) -> None:
+    if events: bus.publish(events)

nlbone-0.4.0/src/nlbone/core/application/use_case.py

@@ -0,0 +1,10 @@
+from typing import Protocol, TypeVar
+
+
+InT = TypeVar("InT"); OutT = TypeVar("OutT")
+
+class UseCase(Protocol):
+    def __call__(self, command: InT) -> OutT: ...
+
+class AsyncUseCase(Protocol):
+    async def __call__(self, command: InT) -> OutT: ...

nlbone-0.4.0/src/nlbone/core/domain/base.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Generic, List, TypeVar
+
+TId = TypeVar("TId")
+
+
+class DomainError(Exception):
+    """Base domain exception."""
+
+
+@dataclass(frozen=True)
+class DomainEvent:
+    """Immutable domain event."""
+    occurred_at: datetime = datetime.now(timezone.utc)
+
+    @property
+    def name(self):
+        return self.__class__.__name__
+
+
+class ValueObject:
+    """Base for value objects (immutable in practice)."""
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, self.__class__) and self.__dict__ == other.__dict__
+
+    def __hash__(self) -> int:  # allow in sets/dicts
+        return hash(tuple(sorted(self.__dict__.items())))
+
+
+class Entity(Generic[TId]):
+    id: TId
+
+
+class AggregateRoot(Entity[TId]):
+    """Aggregate root with domain event collection."""
+    def __init__(self, *args, **kwargs) -> None:
+        self._domain_events: List[DomainEvent] = []
+
+    def _raise(self, event: DomainEvent) -> None:
+        self._domain_events.append(event)
+
+    def pull_events(self) -> List[DomainEvent]:
+        events = list(self._domain_events)
+        self._domain_events.clear()
+        return events

nlbone-0.4.0/src/nlbone/core/ports/__init__.py

@@ -0,0 +1,5 @@
+from .auth import AuthService
+from .repo import Repository, AsyncRepository
+from .files import FileServicePort, AsyncFileServicePort
+from .uow import UnitOfWork, AsyncUnitOfWork
+from .event_bus import EventBusPort

nlbone-0.4.0/src/nlbone/core/ports/event_bus.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+from typing import Callable, Iterable, Protocol
+from nlbone.core.domain.base import DomainEvent
+
+class EventBusPort(Protocol):
+    def publish(self, events: Iterable[DomainEvent]) -> None: ...
+    def subscribe(self, event_name: str, handler: Callable[[DomainEvent], None]) -> None: ...

nlbone-0.4.0/src/nlbone/core/ports/repo.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+from typing import Iterable, Optional, Protocol, TypeVar, List
+
+T = TypeVar("T")
+
+class Repository(Protocol[T]):  # ← نه Protocol, Generic[T]
+    def get(self, id) -> Optional[T]: ...
+    def add(self, obj: T) -> None: ...
+    def remove(self, obj: T) -> None: ...
+    def list(self, *, limit: int | None = None, offset: int = 0) -> Iterable[T]: ...
+
+class AsyncRepository(Protocol[T]):
+    async def get(self, id) -> Optional[T]: ...
+    def add(self, obj: T) -> None: ...
+    async def remove(self, obj: T) -> None: ...
+    async def list(self, *, limit: int | None = None, offset: int = 0) -> List[T]: ...

nlbone-0.4.0/src/nlbone/core/ports/uow.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+from typing import Protocol, runtime_checkable
+
+@runtime_checkable
+class UnitOfWork(Protocol):
+    def __enter__(self) -> "UnitOfWork": ...
+    def __exit__(self, exc_type, exc, tb) -> None: ...
+    def commit(self) -> None: ...
+    def rollback(self) -> None: ...
+
+@runtime_checkable
+class AsyncUnitOfWork(Protocol):
+    async def __aenter__(self) -> "AsyncUnitOfWork": ...
+    async def __aexit__(self, exc_type, exc, tb) -> None: ...
+    async def commit(self) -> None: ...
+    async def rollback(self) -> None: ...

{nlbone-0.3.3 → nlbone-0.4.0}/src/nlbone/interfaces/api/dependencies/__init__.py

@@ -1,2 +1,3 @@
 from .db import get_session, get_async_session
-from .auth import has_access, client_has_access, current_client_id, current_user_id, current_request, user_authenticated
+from .auth import has_access, client_has_access, current_client_id, current_user_id, current_request, user_authenticated
+from .uow import get_uow, get_async_uow

nlbone-0.4.0/src/nlbone/interfaces/api/dependencies/uow.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+from collections.abc import Iterator
+from typing import AsyncIterator
+
+from fastapi import Request
+
+from nlbone.adapters.db.sqlalchemy import AsyncSqlAlchemyUnitOfWork
+from nlbone.core.ports.uow import UnitOfWork, AsyncUnitOfWork
+
+
+def get_uow(request: Request) -> Iterator[UnitOfWork]:
+    """
+    Uses DI container mounted at app.state.container to create a UoW per request.
+    Assumes container.uow is a provider returning SqlAlchemyUnitOfWork(session_factory).
+    """
+    container = getattr(request.app.state, "container", None)
+    if container is None or not hasattr(container, "uow"):
+        raise RuntimeError("Container with 'uow' provider not configured on app.state.container")
+
+    uow = container.uow()
+    with uow as _uow:
+        yield _uow
+
+
+async def get_async_uow(request: Request) -> AsyncIterator[AsyncUnitOfWork]:
+    container = getattr(request.app.state, "container", None)
+    if container is None or not hasattr(container, "async_uow"):
+        raise RuntimeError("Container.async_uow provider not configured")
+    uow: AsyncSqlAlchemyUnitOfWork = container.async_uow()
+    async with uow as _uow:
+        yield _uow

nlbone-0.3.3/src/nlbone/adapters/db/sqlalchemy/__init__.py

@@ -1 +0,0 @@
-from .query_builder import get_paginated_response, apply_pagination

nlbone-0.3.3/src/nlbone/core/ports/__init__.py

@@ -1 +0,0 @@
-from .auth import AuthService