sqlcrucible 0.3.2__tar.gz → 0.3.4__tar.gz

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/.github/workflows/ci.yml

@@ -53,13 +53,17 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v5
 
+      - name: Derive cache key
+        id: cache-key
+        run: echo "session=$(echo '${{ matrix.session }}' | tr ',' '-')" >> $GITHUB_OUTPUT
+
       - name: Restore uv cache
         uses: actions/cache@v4
         with:
           path: ${{ env.UV_CACHE_DIR }}
-          key: uv-${{ runner.os }}-${{ matrix.session }}-${{ hashFiles('uv.lock') }}
+          key: uv-${{ runner.os }}-${{ steps.cache-key.outputs.session }}-${{ hashFiles('uv.lock') }}
           restore-keys: |
-            uv-${{ runner.os }}-${{ matrix.session }}-
+            uv-${{ runner.os }}-${{ steps.cache-key.outputs.session }}-
             uv-${{ runner.os }}-
 
       - name: Run nox session

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/.gitignore

@@ -23,3 +23,4 @@ htmlcov/
 
 # MkDocs
 site/
+/.hypothesis/

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlcrucible
-Version: 0.3.2
+Version: 0.3.4
 Summary: Define a single model that works as both Pydantic and SQLAlchemy, with explicit conversion between the two
 Author-email: Richard Rae-Jones <sqlcrucible@richard.rdrj.uk>
 License-Expression: MIT

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/docs/comparison.md

@@ -49,7 +49,7 @@
 
     ```python
     from typing import Annotated
-    from uuid import UUID, uuid4
+    from uuid import UUID, uuid7
     from pydantic import Field
     from sqlalchemy.orm import mapped_column
     from sqlcrucible import SQLCrucibleBaseModel
@@ -57,7 +57,7 @@
     class User(SQLCrucibleBaseModel):
         __sqlalchemy_params__ = {"__tablename__": "user"}
 
-        id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+        id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
         name: str
         email: str
     ```
@@ -65,11 +65,11 @@
 === "SQLModel"
 
     ```python
-    from uuid import UUID, uuid4
+    from uuid import UUID, uuid7
     from sqlmodel import SQLModel, Field
 
     class User(SQLModel, table=True):
-        id: UUID = Field(default_factory=uuid4, primary_key=True)
+        id: UUID = Field(default_factory=uuid7, primary_key=True)
         name: str
         email: str
     ```
@@ -113,7 +113,7 @@
 
     class Author(SQLCrucibleBaseModel):
         __sqlalchemy_params__ = {"__tablename__": "author"}
