ferro-orm 0.10.3__tar.gz → 0.10.5__tar.gz

{ferro_orm-0.10.3 → ferro_orm-0.10.5}/CHANGELOG.md

@@ -1,6 +1,24 @@
 # CHANGELOG
 
 
+## v0.10.5 (2026-05-25)
+
+### Bug Fixes
+
+- Coerce Annotated StrEnum fields on cold hydration
+  ([#66](https://github.com/syn54x/ferro-orm/pull/66),
+  [`c17c13b`](https://github.com/syn54x/ferro-orm/commit/c17c13b56e100028a42fa431ca59c9729a22daeb))
+
+
+## v0.10.4 (2026-05-24)
+
+### Bug Fixes
+
+- **query**: Cast native Postgres enum RHS in `.where()` filters
+  ([#64](https://github.com/syn54x/ferro-orm/pull/64),
+  [`7fea893`](https://github.com/syn54x/ferro-orm/commit/7fea89320fd2216a956ae32e8ae6f4829dd8fcf7))
+
+
 ## v0.10.3 (2026-05-21)
 
 ### Bug Fixes

{ferro_orm-0.10.3 → ferro_orm-0.10.5}/Cargo.lock

@@ -25,9 +25,9 @@ dependencies = [
 
 [[package]]
 name = "autocfg"
-version = "1.5.0"
+version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 
 [[package]]
 name = "base64"
@@ -61,9 +61,9 @@ dependencies = [
 
 [[package]]
 name = "bumpalo"
-version = "3.20.2"
+version = "3.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
 [[package]]
 name = "byteorder"
@@ -294,7 +294,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.10.3"
+version = "0.10.5"
 dependencies = [
  "dashmap",
  "once_cell",
@@ -711,9 +711,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "js-sys"
-version = "0.3.98"
+version = "0.3.99"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "67df7112613f8bfd9150013a0314e196f4800d3201ae742489d999db2f979f08"
+checksum = "142bc4740e452c1e57ade0cbc129f139c9093e354346f0872ef985f4f5cf5f11"
 dependencies = [
  "cfg-if",
  "futures-util",
@@ -788,9 +788,9 @@ dependencies = [
 
 [[package]]
 name = "log"
-version = "0.4.29"
+version = "0.4.30"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
+checksum = "616ec5685824bcc94416c6d4a7a446eea774a31efd7062c8480ba6fd06d7a6e5"
 
 [[package]]
 name = "md-5"
@@ -1292,9 +1292,9 @@ dependencies = [
 
 [[package]]
 name = "serde_json"
-version = "1.0.149"
+version = "1.0.150"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
 dependencies = [
  "itoa",
  "memchr",
@@ -1892,9 +1892,9 @@ checksum = "b8dad83b4f25e74f184f64c43b150b91efe7647395b42289f38e50566d82855b"
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.121"
+version = "0.2.122"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "49ace1d07c165b0864824eee619580c4689389afa9dc9ed3a4c75040d82e6790"
+checksum = "3ed04576f974d2b2fba0f38c51dbc5518011e38c36bf1143164be765528fd409"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -1905,9 +1905,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.121"
+version = "0.2.122"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8e68e6f4afd367a562002c05637acb8578ff2dea1943df76afb9e83d177c8578"
+checksum = "916151b09da36bd82f6615cbf3a419e2f0ba23a03c6160e8e92eb6bd4aa1dec6"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -1915,9 +1915,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.121"
+version = "0.2.122"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d95a9ec35c64b2a7cb35d3fead40c4238d0940c86d107136999567a4703259f2"
+checksum = "299047362ccbfce148b67ab7e73349f77748e00c8296f9542adfad2ad82c5c5e"
 dependencies = [
  "bumpalo",
  "proc-macro2",
@@ -1928,9 +1928,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.121"
+version = "0.2.122"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4e0100b01e9f0d03189a92b96772a1fb998639d981193d7dbab487302513441"
+checksum = "9a929b2c61f11ba3e9bc35b50c1f25cb38e0e892c0c231ae2b8cf78d5dad4437"
 dependencies = [
  "unicode-ident",
 ]

{ferro_orm-0.10.3 → ferro_orm-0.10.5}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ferro"
-version = "0.10.3"
+version = "0.10.5"
 edition = "2024"
 readme = "README.md"
 

{ferro_orm-0.10.3 → ferro_orm-0.10.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.10.3
+Version: 0.10.5
 Requires-Dist: pydantic>=2.0
 Requires-Dist: alembic>=1.18.1 ; extra == 'alembic'
 Requires-Dist: sqlalchemy>=2.0.46 ; extra == 'alembic'

ferro_orm-0.10.5/docs/brainstorms/2026-05-25-annotated-strenum-cold-hydration-requirements.md

@@ -0,0 +1,112 @@
+---
+date: 2026-05-25
+topic: annotated-strenum-cold-hydration
+issue: https://github.com/syn54x/ferro-orm/issues/65
+---
+
+# Annotated StrEnum Cold Hydration
+
+## Summary
+
+Register enum field types once at model class definition (using the same annotation-unwrapping logic as schema registration), then coerce string values from the database into enum members on every hydration path. This fixes cold fetches for `Annotated[StrEnum, FerroField(db_type="text")]` under PEP 563/649 deferred annotations without duplicating discovery logic in `_fix_types`.
+
+---
+
+## Problem Frame
+
+Ferro hydrates rows through a zero-copy Rust path that populates instance `__dict__` with raw column values. String-valued columns therefore arrive as `str`, not as the declared Python enum. A post-hydration pass (`Model._fix_types`) is responsible for coercing those strings into enum members.
+
+That pass discovers enum fields lazily on first use. Discovery calls `get_type_hints` with the **ferro.models** module namespace, not the user model’s defining module. With `from __future__ import annotations` (common on Python 3.14+), deferred annotation strings never resolve in that namespace; the fallback reads `__annotations__`, which are still strings and do not match `isinstance(hint, type)`. Result: `_enum_fields` stays empty, coercion is skipped, and cold reads return plain `str` even though `__ferro_schema__` already records `enum_type_name` correctly.
+
+`create()` in the same process often still yields enum instances because Pydantic validates on construction. The bug surfaces on **cold** `all()` / `get()` / query results after `reset_engine()` or a fresh connection — exactly when apps rely on `.value`, `match`/`case`, or strict `isinstance` checks.
+
+Equality with the raw string (`instance.mode == "hourly"`) still works; the failure mode is **type fidelity** and enum APIs, not storage or SQL.
+
+---
+
+## Requirements
+
+**Enum registration (canonical, class-definition time)**
+
+- R1. Each concrete `Model` subclass exposes a stable `_enum_fields: dict[str, type[Enum]]` populated during metaclass setup (Phase 3), not on first `_fix_types` call.
+- R2. Registration uses the shared `_enum_subclass_from_annotation` helper already used when building `__ferro_schema__`, so `Annotated[...]`, optional unions, and plain enum annotations are handled identically for schema and hydration.
+- R3. The source of truth for which fields are enums is Pydantic’s resolved `model_fields[<name>].annotation` (with `get_type_hints(cls, include_extras=True)` as fallback only when a field annotation is missing), never `get_type_hints` with ferro-internal `globals()` / `locals()`.
+- R4. `_fix_types` performs **coercion only** against the pre-built `_enum_fields` map; it must not re-scan annotations or mutate discovery state on fetch.
+
+**Hydration behavior**
+
+- R5. After any Rust-backed fetch (`all`, `get`, `fetch_filtered`, query builder `first`/`all`, `ModelConnection.get_or_none`, etc.), every non-null enum column whose stored value is not already an instance of the registered enum class is coerced via `enum_cls(raw_value)` (preserving current tolerant failure behavior for invalid DB values).
+- R6. Cold fetch after `reset_engine()` + reconnect must return enum members, not `str`, for models using `Annotated[StrEnum, FerroField(db_type="text")]` with PEP 563/649 deferred annotations.
+- R7. Behavior for plain `StrEnum` fields (no `Annotated`), native Postgres enum columns, and `IntEnum` with integer storage remains unchanged — no regression in existing round-trip tests.
+
+**Testing**
+
+- R8. Add an integration regression test that defines a model with `from __future__ import annotations`, `Annotated[StrEnum, FerroField(db_type="text")]`, inserts via `create()`, calls `reset_engine()`, reconnects, fetches via `all()` (or `get`), and asserts `isinstance(field, EnumSubclass)` and `.value` access works.
+- R9. Optionally assert `_enum_fields` is non-empty and includes the field name after class creation (unit-level guard against rediscovering the #65 failure mode).
+
+---
+
+## Acceptance Examples
+
+- **AE1 — Cold fetch with deferred annotations**
+  Covers: R5, R6, R8
+  Given `from __future__ import annotations` and `billing_mode: Annotated[Mode, FerroField(db_type="text")]`, when a row is created with `Mode.HOURLY`, then `reset_engine()` and reconnect, then `Row.all()[0]`, then `type(row.billing_mode)` is `Mode` and `row.billing_mode.value == "hourly"`.
+
+- **AE2 — Schema parity unchanged**
+  Covers: R2, R7
+  Given the same model class, `__ferro_schema__["properties"]["billing_mode"]["enum_type_name"]` remains `"mode"` (lowercased class name) before and after the fix.
+
+- **AE3 — Invalid DB value tolerance**
+  Covers: R5
+  Given a text column containing a string that is not a valid enum member, when fetched, the instance field remains a non-enum value (or coercion fails silently as today) without raising during `_fix_types` — no change to defensive behavior unless separately specified.
+
+---
+
+## Success Criteria
+
+- Issue #65 reproduction script exits 0 on main after the fix.
+- New regression test fails on current `main` without the fix and passes with it.
+- No new phantom DDL or cross-emitter drift (hydration-only change).
+- `_enum_fields` discovery logic exists in exactly one conceptual place (metaclass + shared helper), not duplicated in `_fix_types`.
+
+---
+
+## Scope Boundaries
+
+**In scope**
+
+- Python-side enum registration and post-hydration coercion for all existing fetch entry points.
+- Regression test under PEP 563/649 + `Annotated` + `db_type="text"`.
+- Closes GitHub issue #65.
+
+**Out of scope**
+
+- Rust-side enum coercion during dict population (duplicate logic across FFI; defer unless profiling proves Python coercion is a bottleneck).
+- Changing default storage away from native Postgres enums in Alembic (separate product decision; `db_type="text"` on StrEnum remains valid).
+- Pydantic `model_validate` on hydration (violates direct-to-dict / zero-copy invariant I-2).
+- Broader refactors of `_fix_types` for non-enum types (UUID, Decimal, etc.) unless already planned elsewhere.
+
+---
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Where to register enums | Metaclass Phase 3 | Same lifecycle as `ferro_fields` and schema registration; immune to wrong `get_type_hints` namespaces. |
+| Shared helper | Reuse `_enum_subclass_from_annotation` | Schema and hydration must agree on what counts as an enum field (AGENTS.md parity spirit). |
+| `_fix_types` role | Coercion only | Eliminates lazy discovery bug class; cheaper on hot path. |
+| Minimal patch alternative | Repair `_fix_types` discovery only | **Rejected as lesser solve** — fixes #65 but leaves two discovery paths and repeats failure modes for the next annotation shape. |
+
+---
+
+## Dependencies / Assumptions
+
+- Pydantic v2 continues to resolve `model_fields[].annotation` to real enum types even when `__annotations__` on the class remain strings under PEP 563.
+- `reset_engine()` remains a valid way to simulate cold identity-map clears in tests.
+- Issue reporter environment (ferro 0.10.3, Python 3.14+, SQLite) matches current test matrix support.
+
+---
+
+## Outstanding Questions
+
+- None blocking implementation. If PEP 649-only models without `__annotate_func__` resolution in metaclass appear in the wild, confirm `_resolve_deferred_annotations` still leaves `model_fields` authoritative (spot-check in plan phase).

ferro_orm-0.10.5/docs/plans/2026-05-25-001-fix-annotated-strenum-cold-hydration-plan.md

@@ -0,0 +1,228 @@
+---
+title: "fix: Annotated StrEnum cold hydration (#65)"
+type: fix
+status: completed
+date: 2026-05-25
+origin: docs/brainstorms/2026-05-25-annotated-strenum-cold-hydration-requirements.md
+issue: https://github.com/syn54x/ferro-orm/issues/65
+---
+
+# fix: Annotated StrEnum cold hydration (#65)
+
+## Summary
+
+Populate `Model._enum_fields` at class-definition time in `ModelMetaclass` using Pydantic’s resolved field annotations and `_enum_subclass_from_annotation`, then reduce `Model._fix_types` to coercion-only. Add a regression test that reproduces issue #65 (`from __future__ import annotations`, cold fetch after `reset_engine()`). Closes the gap where schema registration knows about enums but hydration does not.
+
+---
+
+## Problem Frame
+
+Cold Rust hydration leaves text-backed enum columns as `str`. `Model._fix_types` should coerce them back to enum members, but its lazy discovery uses `get_type_hints(cls, globalns=globals(), localns=locals())` inside `ferro.models` — the wrong namespace. Under PEP 563 (`from __future__ import annotations`), that raises `NameError` for `Annotated`, falls back to string `__annotations__`, and never populates `_enum_fields`. Schema registration already succeeds because `build_model_schema` resolves hints against the model’s defining module and uses `_enum_subclass_from_annotation`.
+
+Origin: `docs/brainstorms/2026-05-25-annotated-strenum-cold-hydration-requirements.md` (issue #65).
+
+---
+
+## Requirements Traceability
+
+| ID | Requirement | Plan unit |
+|----|-------------|-----------|
+| R1 | Stable `_enum_fields` at class definition | U1 |
+| R2 | Shared `_enum_subclass_from_annotation` | U1 |
+| R3 | Source: `model_fields[].annotation` (+ hints fallback) | U1 |
+| R4 | `_fix_types` coercion-only | U2 |
+| R5 | All fetch paths coerce | U2 (verify call sites) |
+| R6 | Cold fetch + PEP 563/649 | U3 |
+| R7 | No regression on existing enum tests | U3 |
+| R8 | New integration regression | U3 |
+| R9 | Optional `_enum_fields` unit guard | U3 |
+
+**Acceptance examples:** AE1 (cold fetch), AE2 (schema unchanged), AE3 (invalid DB value tolerance unchanged).
+
+---
+
+## Scope Boundaries
+
+- Python registration + `_fix_types` only; no Rust hydration changes.
+- No Pydantic `model_validate` on fetch (I-2 zero-copy hydration).
+- No changes to DDL / `enum_type_name` emission (already correct).
+
+**Rejected lesser approach:** Patching only `_fix_types` to call `get_type_hints(cls, include_extras=True)` without ferro `globals()` — fixes #65 but preserves duplicate discovery and drifts from schema logic. Document in PR if useful; do not implement unless explicitly requested.
+
+---
+
+## Context & Research
+
+### Root cause (verified)
+
+Reproduction on `main`:
+
+```text
+# with from __future__ import annotations
+billing_mode type: str
+Row._enum_fields: {}
+```
+
+`get_type_hints(Row, globalns=ferro.models.__dict__)` → `NameError: name 'Annotated' is not defined`.
+`get_type_hints(Row, include_extras=True)` (default module) → resolves `Mode`.
+`Row.model_fields['billing_mode'].annotation` → `<enum 'Mode'>` even when `__annotations__` is a string.
+
+### Call sites that invoke `_fix_types` (must remain covered)
+
+- `src/ferro/models.py`: `all`, `get`, instance method path, `ModelConnection.get_or_none`
+- `src/ferro/query/builder.py`: query result hydration
+
+No new call sites required if coercion map is populated at import.
+
+### Patterns to follow
+
+- `src/ferro/schema_metadata.py` — `_enum_subclass_from_annotation`, `build_model_schema` enum loop (lines ~144–159)
+- `src/ferro/metaclass.py` — Phase 3 post-creation hooks (`_validate_db_type_options` already uses `get_type_hints(cls, include_extras=True)`)
+- `tests/test_schema_enum_annotations.py` — schema-only coverage for deferred annotations; extend or sibling file for hydration
+
+### Institutional learnings
+
+- `docs/solutions/issues/pydantic-slots-missing-after-ferro-hydration.md` — hydration path must stay observationally equivalent to Pydantic instances; enum coercion is separate but same “post-Rust normalization” layer.
+- AGENTS.md I-2 — do not route hydration through `Model.__init__`.
+
+---
+
+## Key Technical Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Registration timing | Metaclass Phase 3, before/after schema generation | Same lifecycle as `ferro_fields`; map available before any fetch. |
+| Annotation source | `cls.model_fields` first | Already resolved by Pydantic; works for PEP 563 string `__annotations__`. |
+| Helper | Import `_enum_subclass_from_annotation` from `schema_metadata` | Single definition for schema + hydration (R2). |
+| `_fix_types` | Remove lazy discovery block; assume `_enum_fields` exists | `Model` base can set `_enum_fields = {}`; subclasses override at definition. |
+| Test placement | New `tests/test_enum_cold_hydration.py` | Keeps `test_schema_enum_annotations.py` schema-focused; cold path is integration-shaped. |
+
+---
+
+## Open Questions
+
+### Resolved
+
+- **Why does schema work but hydration fails?** Different `get_type_hints` namespaces and fallback to raw string annotations.
+- **Is Rust coercion needed?** No for this fix; Python post-pass is established pattern and cheap relative to FFI complexity.
+
+### Deferred to implementation
+
+- Whether to initialize `Model._enum_fields = {}` on the base `Model` class explicitly (recommended for `hasattr` simplification).
+
+---
+
+## Implementation Units
+
+### U1. Register `_enum_fields` in metaclass
+
+**Goal:** Every concrete model class has `cls._enum_fields: dict[str, type[Enum]]` before any query runs.
+
+**Requirements:** R1, R2, R3.
+
+**Dependencies:** None.
+
+**Files:**
+
+- Modify: `src/ferro/metaclass.py`
+- Optional import: `src/ferro/schema_metadata.py` (existing `_enum_subclass_from_annotation`)
+
+**Approach:**
+
+1. Add `@staticmethod def _register_enum_fields(cls) -> None` on `ModelMetaclass`.
+2. Iterate `cls.model_fields.items()`; for each `field_name`, `annotation = finfo.annotation`.
+3. Optional fallback per field: if annotation is a `str` or unresolved, try `get_type_hints(cls, include_extras=True).get(field_name)` (same pattern as `_validate_db_type_options`).
+4. `enum_cls = _enum_subclass_from_annotation(annotation)`; if not `None`, add to local dict.
+5. Assign `cls._enum_fields = mapping` (empty dict when no enums).
+6. Call from `__new__` Phase 3 after `super().__new__` and before or after `_generate_and_register_schema` (order irrelevant; both need resolved `model_fields`).
+
+**Test scenarios (U3):**
+
+- After class body definition with `from __future__ import annotations` and `Annotated[StrEnum, FerroField(...)]`, `ModelSubclass._enum_fields` contains the field name and enum class.
+
+---
+
+### U2. Simplify `_fix_types` to coercion-only
+
+**Goal:** Remove broken lazy discovery; coerce using pre-built map.
+
+**Requirements:** R4, R5.
+
+**Dependencies:** U1.
+
+**Files:**
+
+- Modify: `src/ferro/models.py`
+
+**Approach:**
+
+1. On base `Model`, set class attribute `_enum_fields: ClassVar[dict[str, type[Enum]]] = {}` (or document that only subclasses get populated).
+2. Replace `_fix_types` body:
+   - Remove `if not hasattr(cls, "_enum_fields")` discovery block entirely.
+   - Loop `for field_name, enum_cls in cls._enum_fields.items():` with existing coercion (`enum_cls(val)` on non-enum non-None values).
+3. Grep for `_enum_fields` mutations elsewhere; there should be none after U1.
+
+**Test scenarios:**
+
+- Covered by U3 integration test (exercises `all()` → `_fix_types`).
+
+---
+
+### U3. Regression tests
+
+**Goal:** Fail on current `main`; pass after U1+U2. Guard AE2/AE3.
+
+**Requirements:** R6–R9, AE1–AE3.
+
+**Dependencies:** U1, U2.
+
+**Files:**
+
+- Create: `tests/test_enum_cold_hydration.py`
+
+**Approach:**
+
+1. **AE1 / R6 / R8** — `test_annotated_strenum_text_cold_fetch_after_reset_engine(db_url)`:
+   - Module-level `from __future__ import annotations`.
+   - Inner model: `billing_mode: Annotated[Mode, FerroField(db_type="text")]`.
+   - `connect`, `create` with enum member, `reset_engine`, `connect`, `all()[0]`.
+   - Assert `isinstance(..., Mode)`, `.value == "hourly"`.
+2. **AE2 / R7** — In same test or sibling: assert `__ferro_schema__["properties"]["billing_mode"]["enum_type_name"] == "mode"`.
+3. **R9** — `test_enum_fields_populated_for_deferred_annotations`: after class definition, `assert Model._enum_fields["billing_mode"] is Mode` (no DB).
+4. Run existing enum-related tests: `tests/test_db_type_integration.py::test_strenum_text_storage_round_trip`, `tests/test_schema_enum_annotations.py`, `tests/test_structural_types.py` enum cases.
+
+**Execution posture:** Test-first — run new test before U1/U2 to confirm failure mode (`str`, empty `_enum_fields`).
+
+---
+
+## Sequencing
+
+```text
+U3 (write failing test) → U1 (metaclass registration) → U2 (_fix_types) → U3 (green) → full pytest enum subset
+```
+
+---
+
+## Verification Checklist
+
+- [ ] `uv run pytest tests/test_enum_cold_hydration.py -q`
+- [ ] Issue #65 repro script (inline or committed under `tests/` / `scripts/`) exits 0
+- [ ] `uv run pytest tests/test_schema_enum_annotations.py tests/test_db_type_integration.py -k enum -q` (or full file if fast)
+- [ ] No `get_type_hints(..., globalns=globals())` left in `_fix_types`
+- [ ] PR body: `Fixes #65`
+
+---
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Models defined before imports complete | Same as today for schema; `model_fields` is authoritative. |
+| Circular import metaclass ↔ schema_metadata | Already imports `build_model_schema`; adding enum helper is safe. |
+| Subclass redefines fields dynamically | Out of scope; Ferro models are static class definitions. |
+
+---
+
+## Handoff to implementation
+
+Use `ce-work` or manual implementation following unit order above. Estimated touch surface: ~40 lines metaclass, ~25 lines models, ~60 lines test.

{ferro_orm-0.10.3 → ferro_orm-0.10.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ferro-orm"
-version = "0.10.3"
+version = "0.10.5"
 description = "A high-performance, Rust-backed ORM for Python."
 readme = "README.md"
 authors = [

{ferro_orm-0.10.3 → ferro_orm-0.10.5}/src/ferro/metaclass.py

@@ -1,5 +1,6 @@
 import json
 import types
+from enum import Enum
 from typing import (
     Annotated,
     Any,
@@ -26,7 +27,7 @@ from .base import FerroField, ForeignKey, ManyToManyRelation
 from .fields import FERRO_FIELD_EXTRA_KEY
 from .query import FieldProxy, Relation
 from .relations.descriptors import ForwardDescriptor
-from .schema_metadata import build_model_schema
+from .schema_metadata import _enum_subclass_from_annotation, build_model_schema
 from .state import _MODEL_REGISTRY_PY, _PENDING_RELATIONS
 
 
@@ -57,6 +58,7 @@ class ModelMetaclass(type(BaseModel)):
         ferro_fields = mcs._parse_ferro_field_metadata(cls)
         cls.ferro_fields = ferro_fields
         mcs._validate_db_type_options(cls, ferro_fields)
+        mcs._register_enum_fields(cls)
         mcs._inject_relation_descriptors(cls, local_relations)
         mcs._generate_and_register_schema(cls, name, ferro_fields, local_relations)
 
@@ -397,6 +399,23 @@ class ModelMetaclass(type(BaseModel)):
 
         return ferro_fields
 
+    @staticmethod
+    def _register_enum_fields(cls) -> None:
+        """Populate ``cls._enum_fields`` from resolved Pydantic field annotations."""
+        enum_fields: dict[str, type[Enum]] = {}
+        try:
+            resolved = get_type_hints(cls, include_extras=True)
+        except Exception:
+            resolved = {}
+        for field_name, finfo in getattr(cls, "model_fields", {}).items():
+            annotation = finfo.annotation
+            if isinstance(annotation, str):
+                annotation = resolved.get(field_name, annotation)
+            enum_cls = _enum_subclass_from_annotation(annotation)
+            if enum_cls is not None:
+                enum_fields[field_name] = enum_cls
+        cls._enum_fields = enum_fields
+
     @staticmethod
     def _validate_db_type_options(cls, ferro_fields: dict) -> None:
         """Strict validation of ``Field(db_type=..., db_check=...)`` combinations.

{ferro_orm-0.10.3 → ferro_orm-0.10.5}/src/ferro/models.py

@@ -8,9 +8,6 @@ from typing import (
     Any,
     ClassVar,
     Self,
-    get_args,
-    get_origin,
-    get_type_hints,
     overload,
 )
 
@@ -46,7 +43,9 @@ def _transaction_or_using(using: str | None) -> tuple[str | None, str | None]:
         tx_connection = _CURRENT_TRANSACTION_CONNECTION.get()
         if using == tx_connection:
             return tx_id, None
-        raise ValueError("ORM operations inside a transaction inherit the transaction connection")
+        raise ValueError(
+            "ORM operations inside a transaction inherit the transaction connection"
+        )
     return tx_id, using
 
 
@@ -63,7 +62,9 @@ def _instance_transaction_route(
         if using is not None:
             if using == tx_connection:
                 return tx_id, None, origin or tx_connection
-            raise ValueError("ORM operations inside a transaction inherit the transaction connection")
+            raise ValueError(
+                "ORM operations inside a transaction inherit the transaction connection"
+            )
         return tx_id, None, origin or tx_connection
 
     effective_using = using or origin
@@ -155,6 +156,7 @@ class Model(BaseModel, metaclass=ModelMetaclass):
 
     __ferro_composite_uniques__: ClassVar[tuple[tuple[str, ...], ...]] = ()
     __ferro_composite_indexes__: ClassVar[tuple[tuple[str, ...], ...]] = ()
+    _enum_fields: ClassVar[dict[str, type[Enum]]] = {}
 
     @classmethod
     def _reregister_ferro(cls) -> None:
@@ -224,7 +226,9 @@ class Model(BaseModel, metaclass=ModelMetaclass):
             >>> user = User(name="Taylor")
             >>> await user.save()
         """
-        tx_id, operation_using, identity_using = _instance_transaction_route(self, using)
+        tx_id, operation_using, identity_using = _instance_transaction_route(
+            self, using
+        )
         new_id = await save_record(
             self.__class__.__name__, self.model_dump_json(), tx_id, operation_using
         )
@@ -251,7 +255,9 @@ class Model(BaseModel, metaclass=ModelMetaclass):
                     break
 
         if pk_val is not None:
-            register_instance(self.__class__.__name__, str(pk_val), self, identity_using)
+            register_instance(
+                self.__class__.__name__, str(pk_val), self, identity_using
+            )
             _set_instance_origin(self, identity_using)
 
     async def delete(self, *, using: str | None = None) -> None:
@@ -267,7 +273,9 @@ class Model(BaseModel, metaclass=ModelMetaclass):
         """
         pk_field_name = self.__class__._primary_key_field_name()
         pk_val = getattr(self, pk_field_name) if pk_field_name is not None else None
-        _tx_id, operation_using, identity_using = _instance_transaction_route(self, using)
+        _tx_id, operation_using, identity_using = _instance_transaction_route(
+            self, using
+        )
 
         if pk_val is not None:
             name = self.__class__.__name__
@@ -303,38 +311,6 @@ class Model(BaseModel, metaclass=ModelMetaclass):
         Returns:
             None
         """
-        if not hasattr(cls, "_enum_fields"):
-            cls._enum_fields = {}
-            try:
-                hints = get_type_hints(cls, globalns=globals(), localns=locals())
-                for field_name, hint in hints.items():
-                    actual_type = hint
-                    origin = get_origin(hint)
-                    from typing import Union as TypingUnion
-
-                    if origin is TypingUnion:
-                        args = get_args(hint)
-                        for arg in args:
-                            try:
-                                if isinstance(arg, type) and issubclass(arg, Enum):
-                                    actual_type = arg
-                                    break
-                            except TypeError:
-                                pass
-
-                    try:
-                        if isinstance(actual_type, type) and issubclass(
-                            actual_type, Enum
-                        ):
-                            cls._enum_fields[field_name] = actual_type
-                    except TypeError:
-                        pass
-            except Exception:
-                for field_name, hint in getattr(cls, "__annotations__", {}).items():
-                    if field_name not in cls._enum_fields:
-                        if isinstance(hint, type) and issubclass(hint, Enum):
-                            cls._enum_fields[field_name] = hint
-
         for field_name, enum_cls in cls._enum_fields.items():
             val = getattr(instance, field_name)
             if val is not None and not isinstance(val, enum_cls):
@@ -424,7 +400,9 @@ class Model(BaseModel, metaclass=ModelMetaclass):
             raise RuntimeError("Cannot refresh a model without a primary key")
 
         name = self.__class__.__name__
-        _tx_id, operation_using, identity_using = _instance_transaction_route(self, using)
+        _tx_id, operation_using, identity_using = _instance_transaction_route(
+            self, using
+        )
 
         evict_instance(name, str(pk_val), identity_using)
         query = self.__class__.where(getattr(self.__class__, pk_field_name) == pk_val)