belgie-alchemy 0.1.0a4__py3-none-any.whl

belgie_alchemy-0.1.0a4.dist-info/METADATA

@@ -0,0 +1,266 @@
+Metadata-Version: 2.3
+Name: belgie-alchemy
+Version: 0.1.0a4
+Summary: SQLAlchemy building blocks for Belgie
+Author: Matt LeMay
+Author-email: Matt LeMay <mplemay@users.noreply.github.com>
+Requires-Dist: belgie-proto
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# belgie-alchemy
+
+SQLAlchemy 2.0 building blocks for database models.
+
+## Overview
+
+`belgie-alchemy` provides opinionated defaults and utilities for SQLAlchemy:
+
+- **Base**: Declarative base with dataclass mapping and sensible defaults
+- **Mixins**: `PrimaryKeyMixin` (UUID), `TimestampMixin` (created/updated/deleted timestamps)
+- **Types**: `DateTimeUTC` (timezone-aware datetimes), `Scopes` (dialect-specific array/JSON storage)
+
+This module provides **building blocks only** - you define your own models.
+
+## Quick Start
+
+```python
+from datetime import datetime
+from belgie_alchemy import Base, PrimaryKeyMixin, TimestampMixin, DateTimeUTC
+from sqlalchemy.orm import Mapped, mapped_column
+
+class Article(Base, PrimaryKeyMixin, TimestampMixin):
+    __tablename__ = "articles"
+
+    title: Mapped[str]
+    published_at: Mapped[datetime] = mapped_column(DateTimeUTC)
+```
+
+This gives you:
+
+- UUID primary key with server-side generation
+- Automatic `created_at`, `updated_at`, `deleted_at` timestamps
+- Timezone-aware datetime handling
+- Dataclass-style `__init__`, `__repr__`, `__eq__`
+
+## Building Blocks
+
+### Base
+
+Declarative base with dataclass mapping enabled:
+
+```python
+from belgie_alchemy import Base
+from sqlalchemy.orm import Mapped, mapped_column
+
+class MyModel(Base):
+    __tablename__ = "my_models"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str]
+
+# Dataclass-style instantiation
+model = MyModel(id=1, name="example")
+```
+
+Features:
+
+- Consistent naming conventions for constraints
+- Automatic type annotation mapping (`datetime` → `DateTimeUTC`)
+- Dataclass mapping with `kw_only=True`, `repr=True`, `eq=True`
+
+### Mixins
+
+#### PrimaryKeyMixin
+
+Adds a UUID primary key with server-side generation:
+
+```python
+from belgie_alchemy import Base, PrimaryKeyMixin
+
+class MyModel(Base, PrimaryKeyMixin):
+    __tablename__ = "my_models"
+    # Automatically includes: id: Mapped[UUID]
+```
+
+The `id` field:
+
+- Type: `UUID`
+- Server-generated using `gen_random_uuid()`
+- Indexed and unique
+- Primary key
+
+#### TimestampMixin
+
+Adds automatic timestamp tracking:
+
+```python
+from belgie_alchemy import Base, TimestampMixin
+
+class MyModel(Base, TimestampMixin):
+    __tablename__ = "my_models"
+    # Automatically includes:
+    # - created_at: Mapped[datetime]
+    # - updated_at: Mapped[datetime] (auto-updates on changes)
+    # - deleted_at: Mapped[datetime | None]
+```
+
+Features:
+
+- `created_at` set automatically on insert
+- `updated_at` auto-updates on row changes
+- `deleted_at` for soft deletion
+- `mark_deleted()` method to set `deleted_at`
+
+### Types
+
+#### DateTimeUTC
+
+Timezone-aware datetime storage:
+
+```python
+from datetime import datetime
+from belgie_alchemy import Base, DateTimeUTC
+from sqlalchemy.orm import Mapped, mapped_column
+
+class Event(Base):
+    __tablename__ = "events"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    happened_at: Mapped[datetime] = mapped_column(DateTimeUTC)
+```
+
+Features:
+
+- Automatically converts naive datetimes to UTC
+- Preserves timezone-aware datetimes
+- Always returns UTC-aware datetimes from database
+- Works with PostgreSQL, SQLite, MySQL
+
+#### Scopes
+
+Dialect-specific array storage for permission scopes:
+
+```python
+from enum import StrEnum
+from belgie_alchemy import Base, Scopes
+from sqlalchemy.orm import Mapped, mapped_column
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    # Option 1: Simple string array (works everywhere)
+    scopes: Mapped[list[str] | None] = mapped_column(Scopes, default=None)
+```
+
+Features:
+
+- PostgreSQL: Uses native `ARRAY(String)` type
+- SQLite/MySQL: Uses JSON storage
+- Automatically converts StrEnum values to strings
+- Handles `None` values correctly
+
+For PostgreSQL with application-specific enum types, you can override:
+
+```python
+from enum import StrEnum
+from sqlalchemy import ARRAY
+from sqlalchemy.dialects.postgresql import ENUM
+
+class AppScope(StrEnum):
+    READ = "resource:read"
+    WRITE = "resource:write"
+    ADMIN = "admin"
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    # Option 2: PostgreSQL native ENUM array (type-safe)
+    scopes: Mapped[list[AppScope] | None] = mapped_column(
+        ARRAY(ENUM(AppScope, name="app_scope", create_type=True)),
+        default=None,
+    )
+```
+
+## Complete Example: Auth Models
+
+See `examples/alchemy/auth_models.py` for a complete reference implementation of authentication models:
+
+- `User` - with email, verification, and scopes
+- `Account` - OAuth provider linkage
+- `Session` - user session management
+- `OAuthState` - OAuth flow state
+
+**These are templates** - copy them to your project and customize as needed.
+
+Example structure:
+
+```python
+from datetime import datetime
+from uuid import UUID
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from belgie_alchemy import Base, PrimaryKeyMixin, TimestampMixin, DateTimeUTC, Scopes
+
+class User(Base, PrimaryKeyMixin, TimestampMixin):
+    __tablename__ = "users"
+
+    email: Mapped[str] = mapped_column(unique=True, index=True)
+    email_verified: Mapped[bool] = mapped_column(default=False)
+    scopes: Mapped[list[str] | None] = mapped_column(Scopes, default=None)
+
+    accounts: Mapped[list["Account"]] = relationship(
+        back_populates="user",
+        cascade="all, delete-orphan",
+        init=False,
+    )
+
+class Account(Base, PrimaryKeyMixin, TimestampMixin):
+    __tablename__ = "accounts"
+
+    user_id: Mapped[UUID] = mapped_column(
+        ForeignKey("users.id", ondelete="cascade"),
+        nullable=False,
+    )
+    provider: Mapped[str]
+    provider_account_id: Mapped[str]
+
+    user: Mapped[User] = relationship(
+        back_populates="accounts",
+        lazy="selectin",
+        init=False,
+    )
+```
+
+## Design Principles
+
+1. **Building blocks, not frameworks** - You own your models completely
+2. **Sensible defaults** - UTC datetimes, UUIDs, timestamps by default
+3. **Dataclass-friendly** - Clean instantiation and repr
+4. **Dialect-aware** - Use the best type for each database
+5. **Minimal magic** - Clear, explicit behavior
+
+## Migration from impl/auth.py
+
+If you previously imported models from `belgie_alchemy.impl.auth`:
+
+**Before:**
+
+```python
+from belgie_alchemy.impl.auth import User, Account, Session, OAuthState
+```
+
+**After:**
+
+```python
+# Copy models from examples/alchemy/auth_models.py to your project
+# Then import from your own code:
+from myapp.models import User, Account, Session, OAuthState
+```
+
+This gives you full control to customize the models for your application.