-        id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+        id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
         name: str
 
         books = readonly_field(
@@ -131,7 +131,7 @@
     from sqlmodel import Relationship
 
     class Author(SQLModel, table=True):
-        id: UUID = Field(default_factory=uuid4, primary_key=True)
+        id: UUID = Field(default_factory=uuid7, primary_key=True)
         name: str
 
         books: list["Book"] = Relationship(back_populates="author")

sqlcrucible-0.3.4/docs/getting-started.md

@@ -0,0 +1,169 @@
+# Getting Started
+
+## Installation
+
+Install SQLCrucible with pip:
+
+```bash
+pip install sqlcrucible
+```
+
+Or with uv:
+
+```bash
+uv add sqlcrucible
+```
+
+## Quick Start
+
+Here's a complete example showing the typical workflow:
+
+=== "Python 3.14+"
+
+    ```python
+    from typing import Annotated
+    from uuid import UUID, uuid7
+
+    from pydantic import Field
+    from sqlalchemy import create_engine, select
+    from sqlalchemy.orm import Session, mapped_column
+
+    from sqlcrucible import SAType, SQLCrucibleBaseModel
+
+    # 1. Define your entity
+    class Artist(SQLCrucibleBaseModel):
+        __sqlalchemy_params__ = {"__tablename__": "artist"}
+
+        id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
+        name: str
+
+    # 2. Create the database tables
+    engine = create_engine("sqlite:///:memory:")
+    SAType[Artist].__table__.metadata.create_all(engine)
+
+    # 3. Create an entity and save it
+    artist = Artist(name="Bob Dylan")
+    with Session(engine) as session:
+        session.add(artist.to_sa_model())  # Convert to SQLAlchemy model
+        session.commit()
+
+    # 4. Query and convert back
+    with Session(engine) as session:
+        sa_artist = session.scalar(
+            select(SAType[Artist]).where(SAType[Artist].name == "Bob Dylan")
+        )
+        artist = Artist.from_sa_model(sa_artist)  # Convert back to entity
+        print(artist.name)  # "Bob Dylan"
+    ```
+
+=== "Python < 3.14"
+
+    ```python
+    from typing import Annotated
+    from uuid import UUID
+
+    from uuid_utils.compat import uuid7
+
+    from pydantic import Field
+    from sqlalchemy import create_engine, select
+    from sqlalchemy.orm import Session, mapped_column
+
+    from sqlcrucible import SAType, SQLCrucibleBaseModel
+
+    # 1. Define your entity
+    class Artist(SQLCrucibleBaseModel):
+        __sqlalchemy_params__ = {"__tablename__": "artist"}
+
+        id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
+        name: str
+
+    # 2. Create the database tables
+    engine = create_engine("sqlite:///:memory:")
+    SAType[Artist].__table__.metadata.create_all(engine)
+
+    # 3. Create an entity and save it
+    artist = Artist(name="Bob Dylan")
+    with Session(engine) as session:
+        session.add(artist.to_sa_model())  # Convert to SQLAlchemy model
+        session.commit()
+
+    # 4. Query and convert back
+    with Session(engine) as session:
+        sa_artist = session.scalar(
+            select(SAType[Artist]).where(SAType[Artist].name == "Bob Dylan")
+        )
+        artist = Artist.from_sa_model(sa_artist)  # Convert back to entity
+        print(artist.name)  # "Bob Dylan"
+    ```
+
+!!! note "UUID7 on older Python versions"
+    UUID7 is preferred over UUID4 for database primary keys because its time-ordered values improve index performance. `uuid.uuid7` is available in the standard library from Python 3.14. On earlier versions, install [`uuid-utils`](https://pypi.org/project/uuid-utils/) and import with `from uuid_utils.compat import uuid7`. All remaining examples in these docs use the stdlib import for brevity.
+
+The `Artist` class is a standard Pydantic model — it works with FastAPI, has validation, and serializes to JSON. When you need to interact with the database, you explicitly convert to and from the SQLAlchemy model.
+
+## What This Replaces
+
+Without SQLCrucible, you'd need to write equivalent code like this:
+
+```python
+from uuid import UUID, uuid7
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import mapped_column, DeclarativeBase, Mapped
+from typing import Any, Self
+
+class Base(DeclarativeBase): ...
+
+class ArtistSQLAlchemyModel(Base):
+    __tablename__ = "artist"
+    id: Mapped[UUID] = mapped_column(primary_key=True)
+    name: Mapped[str]
+
+class Artist(BaseModel):
+    __sqlalchemy_type__: type[Any] = ArtistSQLAlchemyModel
+
+    id: UUID = Field(default_factory=uuid7)
+    name: str
+
+    def to_sa_model(self) -> ArtistSQLAlchemyModel:
+        return ArtistSQLAlchemyModel(
+            id=self.id,
+            name=self.name
+        )
+
+    @classmethod
+    def from_sa_model(cls, sa_model: ArtistSQLAlchemyModel) -> Self:
+        return cls(
+            id=sa_model.id,
+            name=sa_model.name
+        )
+```
+
+## Framework Support
+
+SQLCrucible works with multiple Python model frameworks:
+
+- **Pydantic**: Inherit from `SQLCrucibleBaseModel`
+- **dataclasses**: Use `@dataclass` with `SQLCrucibleEntity`
+- **attrs**: Use `@define` with `SQLCrucibleEntity`
+
+```python
+from dataclasses import dataclass, field
+
+@dataclass
+class Artist(SQLCrucibleEntity):
+    __sqlalchemy_params__ = {"__tablename__": "artist"}
+    id: Annotated[UUID, mapped_column(primary_key=True)] = field(default_factory=uuid7)
+    name: str
+```
+
+## Caveats
+
+1. **Cyclical references between model instances are not supported.** Use `readonly_field` on one side to break the cycle.
+
+2. **Pydantic and `readonly_field`**: Either inherit from `SQLCrucibleBaseModel` (which includes the necessary config), or add `model_config = ConfigDict(ignored_types=(ReadonlyFieldDescriptor,))` to your model (import from `sqlcrucible`).
+
+3. **Forward references in relationships**: Use lambdas to avoid circular import issues: `relationship(lambda: SAType[OtherEntity])`.
+
+4. **Concrete table inheritance** requires redefining ALL columns in each subclass.
+
+5. **`readonly_field` requires a backing SQLAlchemy model**: Accessing a `readonly_field` on an entity not loaded via `from_sa_model()` raises `RuntimeError`.

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/docs/guide/defining-entities.md

@@ -6,7 +6,7 @@ An entity is a class that serves as both a Pydantic model and a SQLAlchemy table
 
 ```python
 from typing import Annotated
-from uuid import UUID, uuid4
+from uuid import UUID, uuid7
 from pydantic import Field
 from sqlalchemy.orm import mapped_column
 from sqlcrucible import SQLCrucibleBaseModel
@@ -14,7 +14,7 @@ from sqlcrucible import SQLCrucibleBaseModel
 class Artist(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "artist"}
 
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     name: Annotated[str, mapped_column()]
 ```
 
@@ -32,12 +32,12 @@ class BaseEntity(SQLCrucibleBaseModel):
 
 class Artist(BaseEntity):
     __sqlalchemy_params__ = {"__tablename__": "artist"}
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     name: str
 
 class Album(BaseEntity):
     __sqlalchemy_params__ = {"__tablename__": "album"}
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     title: str
 ```
 
@@ -72,7 +72,7 @@ class User(SQLCrucibleBaseModel):
         ),
     }
 
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     email: str
 ```
 

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/docs/guide/field-mapping.md

@@ -45,7 +45,7 @@ This is useful when:
 
 ```python
 from typing import Annotated
-from uuid import UUID, uuid4
+from uuid import UUID, uuid7
 from pydantic import Field
 from sqlalchemy.orm import mapped_column
 from sqlcrucible import SQLCrucibleBaseModel
@@ -54,7 +54,7 @@ from sqlcrucible import SQLAlchemyField
 class User(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "user"}
 
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     # Entity field 'email' maps to column 'email_address' in the database
     email: Annotated[str, SQLAlchemyField(name="email_address")]
 ```

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/docs/guide/inheritance.md

@@ -8,7 +8,7 @@ All subclasses share one table with a discriminator column:
 
 ```python
 from typing import Annotated
-from uuid import UUID, uuid4
+from uuid import UUID, uuid7
 from pydantic import Field
 from sqlalchemy import String
 from sqlalchemy.orm import mapped_column
@@ -20,7 +20,7 @@ class Animal(SQLCrucibleBaseModel):
         "__tablename__": "animal",
         "__mapper_args__": {"polymorphic_on": "type", "polymorphic_identity": "animal"},
     }
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     type: Annotated[str, mapped_column(String(50))]
     name: str
 
@@ -42,7 +42,7 @@ Each subclass has its own table with a foreign key to the parent:
 
 ```python
 from typing import Annotated
-from uuid import UUID, uuid4
+from uuid import UUID, uuid7
 from pydantic import Field
 from sqlalchemy import ForeignKey, String
 from sqlalchemy.orm import mapped_column
@@ -54,7 +54,7 @@ class Animal(SQLCrucibleBaseModel):
         "__tablename__": "animal",
         "__mapper_args__": {"polymorphic_on": "type", "polymorphic_identity": "animal"},
     }
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     type: Annotated[str, mapped_column(String(50))]
     name: str
 
@@ -63,7 +63,7 @@ class Dog(Animal):
         "__tablename__": "dog",
         "__mapper_args__": {"polymorphic_identity": "dog"},
     }
