sqlcrucible 0.3.3__tar.gz → 0.3.5__tar.gz

{sqlcrucible-0.3.3 → sqlcrucible-0.3.5}/.gitignore

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

{sqlcrucible-0.3.3 → sqlcrucible-0.3.5}/PKG-INFO

@@ -1,7 +1,9 @@
 Metadata-Version: 2.4
 Name: sqlcrucible
-Version: 0.3.3
+Version: 0.3.5
 Summary: Define a single model that works as both Pydantic and SQLAlchemy, with explicit conversion between the two
+Project-URL: Homepage, https://sqlcrucible.rdrj.uk
+Project-URL: Issues, https://github.com/RichardDRJ/sqlcrucible/issues
 Author-email: Richard Rae-Jones <sqlcrucible@richard.rdrj.uk>
 License-Expression: MIT
 License-File: LICENSE
@@ -10,6 +12,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
 Requires-Python: >=3.11
 Requires-Dist: pydantic~=2.10
 Requires-Dist: sqlalchemy~=2.0

{sqlcrucible-0.3.3 → sqlcrucible-0.3.5}/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.5/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.3 → sqlcrucible-0.3.5}/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.3 → sqlcrucible-0.3.5}/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.3 → sqlcrucible-0.3.5}/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.3 → sqlcrucible-0.3.5}/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.3 → sqlcrucible-0.3.5}/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"))]
 
@@ -81,7 +81,7 @@ from pydantic import computed_field
 
 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"))]
 
@@ -131,7 +131,7 @@ first is not second  # True — different calls, different instances
 ```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
@@ -142,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.3 → sqlcrucible-0.3.5}/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.3 → sqlcrucible-0.3.5}/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.3 → sqlcrucible-0.3.5}/pyproject.toml

@@ -8,7 +8,9 @@ authors = [
 ]
 requires-python = ">=3.11"
 license = "MIT"
+license-files = ["LICEN[CS]E*"]
 classifiers = [
+    "Topic :: Database",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -21,6 +23,10 @@ dependencies = [
     "typing-extensions ~= 4.15",
 ]
 
+[project.urls]
+Homepage = "https://sqlcrucible.rdrj.uk"
+Issues = "https://github.com/RichardDRJ/sqlcrucible/issues"
+
 [build-system]
 requires = ["hatchling", "hatch-vcs"]
 build-backend = "hatchling.build"
@@ -36,6 +42,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 +86,9 @@ exclude_lines = [
 ]
 show_missing = true
 
+[tool.hypothesis]
+deadline = 400
+
 [tool.ruff]
 line-length = 100
 extend-exclude = ["_version.py"]

{sqlcrucible-0.3.3 → sqlcrucible-0.3.5}/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["_"]
 
 

sqlcrucible-0.3.5/src/sqlcrucible/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.5'
+__version_tuple__ = version_tuple = (0, 3, 5)
+
+__commit_id__ = commit_id = None

{sqlcrucible-0.3.3 → sqlcrucible-0.3.5}/src/sqlcrucible/entity/annotations.py

@@ -30,7 +30,7 @@ class SQLAlchemyField:
     tp: Any | None = None
 
     @classmethod
-    def merge_all(cls, *fields: "SQLAlchemyField | None") -> "SQLAlchemyField":
+    def merge_all(cls, *fields: SQLAlchemyField | None) -> SQLAlchemyField:
         """Merge multiple SQLAlchemyField annotations, with later values taking precedence."""
         result = SQLAlchemyField()
         for field in fields:

{sqlcrucible-0.3.3 → sqlcrucible-0.3.5}/src/sqlcrucible/entity/automodel.py

@@ -9,7 +9,7 @@ import sqlalchemy.orm
 from sqlalchemy.orm.attributes import Mapped
 
 from sqlcrucible.entity.core import SQLAlchemyBase, SQLCrucibleEntity
-from sqlcrucible.entity.field_definitions import SQLAlchemyFieldDefinition
+from sqlcrucible.entity.field_definitions import SQLCrucibleField
 from sqlcrucible._types.forward_refs import resolve_forward_refs
 from sqlcrucible._types.transformer import (
     TypeTransformerChain,
@@ -77,14 +77,15 @@ def _create_automodel(source: type[SQLCrucibleEntity]) -> type[Any]:
     params = vars(source).get("__sqlalchemy_params__", {})
     base = _get_sa_base(source)
 
-    field_defs = source.__sqlalchemy_field_definitions__().values()
+    own_fields: dict[str, SQLCrucibleField] = source.__dict__.get("__sqlcrucible_fields__") or {}
+    field_defs = [decl for decl in own_fields.values() if not decl.excluded]
 
     # Determine which fields need type annotations based on SQLAlchemy's Mapped type.
     # Mapped represents attributes instrumented by the Mapper (columns, relationships),
     # which require annotations for SQLAlchemy to configure them. Non-Mapped descriptors
     # like hybrid_property and association_proxy are extensions that provide their own
     # functionality without mapper instrumentation, so they only need class attributes.
-    def needs_annotation(f: SQLAlchemyFieldDefinition) -> bool:
+    def needs_annotation(f: SQLCrucibleField) -> bool:
         return f.mapped_attr is None or isinstance(f.mapped_attr, Mapped)
 
     annotated_field_defs = [f for f in field_defs if needs_annotation(f)]
@@ -152,7 +153,7 @@ def _get_sa_base(annotation: type[SQLCrucibleEntity]) -> type[Any]:
 
 def _transform_field_type(
     owner: type[SQLCrucibleEntity],
-    field_def: SQLAlchemyFieldDefinition,
+    field_def: SQLCrucibleField,
 ) -> TypeTransformerResult:
     # Resolve any forward references in the source type first
     resolved_tp = resolve_forward_refs(field_def.source_tp, owner)