belgie-alchemy 0.1.0__py3-none-any.whl

belgie_alchemy/adapter.py

@@ -0,0 +1,323 @@
+from datetime import UTC, datetime
+from typing import Any
+from uuid import UUID
+
+from belgie_proto import (
+    AccountProtocol,
+    AdapterProtocol,
+    OAuthStateProtocol,
+    SessionProtocol,
+    UserProtocol,
+)
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class AlchemyAdapter[
+    UserT: UserProtocol,
+    AccountT: AccountProtocol,
+    SessionT: SessionProtocol,
+    OAuthStateT: OAuthStateProtocol,
+](AdapterProtocol[UserT, AccountT, SessionT, OAuthStateT]):
+    def __init__(
+        self,
+        *,
+        user: type[UserT],
+        account: type[AccountT],
+        session: type[SessionT],
+        oauth_state: type[OAuthStateT],
+    ) -> None:
+        self.user_model = user
+        self.account_model = account
+        self.session_model = session
+        self.oauth_state_model = oauth_state
+
+    async def create_user(
+        self,
+        session: AsyncSession,
+        email: str,
+        name: str | None = None,
+        image: str | None = None,
+        *,
+        email_verified: bool = False,
+    ) -> UserT:
+        user = self.user_model(
+            email=email,
+            email_verified=email_verified,
+            name=name,
+            image=image,
+        )
+        session.add(user)
+        try:
+            await session.commit()
+            await session.refresh(user)
+        except Exception:
+            await session.rollback()
+            raise
+        return user
+
+    async def get_user_by_id(self, session: AsyncSession, user_id: UUID) -> UserT | None:
+        stmt = select(self.user_model).where(self.user_model.id == user_id)
+        result = await session.execute(stmt)
+        return result.scalar_one_or_none()
+
+    async def get_user_by_email(self, session: AsyncSession, email: str) -> UserT | None:
+        stmt = select(self.user_model).where(self.user_model.email == email)
+        result = await session.execute(stmt)
+        return result.scalar_one_or_none()
+
+    async def update_user(
+        self,
+        session: AsyncSession,
+        user_id: UUID,
+        **updates: Any,  # noqa: ANN401
+    ) -> UserT | None:
+        user = await self.get_user_by_id(session, user_id)
+        if not user:
+            return None
+
+        for key, value in updates.items():
+            if hasattr(user, key):
+                setattr(user, key, value)
+
+        user.updated_at = datetime.now(UTC)
+        try:
+            await session.commit()
+            await session.refresh(user)
+        except Exception:
+            await session.rollback()
+            raise
+        return user
+
+    async def create_account(
+        self,
+        session: AsyncSession,
+        user_id: UUID,
+        provider: str,
+        provider_account_id: str,
+        **tokens: Any,  # noqa: ANN401
+    ) -> AccountT:
+        account = self.account_model(
+            user_id=user_id,
+            provider=provider,
+            provider_account_id=provider_account_id,
+            access_token=tokens.get("access_token"),
+            refresh_token=tokens.get("refresh_token"),
+            expires_at=tokens.get("expires_at"),
+            token_type=tokens.get("token_type"),
+            scope=tokens.get("scope"),
+            id_token=tokens.get("id_token"),
+        )
+        session.add(account)
+        try:
+            await session.commit()
+            await session.refresh(account)
+        except Exception:
+            await session.rollback()
+            raise
+        return account
+
+    async def get_account(
+        self,
+        session: AsyncSession,
+        provider: str,
+        provider_account_id: str,
+    ) -> AccountT | None:
+        stmt = select(self.account_model).where(
+            self.account_model.provider == provider,
+            self.account_model.provider_account_id == provider_account_id,
+        )
+        result = await session.execute(stmt)
+        return result.scalar_one_or_none()
+
+    async def get_account_by_user_and_provider(
+        self,
+        session: AsyncSession,
+        user_id: UUID,
+        provider: str,
+    ) -> AccountT | None:
+        stmt = select(self.account_model).where(
+            self.account_model.user_id == user_id,
+            self.account_model.provider == provider,
+        )
+        result = await session.execute(stmt)
+        return result.scalar_one_or_none()
+
+    async def update_account(
+        self,
+        session: AsyncSession,
+        user_id: UUID,
+        provider: str,
+        **tokens: Any,  # noqa: ANN401
+    ) -> AccountT | None:
+        account = await self.get_account_by_user_and_provider(session, user_id, provider)
+        if not account:
+            return None
+
+        for key, value in tokens.items():
+            if hasattr(account, key) and value is not None:
+                setattr(account, key, value)
+
+        account.updated_at = datetime.now(UTC)
+        try:
+            await session.commit()
+            await session.refresh(account)
+        except Exception:
+            await session.rollback()
+            raise
+        return account
+
+    async def create_session(
+        self,
+        session: AsyncSession,
+        user_id: UUID,
+        expires_at: datetime,
+        ip_address: str | None = None,
+        user_agent: str | None = None,
+    ) -> SessionT:
+        session_obj = self.session_model(
+            user_id=user_id,
+            expires_at=expires_at,
+            ip_address=ip_address,
+            user_agent=user_agent,
+        )
+        session.add(session_obj)
+        try:
+            await session.commit()
+            await session.refresh(session_obj)
+        except Exception:
+            await session.rollback()
+            raise
+        return session_obj
+
+    async def get_session(
+        self,
+        session: AsyncSession,
+        session_id: UUID,
+    ) -> SessionT | None:
+        stmt = select(self.session_model).where(self.session_model.id == session_id)
+        result = await session.execute(stmt)
+        return result.scalar_one_or_none()
+
+    async def update_session(
+        self,
+        session: AsyncSession,
+        session_id: UUID,
+        **updates: Any,  # noqa: ANN401
+    ) -> SessionT | None:
+        session_obj = await self.get_session(session, session_id)
+        if not session_obj:
+            return None
+
+        for key, value in updates.items():
+            if hasattr(session_obj, key):
+                setattr(session_obj, key, value)
+
+        session_obj.updated_at = datetime.now(UTC)
+        try:
+            await session.commit()
+            await session.refresh(session_obj)
+        except Exception:
+            await session.rollback()
+            raise
+        return session_obj
+
+    async def delete_session(self, session: AsyncSession, session_id: UUID) -> bool:
+        stmt = delete(self.session_model).where(self.session_model.id == session_id)
+        result = await session.execute(stmt)
+        try:
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+        return result.rowcount > 0  # type: ignore[attr-defined]
+
+    async def delete_expired_sessions(self, session: AsyncSession) -> int:
+        now_naive = datetime.now(UTC).replace(tzinfo=None)
+        stmt = delete(self.session_model).where(self.session_model.expires_at < now_naive)
+        result = await session.execute(stmt)
+        try:
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+        return result.rowcount  # type: ignore[attr-defined]
+
+    async def create_oauth_state(
+        self,
+        session: AsyncSession,
+        state: str,
+        expires_at: datetime,
+        code_verifier: str | None = None,
+        redirect_url: str | None = None,
+    ) -> OAuthStateT:
+        # Create the model instance - some models have user_id, some don't
+        try:
+            oauth_state = self.oauth_state_model(
+                state=state,
+                user_id=None,
+                code_verifier=code_verifier,
+                redirect_url=redirect_url,
+                expires_at=expires_at,
+            )
+        except TypeError:
+            # Model doesn't accept user_id (like auth package models)
+            oauth_state = self.oauth_state_model(
+                state=state,
+                code_verifier=code_verifier,
+                redirect_url=redirect_url,
+                expires_at=expires_at,
+            )
+        session.add(oauth_state)
+        try:
+            await session.commit()
+            await session.refresh(oauth_state)
+        except Exception:
+            await session.rollback()
+            raise
+        return oauth_state
+
+    async def get_oauth_state(
+        self,
+        session: AsyncSession,
+        state: str,
+    ) -> OAuthStateT | None:
+        stmt = select(self.oauth_state_model).where(self.oauth_state_model.state == state)
+        result = await session.execute(stmt)
+        return result.scalar_one_or_none()
+
+    async def delete_oauth_state(self, session: AsyncSession, state: str) -> bool:
+        stmt = delete(self.oauth_state_model).where(self.oauth_state_model.state == state)
+        result = await session.execute(stmt)
+        try:
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+        return result.rowcount > 0  # type: ignore[attr-defined]
+
+    async def delete_user(self, session: AsyncSession, user_id: UUID) -> bool:
+        """Delete a user and all associated data.
+
+        Deletes the user record. Related data (sessions, accounts) are automatically
+        deleted by the database via CASCADE constraints on the foreign keys.
+
+        Note: OAuth states are not user-specific and are not deleted.
+        They will expire based on their expires_at timestamp.
+
+        Args:
+            session: Database session
+            user_id: UUID of the user to delete
+
+        Returns:
+            True if user was deleted, False if user didn't exist
+        """
+        stmt = delete(self.user_model).where(self.user_model.id == user_id)
+        result = await session.execute(stmt)
+        try:
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+        return result.rowcount > 0  # type: ignore[attr-defined]