-    id: Annotated[UUID, mapped_column(ForeignKey("animal.id"), primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(ForeignKey("animal.id"), primary_key=True)] = Field(default_factory=uuid7)
     bones_chewed: int | None = None
     type: Annotated[str, ExcludeSAField()] = Field(default="dog")
 ```
@@ -74,7 +74,7 @@ Each subclass is a completely independent table:
 
 ```python
 from typing import Annotated
-from uuid import UUID, uuid4
+from uuid import UUID, uuid7
 from pydantic import Field
 from sqlalchemy import String
 from sqlalchemy.orm import mapped_column
@@ -85,7 +85,7 @@ class Animal(SQLCrucibleBaseModel):
         "__abstract__": True,
         "__mapper_args__": {"polymorphic_on": "type"},
     }
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     type: Annotated[str, mapped_column(String(50))]
     name: str
 
@@ -95,7 +95,7 @@ class Dog(Animal):
         "__mapper_args__": {"polymorphic_identity": "dog", "concrete": True},
     }
     # Must redefine ALL columns for concrete table inheritance
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     type: Annotated[str, mapped_column(String(50))] = Field(default="dog")
     name: str
     bones_chewed: int | None = None
@@ -109,7 +109,7 @@ class Dog(Animal):
 When using inheritance, `from_sa_model()` automatically returns the correct subclass:
 
 ```python
-dog_sa = Dog.__sqlalchemy_type__(id=uuid4(), name="Fido", type="dog", bones_chewed=42)
+dog_sa = Dog.__sqlalchemy_type__(id=uuid7(), name="Fido", type="dog", bones_chewed=42)
 
 # Load via the base class — returns Dog, not Animal
 animal = Animal.from_sa_model(dog_sa)

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/docs/guide/orm-descriptors.md

@@ -12,7 +12,7 @@ Define the function **outside** the class body and use `readonly_field` to mark
 
 ```python
 from typing import Annotated
