ferro-orm 0.9.1__tar.gz → 0.9.2__tar.gz

{ferro_orm-0.9.1 → ferro_orm-0.9.2}/AGENTS.md

@@ -93,6 +93,14 @@ If you add a new schema feature (e.g. partial indexes, exclusion constraints):
 Python ORMs. The Rust core must populate model dicts directly via the bridge
 documented in `src/lib.rs` rather than calling `Model(**row)` from Rust.
 
+Hydrated instances must still be **observationally equivalent** to instances
+constructed through `BaseModel.__init__` for Pydantic’s own slot attributes:
+anything in `BaseModel.__slots__` that `__init__` assigns (notably
+`__pydantic_extra__` and `__pydantic_private__`, in addition to
+`__pydantic_fields_set__`) must be initialized on the Rust hydration path as
+well. Leaving a slot unset raises `AttributeError` on access (unlike a normal
+instance attribute defaulting to `None`).
+
 If you find yourself wanting to call `__init__` from Rust to "make this easier",
 stop and read `.cursorrules` §3.B and the design notes under
 `docs/solutions/patterns/`.

{ferro_orm-0.9.1 → ferro_orm-0.9.2}/CHANGELOG.md

@@ -1,6 +1,15 @@
 # CHANGELOG
 
 
+## v0.9.2 (2026-05-14)
+
+### Bug Fixes
+
+- **hydration**: Initialize Pydantic slots on Rust-hydrated models
+  ([#51](https://github.com/syn54x/ferro-orm/pull/51),
+  [`7609886`](https://github.com/syn54x/ferro-orm/commit/760988649bbfb41d1e46934cdea589efffdfa1b1))
+
+
 ## v0.9.1 (2026-05-11)
 
 ### Bug Fixes

{ferro_orm-0.9.1 → ferro_orm-0.9.2}/Cargo.lock

@@ -294,7 +294,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.9.1"
+version = "0.9.2"
 dependencies = [
  "dashmap",
  "once_cell",
@@ -2296,9 +2296,9 @@ dependencies = [
 
 [[package]]
 name = "zerofrom"
-version = "0.1.7"
+version = "0.1.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "69faa1f2a1ea75661980b013019ed6687ed0e83d069bc1114e2cc74c6c04c4df"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
 dependencies = [
  "zerofrom-derive",
 ]

{ferro_orm-0.9.1 → ferro_orm-0.9.2}/Cargo.toml

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

{ferro_orm-0.9.1 → ferro_orm-0.9.2}/PKG-INFO

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

ferro_orm-0.9.2/docs/solutions/issues/pydantic-slots-missing-after-ferro-hydration.md

@@ -0,0 +1,46 @@
+---
+title: AttributeError on __pydantic_extra__ after loading a row (zero-copy hydration)
+type: issue
+tags: [gotcha, pydantic, bridge, rust, hydration, ffi]
+related_files:
+  - src/operations.rs
+  - tests/test_hydration.py
+related_issues: []
+related_prs: [51]
+captured: 2026-05-14
+---
+
+## Problem
+
+Anything that touches Pydantic’s slot-backed internals on a model instance fails
+with `AttributeError: ... has no attribute '__pydantic_extra__'` (or
+`__pydantic_private__`) **after** the instance was hydrated by Ferro’s Rust
+core (for example `await Model.get(...)`, filtered query results), while the
+same code works if the instance was built with `Model(...)`.
+
+Typical stack traces include `dict(instance)` / `BaseModel.__iter__`, or
+third-party code that walks return values (for example Prefect’s
+`visit_collection`).
+
+## Takeaway
+
+Ferro intentionally bypasses `Model.__init__` for performance (see AGENTS.md
+I-2). Pydantic v2 stores several attributes in `__slots__`; **unset** slots do
+not behave like missing dict keys — reads raise `AttributeError`. The Rust
+hydration paths must assign the same defaults `BaseModel.__init__` would,
+including `__pydantic_extra__` (empty dict when `model_config["extra"] ==
+"allow"`, otherwise `None`) and `__pydantic_private__` (`None`).
+
+## Explanation
+
+The fix lives next to the existing `__pydantic_fields_set__` assignment in
+`src/operations.rs` (`set_pydantic_hydration_slots`).
+
+## How to recognize
+
+- Failure only on **fetched** / **query-hydrated** instances, not on freshly
+  constructed ones.
+- Error mentions `__pydantic_extra__` or `__pydantic_private__` inside Pydantic
+  or serialization helpers.
+- You recently added code that calls `dict(model)`, iterates the model, or runs
+  a framework that deep-visits objects.

{ferro_orm-0.9.1 → ferro_orm-0.9.2}/pyproject.toml

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

{ferro_orm-0.9.1 → ferro_orm-0.9.2}/src/operations.rs

@@ -61,6 +61,35 @@ fn active_connection_for_route(using: Option<String>) -> PyResult<(String, Arc<E
     connection_for_route(using)
 }
 
+/// Initialize Pydantic v2 slots that `BaseModel.__init__` normally sets, after zero-copy
+/// hydration (`__new__` + `__dict__` population).
+///
+/// These attributes live in `__slots__`; if never assigned, reads raise `AttributeError`,
+/// which breaks `dict(model)`, iteration, `model_copy`, and libraries that recurse results
+/// (for example Prefect's `visit_collection`).
+///
+/// When `model_config["extra"] == "allow"`, `__pydantic_extra__` starts as an empty dict;
+/// otherwise it is `None`. `__pydantic_private__` is always `None` for ORM-hydrated rows.
+fn set_pydantic_hydration_slots<'py>(
+    py: Python<'py>,
+    cls: &Bound<'py, PyAny>,
+    instance: &Bound<'py, PyAny>,
+) -> PyResult<()> {
+    let model_config = cls.getattr(pyo3::intern!(py, "model_config"))?;
+    let extra_policy = model_config.call_method1(
+        pyo3::intern!(py, "get"),
+        (pyo3::intern!(py, "extra"), pyo3::intern!(py, "ignore")),
+    )?;
+    let extra_slot = if extra_policy.eq(pyo3::intern!(py, "allow"))? {
+        pyo3::types::PyDict::new(py).into_any().unbind()
+    } else {
+        py.None()
+    };
+    instance.setattr(pyo3::intern!(py, "__pydantic_extra__"), extra_slot)?;
+    instance.setattr(pyo3::intern!(py, "__pydantic_private__"), py.None())?;
+    Ok(())
+}
+
 /// Map SeaQuery `Value` variants to `EngineBindValue`.
 ///
 /// Typed `None` variants are preserved as `Null(NullKind::T)` so the bind
@@ -1019,6 +1048,7 @@ pub fn fetch_all<'py>(
                 }
 
                 let _ = instance.setattr(pydantic_fields_set_str, fields_set);
+                set_pydantic_hydration_slots(py, &cls, &instance)?;
 
                 if use_identity_map {
                     if let Some(pk_val) = row_pk_val {
@@ -1185,6 +1215,7 @@ pub fn fetch_one<'py>(
                 }
 
                 let _ = instance.setattr(pyo3::intern!(py, "__pydantic_fields_set__"), fields_set);
+                set_pydantic_hydration_slots(py, &cls, &instance)?;
                 if use_identity_map {
                     IDENTITY_MAP.insert(
                         (connection_name.clone(), name.clone(), pk_val),
@@ -1691,6 +1722,7 @@ pub fn fetch_filtered<'py>(
                 }
 
                 let _ = instance.setattr(pydantic_fields_set_str, fields_set);
+                set_pydantic_hydration_slots(py, &cls, &instance)?;
 
                 if use_identity_map {
                     if let Some(pk_val) = row_pk_val {

ferro_orm-0.9.2/tests/test_hydration.py

@@ -0,0 +1,100 @@
+import pytest
+from pydantic import ConfigDict, Field
+
+import ferro
+from ferro import Model
+
+pytestmark = pytest.mark.backend_matrix
+
+
+INIT_CALLED_COUNT = 0
+
+
+@pytest.mark.asyncio
+async def test_direct_injection_bypasses_init(db_url):
+    """
+    Test that Ferro's Direct Injection bypasses the Python __init__ method.
+    """
+
+    # Use a unique class name for this test to avoid registry issues
+    class HydrationTestUser(Model):
+        id: int = Field(default=None, json_schema_extra={"primary_key": True})
+        name: str
+
+        def __init__(self, **data):
+            super().__init__(**data)
+            global INIT_CALLED_COUNT
+            INIT_CALLED_COUNT += 1
+
+    await ferro.connect(db_url, auto_migrate=True)
+
+    # 1. Create a record normally (this WILL call __init__)
+    global INIT_CALLED_COUNT
+    INIT_CALLED_COUNT = 0
+    user = HydrationTestUser(id=1, name="Direct Injector")
+    await user.save()
+    assert INIT_CALLED_COUNT == 1
+
+    # 2. Reset engine to clear Identity Map (so we force a DB fetch)
+    ferro.reset_engine()
+    await ferro.connect(db_url, auto_migrate=True)
+
+    # 3. Fetch the record
+    INIT_CALLED_COUNT = 0
+    fetched_user = await HydrationTestUser.get(1)
+
+    assert fetched_user is not None
+    assert fetched_user.name == "Direct Injector"
+
+    # CRITICAL ASSERTION: If Direct Injection is working, __init__ was never called
+    # by the Rust core when instantiating this object.
+    assert INIT_CALLED_COUNT == 0
+
+
+@pytest.mark.asyncio
+async def test_hydrated_row_initializes_pydantic_slots(db_url):
+    """Rust-hydrated instances must match __init__ for Pydantic slot attributes."""
+
+    class SlotCheckUser(Model):
+        id: int = Field(default=None, json_schema_extra={"primary_key": True})
+        name: str
+
+    await ferro.connect(db_url, auto_migrate=True)
+    created = SlotCheckUser(id=1, name="slot-check")
+    await created.save()
+
+    ferro.reset_engine()
+    await ferro.connect(db_url, auto_migrate=True)
+
+    row = await SlotCheckUser.get(1)
+    assert row is not None
+    assert dict(row)["name"] == "slot-check"
+    assert row.__pydantic_extra__ is None
+    assert row.__pydantic_private__ is None
+    copied = row.model_copy()
+    assert copied.name == row.name
+    assert dict(copied)["name"] == "slot-check"
+
+
+@pytest.mark.asyncio
+async def test_hydrated_extra_allow_starts_with_empty_extra_dict(db_url):
+    """When extra='allow', __pydantic_extra__ is {} even when no unknown keys exist."""
+
+    class ExtraAllowUser(Model):
+        model_config = ConfigDict(extra="allow")
+
+        id: int = Field(default=None, json_schema_extra={"primary_key": True})
+        name: str
+
+    await ferro.connect(db_url, auto_migrate=True)
+    created = ExtraAllowUser(id=1, name="ea")
+    await created.save()
+
+    ferro.reset_engine()
+    await ferro.connect(db_url, auto_migrate=True)
+
+    row = await ExtraAllowUser.get(1)
+    assert row is not None
+    assert row.__pydantic_extra__ == {}
+    assert row.__pydantic_private__ is None
+    assert dict(row)["name"] == "ea"

ferro_orm-0.9.1/tests/test_hydration.py

@@ -1,51 +0,0 @@
-import pytest
-from pydantic import Field
-
-import ferro
-from ferro import Model
-
-pytestmark = pytest.mark.backend_matrix
-
-
-INIT_CALLED_COUNT = 0
-
-
-@pytest.mark.asyncio
-async def test_direct_injection_bypasses_init(db_url):
-    """
-    Test that Ferro's Direct Injection bypasses the Python __init__ method.
-    """
-
-    # Use a unique class name for this test to avoid registry issues
-    class HydrationTestUser(Model):
-        id: int = Field(default=None, json_schema_extra={"primary_key": True})
-        name: str
-
-        def __init__(self, **data):
-            super().__init__(**data)
-            global INIT_CALLED_COUNT
-            INIT_CALLED_COUNT += 1
-
-    await ferro.connect(db_url, auto_migrate=True)
-
-    # 1. Create a record normally (this WILL call __init__)
-    global INIT_CALLED_COUNT
-    INIT_CALLED_COUNT = 0
-    user = HydrationTestUser(id=1, name="Direct Injector")
-    await user.save()
-    assert INIT_CALLED_COUNT == 1
-
-    # 2. Reset engine to clear Identity Map (so we force a DB fetch)
-    ferro.reset_engine()
-    await ferro.connect(db_url, auto_migrate=True)
-
-    # 3. Fetch the record
-    INIT_CALLED_COUNT = 0
-    fetched_user = await HydrationTestUser.get(1)
-
-    assert fetched_user is not None
-    assert fetched_user.name == "Direct Injector"
-
-    # CRITICAL ASSERTION: If Direct Injection is working, __init__ was never called
-    # by the Rust core when instantiating this object.
-    assert INIT_CALLED_COUNT == 0