belgie_alchemy/base.py

@@ -0,0 +1,25 @@
+from datetime import datetime
+from typing import Any, ClassVar, Final
+
+from sqlalchemy import MetaData
+from sqlalchemy.orm import DeclarativeBase, MappedAsDataclass
+
+from belgie_alchemy.types import DateTimeUTC
+
+NAMING_CONVENTION: Final[dict[str, str]] = {
+    "ix": "ix_%(column_0_label)s",
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s",
+}
+
+TYPE_ANNOTATION_MAP: Final[dict[type | Any, object]] = {
+    datetime: DateTimeUTC,
+}
+
+
+class Base(MappedAsDataclass, DeclarativeBase):
+    metadata = MetaData(naming_convention=NAMING_CONVENTION)
+    type_annotation_map = TYPE_ANNOTATION_MAP
+    __sa_dataclass_kwargs__: ClassVar[dict[str, bool]] = {"kw_only": True, "repr": True, "eq": True}

belgie_alchemy/mixins.py

@@ -0,0 +1,83 @@
+from datetime import datetime
+from uuid import UUID, uuid4
+
+from sqlalchemy import func
+from sqlalchemy.orm import Mapped, MappedAsDataclass, declarative_mixin, mapped_column
+
+from belgie_alchemy.types import DateTimeUTC
+
+
+@declarative_mixin
+class PrimaryKeyMixin(MappedAsDataclass):
+    """Mixin that adds a UUID primary key column.
+
+    Inherits from MappedAsDataclass to support standalone usage without Base.
+    When used with Base (which also inherits MappedAsDataclass), the duplicate
+    inheritance is safely handled by Python's MRO (Method Resolution Order).
+
+    The id field is excluded from __init__ (init=False) and is automatically
+    generated both client-side (default_factory=uuid4) and server-side
+    (server_default=gen_random_uuid()) for maximum compatibility.
+
+    Usage:
+        class MyModel(Base, PrimaryKeyMixin, TimestampMixin):
+            __tablename__ = "my_table"
+            name: Mapped[str]
+
+    The UUID is:
+    - Generated client-side by default (uuid4)
+    - Has server-side fallback (gen_random_uuid() for PostgreSQL)
+    - Indexed and unique for efficient lookups
+    """
+
+    id: Mapped[UUID] = mapped_column(
+        primary_key=True,
+        default_factory=uuid4,
+        server_default=func.gen_random_uuid(),
+        index=True,
+        unique=True,
+        init=False,
+    )
+
+
+@declarative_mixin
+class TimestampMixin(MappedAsDataclass):
+    """Mixin that adds automatic timestamp tracking columns.
+
+    Inherits from MappedAsDataclass to support standalone usage without Base.
+    When used with Base (which also inherits MappedAsDataclass), the duplicate
+    inheritance is safely handled by Python's MRO (Method Resolution Order).
+
+    All timestamp fields are excluded from __init__ (init=False) and are
+    automatically managed by the database using UTC-aware datetimes.
+
+    Usage:
+        class MyModel(Base, PrimaryKeyMixin, TimestampMixin):
+            __tablename__ = "my_table"
+            name: Mapped[str]
+
+    Fields:
+        created_at: Set automatically on insert (UTC-aware)
+        updated_at: Set automatically on insert and update (UTC-aware)
+        deleted_at: NULL by default, set via mark_deleted() for soft deletion
+
+    Soft Deletion:
+        Use mark_deleted() to mark an entity as deleted without removing it
+        from the database. Remember to commit the session after calling.
+    """
+
+    created_at: Mapped[datetime] = mapped_column(DateTimeUTC, default=func.now(), init=False)
+    updated_at: Mapped[datetime] = mapped_column(DateTimeUTC, default=func.now(), onupdate=func.now(), init=False)
+    deleted_at: Mapped[datetime | None] = mapped_column(DateTimeUTC, nullable=True, default=None, init=False)
+
+    def mark_deleted(self) -> None:
+        """Mark this entity as deleted by setting deleted_at timestamp.
+
+        Note: This only sets the field, it does not persist to the database.
+        You must commit the session to save the change.
+
+        Example:
+            user.mark_deleted()
+            await session.commit()  # Persist the soft delete
+        """
+        self.deleted_at = func.now()