-from uuid import UUID, uuid4
+from uuid import UUID, uuid7
 from pydantic import Field
 from sqlalchemy.orm import mapped_column
 from sqlalchemy.ext.hybrid import hybrid_property
@@ -25,7 +25,7 @@ def _full_name(self) -> str:
 class Person(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "person"}
 
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     first_name: Annotated[str, mapped_column()]
     last_name: Annotated[str, mapped_column()]
 
@@ -62,7 +62,7 @@ You can also pass the descriptor directly to `readonly_field` instead of using `
 class Person(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "person"}
 
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     first_name: Annotated[str, mapped_column()]
     last_name: Annotated[str, mapped_column()]
 
@@ -98,7 +98,7 @@ _full_name_hybrid = hybrid_property(_get_full_name).setter(_set_full_name)
 class Person(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "person"}
 
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     first_name: Annotated[str, mapped_column()]
     last_name: Annotated[str, mapped_column()]
 
@@ -125,13 +125,13 @@ from sqlcrucible import SQLAlchemyField
 class Department(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "department"}
 
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     name: Annotated[str, mapped_column()]
 
 class Employee(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "employee"}
 
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     name: Annotated[str, mapped_column()]
     department_id: Annotated[UUID, mapped_column(ForeignKey("department.id"))]
 
@@ -170,7 +170,7 @@ Use a `creator` function to make the proxy writable:
 class Employee(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "employee"}
 
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     department_id: Annotated[UUID, mapped_column(ForeignKey("department.id"))]
 
     department = readonly_field(
@@ -187,7 +187,7 @@ class Employee(SQLCrucibleBaseModel):
         association_proxy(
             "department",
             "name",
-            creator=lambda name: SAType[Department](id=uuid4(), name=name),
+            creator=lambda name: SAType[Department](id=uuid7(), name=name),
         ),
     ]
 ```

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/docs/guide/relationships.md