belgie_alchemy-0.1.0a4.dist-info/RECORD

@@ -0,0 +1,28 @@
+belgie_alchemy/__init__.py,sha256=zK7g-06wUYg1ThS389aPFnAOK38osQQwtw0ZizUajDc,1070
+belgie_alchemy/__tests__/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+belgie_alchemy/__tests__/adapter/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+belgie_alchemy/__tests__/adapter/test_adapter.py,sha256=-tlLCqihEkJXJRloeLVRtbPdIfpKMQ3axsfs7xZRRTk,16064
+belgie_alchemy/__tests__/auth_models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+belgie_alchemy/__tests__/auth_models/test_auth_models.py,sha256=RQNaGfmvGNIrndgokueKMxvR9uMnOoj9N7FKVTAkM9o,2741
+belgie_alchemy/__tests__/base/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+belgie_alchemy/__tests__/base/test_base.py,sha256=XZVy2eoutSOpDdufvZkEc7uJmmVOyxOh9HJkjsCcimM,3298
+belgie_alchemy/__tests__/conftest.py,sha256=S_c1HqCF3fviRnAcox0ZwKPcKiAPOcfEDMguJRNqqNE,1190
+belgie_alchemy/__tests__/fixtures/__init__.py,sha256=Ldyp56D1LrPVvJHcXfyvxtskqbeqXZqme-FNnNBb-oE,347
+belgie_alchemy/__tests__/fixtures/database.py,sha256=yKYkRQcdbZ9wGDNWhn6tDhY-rF2QQz0oibEb2LSoFdY,1129
+belgie_alchemy/__tests__/fixtures/models.py,sha256=ftWLG-MkqmUa1Z_Yp7pon6m84qLbtJo9XmCYiYYlsTo,3822
+belgie_alchemy/__tests__/mixins/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+belgie_alchemy/__tests__/mixins/test_mixins.py,sha256=0OQWWTc0fs_CN_4lrvVJgxrXji5mfn0wgRyRVJd_4gU,2419
+belgie_alchemy/__tests__/settings/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+belgie_alchemy/__tests__/settings/test_settings.py,sha256=jW7ZtTDfkBSX9AJYUKe5HSm2AjGSd-D51BFoRRVCIAA,11263
+belgie_alchemy/__tests__/settings/test_settings_integration.py,sha256=StkOTvfssTG8lvyAa_r-pdyyO1e6vC8IeRQJMuRr7hc,15480
+belgie_alchemy/__tests__/types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+belgie_alchemy/__tests__/types/test_types.py,sha256=bTMlfmyCJRLKsZ0Hj-4gor9xlbPTfteR0S0pqzaWR-8,5300
+belgie_alchemy/adapter.py,sha256=30ePooceD1O40WpODfEycxc4KaOKx_71GiCJqqF1rRE,10305
+belgie_alchemy/base.py,sha256=x-AddtIS4aBzA8p7exFDK-AYpMZ9HdhuwzmcdpPZ74g,843
+belgie_alchemy/mixins.py,sha256=rn3zXiU-UdyEcYOBNpy8p5JFkJRVzr6QaL_kk2VfoV8,3090
+belgie_alchemy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+belgie_alchemy/settings.py,sha256=0zK-GDEVzmI3efEceWGV7H3jieW63gqZHVJ4vgJVlMM,4991
+belgie_alchemy/types.py,sha256=BJ_rL5Ce5TyVV-C3I20VukA8A3Qifxzch-0OY1lqAcQ,1177
+belgie_alchemy-0.1.0a4.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+belgie_alchemy-0.1.0a4.dist-info/METADATA,sha256=N0hl6JhUuzWWNqZeZft17_pz1Qr725fmpEulnILq-p0,7005
+belgie_alchemy-0.1.0a4.dist-info/RECORD,,

belgie_alchemy-0.1.0a4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.28
+Root-Is-Purelib: true
+Tag: py3-none-any