belgie_alchemy/settings.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import os
+from functools import cached_property
+from typing import TYPE_CHECKING, Annotated, Literal, cast
+
+from pydantic import Field, NonNegativeFloat, NonNegativeInt, PositiveInt, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from sqlalchemy import event
+from sqlalchemy.engine import URL
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+
+if TYPE_CHECKING:
+    import sqlite3
+    from collections.abc import AsyncGenerator
+
+
+class PostgresSettings(BaseSettings):
+    """PostgreSQL database settings.
+
+    Environment variables use the prefix: BELGIE_POSTGRES_
+    Example: BELGIE_POSTGRES_HOST=localhost
+    """
+
+    model_config = SettingsConfigDict(env_prefix="BELGIE_POSTGRES_", extra="ignore")
+
+    type: Literal["postgres"] = "postgres"
+    host: str
+    port: PositiveInt = 5432
+    database: str
+    username: str
+    password: SecretStr
+    pool_size: PositiveInt = 5
+    max_overflow: NonNegativeInt = 10
+    pool_timeout: NonNegativeFloat = 30.0
+    pool_recycle: PositiveInt = 3600
+    pool_pre_ping: bool = True
+    echo: bool = False
+
+
+class SqliteSettings(BaseSettings):
+    """SQLite database settings.
+
+    Environment variables use the prefix: BELGIE_SQLITE_
+    Example: BELGIE_SQLITE_DATABASE=:memory:
+    """
+
+    model_config = SettingsConfigDict(env_prefix="BELGIE_SQLITE_", extra="ignore")
+
+    type: Literal["sqlite"] = "sqlite"
+    database: str
+    enable_foreign_keys: bool = True
+    echo: bool = False
+
+
+class DatabaseSettings(BaseSettings):
+    """Database settings with support for PostgreSQL and SQLite.
+
+    Environment variables:
+    - BELGIE_DATABASE_TYPE: "postgres" or "sqlite" (default: "sqlite")
+    - For PostgreSQL: BELGIE_POSTGRES_HOST, BELGIE_POSTGRES_PORT, etc.
+    - For SQLite: BELGIE_SQLITE_DATABASE, BELGIE_SQLITE_ENABLE_FOREIGN_KEYS, etc.
+
+    Example usage:
+        # From environment variables
+        db = DatabaseSettings.from_env()
+
+        # Direct instantiation
+        db = DatabaseSettings(dialect={"type": "sqlite", "database": ":memory:"})
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="BELGIE_DATABASE_",
+        extra="ignore",
+    )
+
+    dialect: Annotated[PostgresSettings | SqliteSettings, Field(discriminator="type")]
+
+    @classmethod
+    def from_env(cls) -> DatabaseSettings:
+        """Load database settings from environment variables.
+
+        Reads BELGIE_DATABASE_TYPE to determine which dialect to use,
+        then loads the appropriate settings from BELGIE_POSTGRES_* or BELGIE_SQLITE_* vars.
+
+        Returns:
+            DatabaseSettings instance configured from environment variables.
+
+        Example:
+            # Set environment variables
+            os.environ["BELGIE_DATABASE_TYPE"] = "postgres"
+            os.environ["BELGIE_POSTGRES_HOST"] = "localhost"
+            os.environ["BELGIE_POSTGRES_DATABASE"] = "mydb"
+            # ... other postgres settings
+
+            db = DatabaseSettings.from_env()
+        """
+        db_type = os.getenv("BELGIE_DATABASE_TYPE", "sqlite")
+
+        if db_type == "postgres":
+            return cls(dialect=PostgresSettings())  # type: ignore[call-arg]
+        return cls(dialect=SqliteSettings())  # type: ignore[call-arg]
+
+    @cached_property
+    def engine(self) -> AsyncEngine:
+        if self.dialect.type == "postgres":
+            dialect = cast("PostgresSettings", self.dialect)
+            url = URL.create(
+                "postgresql+asyncpg",
+                username=dialect.username,
+                password=dialect.password.get_secret_value(),
+                host=dialect.host,
+                port=dialect.port,
+                database=dialect.database,
+            )
+            return create_async_engine(
+                url,
+                echo=dialect.echo,
+                pool_size=dialect.pool_size,
+                max_overflow=dialect.max_overflow,
+                pool_timeout=dialect.pool_timeout,
+                pool_recycle=dialect.pool_recycle,
+                pool_pre_ping=dialect.pool_pre_ping,
+            )
+
+        dialect = cast("SqliteSettings", self.dialect)
+        url = URL.create("sqlite+aiosqlite", database=dialect.database)
+        engine = create_async_engine(url, echo=dialect.echo)
+
+        if dialect.enable_foreign_keys:
+
+            @event.listens_for(engine.sync_engine, "connect")
+            def _enable_foreign_keys(dbapi_conn: sqlite3.Connection, _conn_record: object) -> None:
+                cursor = dbapi_conn.cursor()
+                cursor.execute("PRAGMA foreign_keys=ON")
+                cursor.close()
+
+        return engine
+
+    @cached_property
+    def session_maker(self) -> async_sessionmaker[AsyncSession]:
+        return async_sessionmaker(self.engine, class_=AsyncSession, expire_on_commit=False)
+
+    async def dependency(self) -> AsyncGenerator[AsyncSession, None]:
+        async with self.session_maker() as session:
+            yield session

belgie_alchemy/types.py

@@ -0,0 +1,32 @@
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import DateTime
+from sqlalchemy.types import TypeDecorator
+
+
+class DateTimeUTC(TypeDecorator[datetime]):
+    impl = DateTime(timezone=True)
+    cache_ok = True
+
+    def process_bind_param(self, value: datetime | None, _dialect: Any) -> datetime | None:  # type: ignore[override]  # noqa: ANN401
+        if value is None:
+            return None
+        if not isinstance(value, datetime):
+            type_name = type(value).__name__
+            msg = (
+                f"DateTimeUTC requires datetime object, got {type_name}. "
+                f"If using a date, convert to datetime first: "
+                f"datetime.combine(your_date, time())"
+            )
+            raise TypeError(msg)
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=UTC)
+        return value.astimezone(UTC)
+
+    def process_result_value(self, value: Any, _dialect: Any) -> datetime | None:  # type: ignore[override]  # noqa: ANN401
+        if value is None:
+            return None
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=UTC)
+        return value.astimezone(UTC)