@@ -6,7 +6,7 @@ Use `readonly_field` to define relationship fields that are loaded from the SQLA
 
 ```python
 from typing import Annotated
-from uuid import UUID, uuid4
+from uuid import UUID, uuid7
 from pydantic import Field
 from sqlalchemy import ForeignKey
 from sqlalchemy.orm import mapped_column, relationship
@@ -15,12 +15,12 @@ from sqlcrucible import readonly_field
 
 class Artist(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "artist"}
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     name: str
 
 class Track(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "track"}
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     name: str
     artist_id: Annotated[UUID, mapped_column(ForeignKey("artist.id"))]
 
@@ -66,18 +66,72 @@ artist = readonly_field(
 
 ## Important Notes
 
-- **Cyclical references are not supported.** If `Artist` has a `tracks` relationship and `Track` has an `artist` relationship, use `readonly_field` on at least one side to break the cycle.
-
 - **Pydantic compatibility**: Either inherit from `SQLCrucibleBaseModel` (which includes the necessary config), or add `model_config = ConfigDict(ignored_types=(ReadonlyFieldDescriptor,))` to your model (import from `sqlcrucible`).
 
 - **Accessing without a backing model**: Accessing a `readonly_field` on an entity not loaded via `from_sa_model()` raises `RuntimeError`.
 
+## Serialisation
+
+By default, `readonly_field` values are **excluded** from `model_dump()` and `model_dump_json()`. This is by design — they are not Pydantic model fields.
+
+To include a readonly relationship in serialised output, wrap it with `computed_field`:
+
+```python
+from pydantic import computed_field
+
+class Track(SQLCrucibleBaseModel):
+    __sqlalchemy_params__ = {"__tablename__": "track"}
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
+    name: str
+    artist_id: Annotated[UUID, mapped_column(ForeignKey("artist.id"))]
+
+    artist = computed_field(readonly_field(
+        Artist,
+        relationship(lambda: SAType[Artist]),
+    ))
+```
+
+`ReadonlyFieldDescriptor` is a `property` subclass, so Pydantic's `computed_field` can infer the return type directly — no intermediate `@property` wrapper needed.
+
+!!! warning
+    If **both** sides of a bidirectional relationship wrap `readonly_field` with `computed_field`, Pydantic will detect a circular reference during `model_dump()` and raise a `ValueError`. Only expose one side of a cycle via `computed_field`.
+
+## Caching and Identity
+
+### Per-instance caching
+
+`readonly_field` caches the converted value per instance, so repeated access returns the same object:
+
+```python
+track = Track.from_sa_model(track_sa)
+track.artist is track.artist  # True — same object
+```
+
+This applies to all field types — entities, lists, and scalars.
+
+### Identity preservation
+
+Within a single `from_sa_model()` call, an identity map ensures that the same SQLAlchemy model instance always converts to the same entity. This means bidirectional relationships preserve object identity:
+
+```python
+author = Author.from_sa_model(author_sa)
+author.tracks[0].artist is author  # True — same entity, not a copy
+```
+
+Each top-level `from_sa_model()` call creates a fresh identity map, so separate calls produce independent instances:
+
+```python
+first = Author.from_sa_model(author_sa)
+second = Author.from_sa_model(author_sa)
+first is not second  # True — different calls, different instances
+```
+
 ## Example: One-to-Many Relationship
 
 ```python
 class Artist(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "artist"}
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     name: str
 
     # One-to-many: artist has many tracks
