forktex-core-py 0.1.0__tar.gz

forktex_core_py-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: forktex-core-py
+Version: 0.1.0
+Summary: Shared database (PostgreSQL) and cache (Redis) primitives for the FORKTEX ecosystem
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: pydantic>=2.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.7.0; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis[hiredis]>=5.0; extra == 'redis'

forktex_core_py-0.1.0/README.md

@@ -0,0 +1,35 @@
+# forktex-core
+
+Shared database (PostgreSQL) and cache (Redis) primitives for the FORKTEX ecosystem.
+
+## Install
+
+```bash
+pip install forktex-core            # psql only
+pip install forktex-core[redis]     # psql + redis
+```
+
+## PostgreSQL
+
+```python
+from forktex_core.psql import init_engine, close_engine, get_session, BaseDBModel, TimestampMixin, AuditMixin
+
+# Initialize in app lifespan
+init_engine("postgresql+asyncpg://user:pass@localhost/db")
+
+# Use in services
+async with get_session() as session:
+    user = await session.get(User, user_id)
+```
+
+## Redis
+
+```python
+from forktex_core.redis import init, close, cached
+
+await init("redis://localhost:6379/0")
+
+@cached(ttl=300)
+async def get_profile(user_id: str):
+    ...
+```

forktex_core_py-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "forktex-core-py"
+version = "0.1.0"
+description = "Shared database (PostgreSQL) and cache (Redis) primitives for the FORKTEX ecosystem"
+requires-python = ">=3.11"
+dependencies = [
+    "sqlalchemy[asyncio]>=2.0",
+    "asyncpg>=0.29",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+redis = ["redis[hiredis]>=5.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.7.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forktex_core"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "session"

forktex_core_py-0.1.0/src/forktex_core/__init__.py

@@ -0,0 +1,3 @@
+"""FORKTEX Core — shared database and cache primitives."""
+
+__version__ = "0.1.0"

forktex_core_py-0.1.0/src/forktex_core/psql/__init__.py

@@ -0,0 +1,47 @@
+"""PostgreSQL async primitives: connection, base models, CRUD utilities."""
+
+from forktex_core.psql.connection import (
+    init_engine,
+    close_engine,
+    get_session,
+    with_transactional_session,
+)
+from forktex_core.psql.models import (
+    BaseDBModel,
+    ReprMixin,
+    TimestampMixin,
+    AuditMixin,
+    JsonModelColumn,
+)
+from forktex_core.psql.crud import (
+    PageResponse,
+    ScrollResponse,
+    ConflictError,
+    get,
+    list_all,
+    paginate,
+    paginate_scroll,
+    find_one_by,
+    create,
+)
+
+__all__ = [
+    "init_engine",
+    "close_engine",
+    "get_session",
+    "with_transactional_session",
+    "BaseDBModel",
+    "ReprMixin",
+    "TimestampMixin",
+    "AuditMixin",
+    "JsonModelColumn",
+    "PageResponse",
+    "ScrollResponse",
+    "ConflictError",
+    "get",
+    "list_all",
+    "paginate",
+    "paginate_scroll",
+    "find_one_by",
+    "create",
+]

forktex_core_py-0.1.0/src/forktex_core/psql/connection.py

@@ -0,0 +1,112 @@
+"""Async SQLAlchemy engine and session management for PostgreSQL.
+
+Unified connection module ForkTex Ecosystem api Archtypes
+Supports configurable engine kwargs for pool tuning.
+
+Usage:
+    # Basic (network/cloud style — default pool settings)
+    init_engine("postgresql+asyncpg://user:pass@host/db")
+
+    # With pool tuning (intelligence style)
+    init_engine(
+        "postgresql+asyncpg://user:pass@host/db",
+        pool_size=20,
+        max_overflow=10,
+        pool_pre_ping=True,
+    )
+
+    # FastAPI lifespan
+    @asynccontextmanager
+    async def lifespan(app):
+        init_engine(settings.db_url)
+        yield
+        await close_engine()
+
+    # Route handler
+    async def my_route(session: AsyncSession = Depends(get_session)):
+        ...
+
+    # Service layer
+    @with_transactional_session
+    async def my_service(session: AsyncSession, ...):
+        ...
+"""
+
+from contextlib import asynccontextmanager
+import functools
+from typing import AsyncGenerator, Optional
+
+from sqlalchemy.ext.asyncio import (
+    async_sessionmaker,
+    create_async_engine,
+    AsyncSession,
+    AsyncEngine,
+)
+
+
+# Module-level references (set by init_engine).
+engine: Optional[AsyncEngine] = None
+_async_sessionmaker: Optional[async_sessionmaker] = None
+
+
+def init_engine(db_url: str, *, echo: bool = False, **engine_kwargs) -> async_sessionmaker:
+    """Initialize the async engine and session factory.
+
+    Args:
+        db_url: SQLAlchemy async database URL (e.g. postgresql+asyncpg://...).
+        echo: Echo SQL statements to stdout.
+        **engine_kwargs: Forwarded to create_async_engine (pool_size, max_overflow,
+            pool_pre_ping, pool_recycle, etc.).
+
+    Returns:
+        The configured async_sessionmaker.
+    """
+    global engine, _async_sessionmaker
+    engine = create_async_engine(db_url, echo=echo, **engine_kwargs)
+    _async_sessionmaker = async_sessionmaker(bind=engine, expire_on_commit=False, class_=AsyncSession)
+    return _async_sessionmaker
+
+
+async def close_engine() -> None:
+    """Dispose the engine on app shutdown."""
+    global engine
+    if engine is not None:
+        await engine.dispose()
+        engine = None
+
+
+@asynccontextmanager
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    """Yield a transactional async session. Commits on success, rolls back on error.
+
+    Can be used as a FastAPI dependency via ``Depends(get_session)`` or as a
+    plain async context manager in service code.
+    """
+    assert _async_sessionmaker is not None, "Engine/sessionmaker not initialized — call init_engine() first"
+    async with _async_sessionmaker() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+
+def with_transactional_session(func):
+    """Decorator that auto-injects a session as the first arg if not already provided.
+
+    If the first positional arg is already an ``AsyncSession``, or ``session``
+    is in kwargs, the function is called as-is. Otherwise a new session is
+    created via ``get_session()``.
+    """
+
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        if args and isinstance(args[0], AsyncSession):
+            return await func(*args, **kwargs)
+        if "session" in kwargs:
+            return await func(*args, **kwargs)
+        async with get_session() as session:
+            return await func(session, *args, **kwargs)
+
+    return wrapper

forktex_core_py-0.1.0/src/forktex_core/psql/crud.py

@@ -0,0 +1,253 @@
+"""Generic async CRUD utilities for SQLAlchemy.
+
+Provides paginated queries (page-based and cursor-based), single-record
+lookups, and creation helpers with conflict detection.
+"""
+
+from math import ceil
+from typing import Any, Callable, Generic, List, Optional, Type, TypeVar
+
+from pydantic import BaseModel
+from sqlalchemy import ColumnElement, Select, func, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import InstrumentedAttribute
+
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+
+# ---------------------------------------------------------------------------
+# Response containers
+# ---------------------------------------------------------------------------
+
+
+class PageResponse(BaseModel, Generic[T]):
+    """Page-based pagination response."""
+
+    data: list[T]
+    has_more: bool
+    limit: int
+    total_count: Optional[int] = None
+    current_page: Optional[int] = None
+    total_pages: Optional[int] = None
+
+    def apply_to_page_data(self, map_func: Callable[[T], U]) -> "PageResponse[U]":
+        return PageResponse[U](
+            data=[map_func(item) for item in self.data],
+            has_more=self.has_more,
+            limit=self.limit,
+            total_count=self.total_count,
+            current_page=self.current_page,
+            total_pages=self.total_pages,
+        )
+
+
+class ScrollResponse(BaseModel, Generic[T]):
+    """Cursor-based (scroll) pagination response."""
+
+    data: list[T]
+    limit: int
+    has_more: bool
+    next_cursor: str | None = None
+
+    def apply_to_scroll_data(self, map_func: Callable[[T], U]) -> "ScrollResponse[U]":
+        return ScrollResponse[U](
+            data=[map_func(item) for item in self.data],
+            limit=self.limit,
+            has_more=self.has_more,
+            next_cursor=self.next_cursor,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class ConflictError(Exception):
+    """Raised when an INSERT/UPDATE violates a uniqueness constraint."""
+
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Single-record operations
+# ---------------------------------------------------------------------------
+
+
+async def get(
+    session: AsyncSession,
+    model: Type[T],
+    value: Any,
+    *,
+    key: str = "id",
+    options: list | None = None,
+) -> T | None:
+    """Retrieve a single record by column value (default: primary key)."""
+    if not hasattr(model, key):
+        raise AttributeError(f"{model.__name__} has no attribute '{key}'")
+
+    stmt = select(model).where(getattr(model, key) == value)
+    if options:
+        stmt = stmt.options(*options)
+    result = await session.execute(stmt)
+    return result.scalar_one_or_none()
+
+
+async def find_one_by(
+    session: AsyncSession,
+    model: Type[T],
+    **filters,
+) -> Optional[T]:
+    """Find a single record matching all keyword filters."""
+    stmt = select(model).filter_by(**filters)
+    res = await session.execute(stmt)
+    return res.scalar_one_or_none()
+
+
+async def list_all(
+    session: AsyncSession,
+    model: Type[T],
+    *,
+    options: list | None = None,
+) -> List[T]:
+    """Return all records of a model (use sparingly on large tables)."""
+    stmt = select(model)
+    if options:
+        stmt = stmt.options(*options)
+    res = await session.execute(stmt)
+    return list(res.scalars().all())
+
+
+async def create(
+    session: AsyncSession,
+    model: Type[T],
+    **values,
+) -> T:
+    """Create a new record. Raises ``ConflictError`` on integrity violation."""
+    obj = model(**values)
+    session.add(obj)
+    try:
+        await session.flush()
+    except IntegrityError as exc:
+        raise ConflictError(str(exc)) from exc
+    await session.refresh(obj)
+    return obj
+
+
+# ---------------------------------------------------------------------------
+# Paginated queries
+# ---------------------------------------------------------------------------
+
+
+async def paginate(
+    session: AsyncSession,
+    model: Type[T],
+    page: int = 1,
+    page_size: int = 100,
+    conditions: Optional[List[ColumnElement]] = None,
+    order_by: Optional[list[ColumnElement]] = None,
+    joins: Optional[list[InstrumentedAttribute]] = None,
+    options: list | None = None,
+) -> "PageResponse[T]":
+    """Page-based pagination with total count."""
+    stmt = select(model)
+
+    if options:
+        stmt = stmt.options(*options)
+    if joins:
+        for join in joins:
+            stmt = stmt.outerjoin(join)
+    if conditions:
+        stmt = stmt.where(*conditions)
+    if order_by:
+        stmt = stmt.order_by(*order_by)
+
+    return await _paginate_query(session, stmt, page, page_size)
+
+
+async def paginate_scroll(
+    session: AsyncSession,
+    model: Type[T],
+    limit: int = 20,
+    conditions: Optional[List[ColumnElement]] = None,
+    order_by: Optional[list[ColumnElement]] = None,
+    joins: Optional[list[InstrumentedAttribute]] = None,
+    options: list | None = None,
+) -> "ScrollResponse[T]":
+    """Cursor-based (scroll) pagination. Fetches limit+1 to detect has_more."""
+    stmt = select(model)
+
+    if options:
+        stmt = stmt.options(*options)
+    if joins:
+        for join in joins:
+            stmt = stmt.outerjoin(join)
+    if conditions:
+        stmt = stmt.where(*conditions)
+    if order_by:
+        stmt = stmt.order_by(*order_by)
+
+    return await _paginate_scroll_query(session, stmt, limit)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+async def _paginate_query(
+    session: AsyncSession,
+    query: Select[Any],
+    page: int = 1,
+    page_size: int = 100,
+) -> "PageResponse[T]":
+    if page < 1:
+        page = 1
+    if page_size < 1:
+        page_size = 10
+
+    total_count_stmt = select(func.count()).select_from(query.subquery())
+    total_count = (await session.execute(total_count_stmt)).scalar_one()
+
+    offset = (page - 1) * page_size
+    paginated_stmt = query.offset(offset).limit(page_size)
+    result = await session.execute(paginated_stmt)
+    data = list(result.scalars().all())
+
+    has_more = (page * page_size) < total_count
+    total_pages = ceil(total_count / page_size) if page_size else 1
+
+    return PageResponse(
+        data=data,
+        has_more=has_more,
+        limit=page_size,
+        total_count=total_count,
+        current_page=page,
+        total_pages=total_pages,
+    )
+
+
+async def _paginate_scroll_query(
+    session: AsyncSession,
+    query: Select[Any],
+    limit: int = 20,
+) -> "ScrollResponse[T]":
+    if limit < 1:
+        limit = 20
+
+    scroll_stmt = query.limit(limit + 1)
+    result = await session.execute(scroll_stmt)
+    data = list(result.scalars().all())
+
+    has_more = len(data) > limit
+    if has_more:
+        data = data[:limit]
+
+    return ScrollResponse(
+        data=data,
+        has_more=has_more,
+        limit=limit,
+    )

forktex_core_py-0.1.0/src/forktex_core/psql/models.py

@@ -0,0 +1,167 @@
+"""SQLAlchemy base models and mixins.
+
+Extracted from the FORKTEX ecosystem. All API projects (network, cloud,
+workflow, intelligence) share these base classes.
+
+- ``BaseDBModel``: DeclarativeBase with StrEnum auto-mapping and repr.
+- ``TimestampMixin``: created_at / updated_at with server defaults.
+- ``AuditMixin``: Extends TimestampMixin with created_by_id, updated_by_id,
+  soft delete (archived_at / is_active), and archive consistency constraints.
+- ``JsonModelColumn``: Helper for storing Pydantic models in JSON columns.
+
+Note: AuditMixin does NOT declare ForeignKey constraints on created_by_id /
+updated_by_id. Each consumer project adds its own FK references via
+``__table_args__`` if needed, since the user table name varies across projects.
+"""
+
+import enum
+import uuid
+from datetime import datetime
+from typing import TypeVar, Generic
+
+import sqlalchemy as sa
+from pydantic import BaseModel
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy.orm.decl_api import declared_attr
+
+
+class ReprMixin:
+    """Readable __repr__ showing all non-private attributes."""
+
+    def __repr__(self):
+        cls = self.__class__.__name__
+        attrs = ", ".join(
+            f"{k}={v!r}" for k, v in self.__dict__.items() if not k.startswith("_")
+        )
+        return f"{cls}({attrs})"
+
+
+class BaseDBModel(DeclarativeBase, ReprMixin):
+    """Base for all SQLAlchemy ORM models.
+
+    Automatically maps ``StrEnum`` to non-native string columns.
+    """
+
+    type_annotation_map = {
+        enum.StrEnum: sa.Enum(enum.StrEnum, native_enum=False, length=64),
+    }
+
+
+class TimestampMixin:
+    """Adds created_at and updated_at with server-side defaults."""
+
+    created_at: Mapped[datetime] = mapped_column(
+        server_default=sa.func.now(), nullable=False
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        server_default=sa.func.now(), onupdate=sa.func.now(), nullable=False
+    )
+
+
+class AuditMixin(TimestampMixin):
+    """Full audit trail with soft delete.
+
+    Provides:
+    - created_by_id / updated_by_id as plain UUID columns (no FK — add your own).
+    - archived_at / is_active for soft delete.
+    - A check constraint enforcing (is_active ⟺ archived_at IS NULL).
+    - An optional partial unique index on ``unique_fields`` (active records only).
+
+    Usage::
+
+        class MyModel(BaseDBModel, AuditMixin):
+            __tablename__ = "my_model"
+            unique_fields = ("org_id", "name")  # optional: partial unique on active rows
+            id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+            ...
+    """
+
+    created_by_id: Mapped[uuid.UUID | None] = mapped_column(
+        sa.UUID(as_uuid=True),
+        nullable=True,
+        index=True,
+    )
+    updated_by_id: Mapped[uuid.UUID | None] = mapped_column(
+        sa.UUID(as_uuid=True),
+        nullable=True,
+        index=True,
+    )
+    archived_at: Mapped[datetime | None] = mapped_column(
+        sa.DateTime(timezone=True), nullable=True, index=True
+    )
+    is_active: Mapped[bool] = mapped_column(
+        sa.Boolean, nullable=False, default=True, index=True
+    )
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if cls is AuditMixin:
+            return
+        if not issubclass(cls, BaseDBModel):
+            raise TypeError("AuditMixin can only be used with BaseDBModel subclasses.")
+        if not hasattr(cls, "__tablename__") or not isinstance(cls.__tablename__, str):
+            raise TypeError("Classes using AuditMixin must define __tablename__")
+
+    @declared_attr
+    def __table_args__(cls):
+        table_args = []
+
+        # Partial unique index for "active only" uniqueness.
+        if getattr(cls, "unique_fields", None):
+            table_args.append(
+                sa.Index(
+                    f"uq_{cls.__tablename__}_active",
+                    *cls.unique_fields,
+                    unique=True,
+                    postgresql_where=sa.text("archived_at IS NULL"),
+                )
+            )
+
+        # Validity constraint: active ⟺ not archived.
+        table_args.append(
+            sa.CheckConstraint(
+                "(is_active AND archived_at IS NULL) OR "
+                "(NOT is_active AND archived_at IS NOT NULL)",
+                name=f"ck_{cls.__tablename__}_active_archive_consistency",
+            )
+        )
+
+        return tuple(table_args)
+
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class JsonModelColumn(Generic[T]):
+    """Helper for SQLAlchemy JSON columns storing lists of Pydantic models.
+
+    Usage::
+
+        # Serialize before writing to DB
+        row.tags = JsonModelColumn.serialize(tag_models)
+
+        # Deserialize after reading from DB
+        tags = JsonModelColumn.deserialize(row.tags, TagModel)
+    """
+
+    @staticmethod
+    def serialize(models: list[T] | list[dict]) -> list[dict]:
+        result = []
+        for v in models:
+            if isinstance(v, BaseModel):
+                result.append(v.model_dump(mode="json"))
+            else:
+                cleaned = {}
+                for key, val in v.items():
+                    if isinstance(val, enum.Enum):
+                        cleaned[key] = val.value
+                    elif isinstance(val, datetime):
+                        cleaned[key] = val.isoformat()
+                    else:
+                        cleaned[key] = val
+                result.append(cleaned)
+        return result
+
+    @staticmethod
+    def deserialize(data: list[dict], model: type[T]) -> list[T]:
+        return [model(**item) for item in (data or [])]