@@ -88,7 +142,7 @@ class Artist(SQLCrucibleBaseModel):
 
 class Track(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "track"}
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     name: str
     artist_id: Annotated[UUID, mapped_column(ForeignKey("artist.id"))]
 

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/docs/index.md

@@ -21,7 +21,7 @@ With SQLCrucible, you define your model once:
 
 ```python
 from typing import Annotated
-from uuid import UUID, uuid4
+from uuid import UUID, uuid7
 from pydantic import Field
 from sqlalchemy.orm import mapped_column
 from sqlcrucible import SQLCrucibleBaseModel
@@ -29,7 +29,7 @@ from sqlcrucible import SQLCrucibleBaseModel
 class Artist(SQLCrucibleBaseModel):
     __sqlalchemy_params__ = {"__tablename__": "artist"}
 
-    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid4)
+    id: Annotated[UUID, mapped_column(primary_key=True)] = Field(default_factory=uuid7)
     name: Annotated[str, mapped_column()]
 ```
 

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/mkdocs.yml

@@ -21,6 +21,7 @@ theme:
   features:
     - content.code.copy
     - content.code.annotate
+    - content.tabs.link
     - navigation.sections
     - navigation.expand
     - search.highlight

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/noxfile.py

@@ -11,6 +11,17 @@ nox.options.reuse_existing_virtualenvs = True
 
 SUPPORTED_PYTHON_VERSIONS = nox.project.python_versions(nox.project.load_toml("pyproject.toml"))
 MIN_PYTHON_VERSION = SUPPORTED_PYTHON_VERSIONS[0]
+PYDANTIC_VERSIONS = ["2.10", "2.11", "2.12"]
+PYDANTIC_MAX_PYTHON: dict[str, str] = {
+    "2.10": "3.13",
+    "2.11": "3.13",
+}
+_TEST_MATRIX = [
+    (python, pydantic)
+    for python in SUPPORTED_PYTHON_VERSIONS
+    for pydantic in PYDANTIC_VERSIONS
+    if pydantic not in PYDANTIC_MAX_PYTHON or python <= PYDANTIC_MAX_PYTHON[pydantic]
+]
 
 
 def uv(*args: str, session: nox.Session) -> None:
@@ -62,10 +73,12 @@ def depcheck(session: nox.Session) -> None:
     session.run("deptry", "src", "tests")
 
 
-@nox.session(python=SUPPORTED_PYTHON_VERSIONS)
-def test(session: nox.Session) -> None:
+@nox.session
+@nox.parametrize(("python", "pydantic"), _TEST_MATRIX)
+def test(session: nox.Session, pydantic: str) -> None:
     """Run tests with pytest."""
     uv("sync", "--group", "test", session=session)
+    session.install(f"pydantic~={pydantic}.0")
     session.run("pytest", *session.posargs)
 
 

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/pyproject.toml

@@ -36,6 +36,7 @@ version-file = "src/sqlcrucible/_version.py"
 test = [
     "pytest>=8.0.0",
     "pytest-cov>=6.0.0",
+    "hypothesis>=6.100.0",
     "pyright",
     "ty",
 ]
@@ -79,6 +80,9 @@ exclude_lines = [
 ]
 show_missing = true
 
+[tool.hypothesis]
+deadline = 400
+
 [tool.ruff]
 line-length = 100
 extend-exclude = ["_version.py"]

{sqlcrucible-0.3.2 → sqlcrucible-0.3.4}/src/sqlcrucible/_types/forward_refs.py

@@ -45,7 +45,7 @@ def resolve_forward_refs(tp: Any, owner: type) -> Any:
     )
     globalns = vars(sys.modules[owner.__module__])
     localns = vars(owner)
-    hints = get_type_hints(temp, globalns=globalns, localns=localns)
+    hints = get_type_hints(temp, globalns=globalns, localns=localns, include_extras=True)
     return hints["_"]