ferro-orm 0.6.1__tar.gz → 0.7.0__tar.gz

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/CHANGELOG.md

@@ -1,6 +1,14 @@
 # CHANGELOG
 
 
+## v0.7.0 (2026-05-08)
+
+### Features
+
+- Per-connection identity_map on connect ([#47](https://github.com/syn54x/ferro-orm/pull/47),
+  [`0a1d629`](https://github.com/syn54x/ferro-orm/commit/0a1d62926538cde14fdd4f4deece21a59a1ede69))
+
+
 ## v0.6.1 (2026-05-07)
 
 ### Refactoring

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/Cargo.lock

@@ -79,9 +79,9 @@ checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "cc"
-version = "1.2.61"
+version = "1.2.62"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d16d90359e986641506914ba71350897565610e87ce0ad9e6f28569db3dd5c6d"
+checksum = "a1dce859f0832a7d088c4f1119888ab94ef4b5d6795d1ce05afb7fe159d79f98"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -294,7 +294,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.6.1"
+version = "0.7.0"
 dependencies = [
  "dashmap",
  "once_cell",
@@ -1699,9 +1699,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.52.2"
+version = "1.52.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "110a78583f19d5cdb2c5ccf321d1290344e71313c6c37d43520d386027d18386"
+checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
 dependencies = [
  "bytes",
  "libc",

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/Cargo.toml

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

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/PKG-INFO

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

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/pyproject.toml

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

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/src/backend.rs

@@ -30,6 +30,8 @@ impl BackendKind {
 pub struct EngineHandle {
     backend: BackendKind,
     pool: BackendPool,
+    /// When false, Ferro skips the identity map for this connection (no lookup/register on load).
+    identity_map_enabled: bool,
 }
 
 #[derive(Clone, Debug)]
@@ -116,6 +118,7 @@ impl EngineHandle {
         Self {
             backend: BackendKind::Sqlite,
             pool: BackendPool::Sqlite(Arc::new(pool)),
+            identity_map_enabled: true,
         }
     }
 
@@ -123,9 +126,23 @@ impl EngineHandle {
         Self {
             backend: BackendKind::Postgres,
             pool: BackendPool::Postgres(Arc::new(pool)),
+            identity_map_enabled: true,
         }
     }
 
+    /// Returns whether this connection uses the identity map (singleton instances per PK).
+    #[must_use]
+    pub fn is_identity_map_enabled(&self) -> bool {
+        self.identity_map_enabled
+    }
+
+    /// Sets identity-map behavior for this handle (used by `connect(identity_map=...)`).
+    #[must_use]
+    pub fn with_identity_map_enabled(mut self, enabled: bool) -> Self {
+        self.identity_map_enabled = enabled;
+        self
+    }
+
     pub fn backend(&self) -> BackendKind {
         self.backend
     }

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/src/connection.rs

@@ -187,7 +187,7 @@ async fn connect_engine_handle(
 /// # Errors
 /// Returns a `PyErr` if the connection fails or if auto-migration fails.
 #[pyfunction]
-#[pyo3(signature = (url, auto_migrate=false, name=None, default=false, max_connections=5, min_connections=0))]
+#[pyo3(signature = (url, auto_migrate=false, name=None, default=false, max_connections=5, min_connections=0, identity_map=true))]
 pub fn connect(
     py: Python<'_>,
     url: String,
@@ -196,6 +196,7 @@ pub fn connect(
     default: bool,
     max_connections: u32,
     min_connections: u32,
+    identity_map: bool,
 ) -> PyResult<Bound<'_, PyAny>> {
     let (connection_url, search_path) = split_search_path(&url);
     let redacted_url = redact_connection_url(&connection_url);
@@ -247,7 +248,8 @@ pub fn connect(
                 "DB Connection failed for {}: {}",
                 redacted_url, e
             ))
-        })?;
+        })?
+        .with_identity_map_enabled(identity_map);
 
         let engine_handle = Arc::new(engine_handle);
 

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/src/ferro/__init__.py

@@ -60,6 +60,8 @@ async def connect(
     name: str | None = None,
     default: bool = False,
     pool: PoolConfig | None = None,
+    *,
+    identity_map: bool = True,
 ) -> None:
     """
     Establish a connection to the database.
@@ -70,6 +72,9 @@ async def connect(
         name: Optional connection name. Omitted connections register as "default".
         default: If True, make this named connection the default for unqualified operations.
         pool: Optional per-connection pool configuration.
+        identity_map: If True (default), keep a per-connection identity map so the same primary
+            key maps to a single Python instance. If False, each load returns fresh instances and
+            the map is not consulted (lower memory use; no ``a is b`` guarantees across loads).
     """
     from .relations import resolve_relationships
 
@@ -83,6 +88,7 @@ async def connect(
         default=default,
         max_connections=pool_config.max_connections,
         min_connections=pool_config.min_connections,
+        identity_map=identity_map,
     )
 
 

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/src/ferro/_core.pyi

@@ -8,6 +8,8 @@ async def connect(
     default: bool = False,
     max_connections: int = 5,
     min_connections: int = 0,
+    *,
+    identity_map: bool = True,
 ) -> None: ...
 async def create_tables(using: Optional[str] = None) -> None: ...
 async def fetch_all(

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/src/operations.rs

@@ -910,6 +910,7 @@ pub fn fetch_all<'py>(
     pyo3_async_runtimes::tokio::future_into_py(py, async move {
         let (connection_name, engine, tx_conn, backend) =
             active_route_for_operation(tx_id, using)?;
+        let use_identity_map = engine.is_identity_map_enabled();
 
         let table_name = name.to_lowercase();
         let pg_native_enum_cols: HashSet<String> = {
@@ -991,12 +992,17 @@ pub fn fetch_all<'py>(
             let connection_attr_str = pyo3::intern!(py, "__ferro_connection_name");
 
             for (row_pk_val, fields) in parsed_data {
-                if let Some(ref pk_val) = row_pk_val
-                    && let Some(existing_obj) =
-                        IDENTITY_MAP.get(&(connection_name.clone(), name.clone(), pk_val.clone()))
-                {
-                    results.append(existing_obj.value().clone_ref(py))?;
-                    continue;
+                if use_identity_map {
+                    if let Some(ref pk_val) = row_pk_val
+                        && let Some(existing_obj) = IDENTITY_MAP.get(&(
+                            connection_name.clone(),
+                            name.clone(),
+                            pk_val.clone(),
+                        ))
+                    {
+                        results.append(existing_obj.value().clone_ref(py))?;
+                        continue;
+                    }
                 }
 
                 let instance = cls.call_method1(new_str, (cls,))?;
@@ -1014,11 +1020,13 @@ pub fn fetch_all<'py>(
 
                 let _ = instance.setattr(pydantic_fields_set_str, fields_set);
 
-                if let Some(pk_val) = row_pk_val {
-                    IDENTITY_MAP.insert(
-                        (connection_name.clone(), name.clone(), pk_val),
-                        instance.clone().unbind(),
-                    );
+                if use_identity_map {
+                    if let Some(pk_val) = row_pk_val {
+                        IDENTITY_MAP.insert(
+                            (connection_name.clone(), name.clone(), pk_val),
+                            instance.clone().unbind(),
+                        );
+                    }
                 }
 
                 results.append(instance)?;
@@ -1053,19 +1061,22 @@ pub fn fetch_one<'py>(
 ) -> PyResult<Bound<'py, PyAny>> {
     let name = cls.getattr("__name__")?.extract::<String>()?;
     let cls_py = cls.unbind();
-    let (connection_name, _) = active_connection_for_route(using.clone())?;
+    let (connection_name, engine) = active_connection_for_route(using.clone())?;
 
     // Check Identity Map first (if no transaction, or even with transaction, IM is usually safe)
-    if let Some(existing_obj) =
-        IDENTITY_MAP.get(&(connection_name.clone(), name.clone(), pk_val.clone()))
-    {
-        let obj = existing_obj.value().clone_ref(py);
-        return pyo3_async_runtimes::tokio::future_into_py(py, async move { Ok(obj) });
+    if engine.is_identity_map_enabled() {
+        if let Some(existing_obj) =
+            IDENTITY_MAP.get(&(connection_name.clone(), name.clone(), pk_val.clone()))
+        {
+            let obj = existing_obj.value().clone_ref(py);
+            return pyo3_async_runtimes::tokio::future_into_py(py, async move { Ok(obj) });
+        }
     }
 
     pyo3_async_runtimes::tokio::future_into_py(py, async move {
         let (connection_name, engine, tx_conn, backend) =
             active_route_for_operation(tx_id, using)?;
+        let use_identity_map = engine.is_identity_map_enabled();
 
         let table_name = name.to_lowercase();
         let pg_native_enum_cols: HashSet<String> = {
@@ -1174,10 +1185,12 @@ pub fn fetch_one<'py>(
                 }
 
                 let _ = instance.setattr(pyo3::intern!(py, "__pydantic_fields_set__"), fields_set);
-                IDENTITY_MAP.insert(
-                    (connection_name.clone(), name.clone(), pk_val),
-                    instance.clone().unbind(),
-                );
+                if use_identity_map {
+                    IDENTITY_MAP.insert(
+                        (connection_name.clone(), name.clone(), pk_val),
+                        instance.clone().unbind(),
+                    );
+                }
                 Ok(instance.into_any().unbind())
             }),
             None => Python::attach(|py| Ok(py.None())),
@@ -1523,6 +1536,7 @@ pub fn fetch_filtered<'py>(
     pyo3_async_runtimes::tokio::future_into_py(py, async move {
         let (connection_name, engine, tx_conn, backend) =
             active_route_for_operation(tx_id, using)?;
+        let use_identity_map = engine.is_identity_map_enabled();
 
         let table_name = name.to_lowercase();
         let pg_native_enum_cols: HashSet<String> = {
@@ -1650,12 +1664,17 @@ pub fn fetch_filtered<'py>(
             let connection_attr_str = pyo3::intern!(py, "__ferro_connection_name");
 
             for (row_pk_val, fields) in parsed_data {
-                if let Some(ref pk_val) = row_pk_val
-                    && let Some(existing_obj) =
-                        IDENTITY_MAP.get(&(connection_name.clone(), name.clone(), pk_val.clone()))
-                {
-                    results.append(existing_obj.value().clone_ref(py))?;
-                    continue;
+                if use_identity_map {
+                    if let Some(ref pk_val) = row_pk_val
+                        && let Some(existing_obj) = IDENTITY_MAP.get(&(
+                            connection_name.clone(),
+                            name.clone(),
+                            pk_val.clone(),
+                        ))
+                    {
+                        results.append(existing_obj.value().clone_ref(py))?;
+                        continue;
+                    }
                 }
 
                 let instance = cls.call_method1(new_str, (cls,))?;
@@ -1673,11 +1692,13 @@ pub fn fetch_filtered<'py>(
 
                 let _ = instance.setattr(pydantic_fields_set_str, fields_set);
 
-                if let Some(pk_val) = row_pk_val {
-                    IDENTITY_MAP.insert(
-                        (connection_name.clone(), name.clone(), pk_val),
-                        instance.clone().unbind(),
-                    );
+                if use_identity_map {
+                    if let Some(pk_val) = row_pk_val {
+                        IDENTITY_MAP.insert(
+                            (connection_name.clone(), name.clone(), pk_val),
+                            instance.clone().unbind(),
+                        );
+                    }
                 }
 
                 results.append(instance)?;
@@ -1802,8 +1823,10 @@ pub fn register_instance(
     obj: Py<PyAny>,
     using: Option<String>,
 ) -> PyResult<()> {
-    let (connection_name, _) = active_connection_for_route(using)?;
-    IDENTITY_MAP.insert((connection_name, name, pk), obj);
+    let (connection_name, engine) = active_connection_for_route(using)?;
+    if engine.is_identity_map_enabled() {
+        IDENTITY_MAP.insert((connection_name, name, pk), obj);
+    }
     Ok(())
 }
 
@@ -1811,8 +1834,10 @@ pub fn register_instance(
 #[pyfunction]
 #[pyo3(signature = (name, pk, using=None))]
 pub fn evict_instance(name: String, pk: String, using: Option<String>) -> PyResult<()> {
-    let (connection_name, _) = active_connection_for_route(using)?;
-    IDENTITY_MAP.remove(&(connection_name, name, pk));
+    let (connection_name, engine) = active_connection_for_route(using)?;
+    if engine.is_identity_map_enabled() {
+        IDENTITY_MAP.remove(&(connection_name, name, pk));
+    }
     Ok(())
 }
 
@@ -1920,7 +1945,9 @@ pub fn delete_filtered(
                 })?;
 
         // After bulk delete, we MUST clear the Identity Map for this model to avoid stale objects
-        IDENTITY_MAP.retain(|(_, m_name, _), _| m_name != &name);
+        if engine.is_identity_map_enabled() {
+            IDENTITY_MAP.retain(|(_, m_name, _), _| m_name != &name);
+        }
 
         Ok(rows_affected)
     })
@@ -1996,7 +2023,9 @@ pub fn update_filtered(
                 })?;
 
         // After bulk update, we MUST clear the Identity Map for this model to avoid stale objects
-        IDENTITY_MAP.retain(|(_, m_name, _), _| m_name != &name);
+        if engine.is_identity_map_enabled() {
+            IDENTITY_MAP.retain(|(_, m_name, _), _| m_name != &name);
+        }
 
         Ok(rows_affected)
     })

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/tests/test_alembic_type_mapping.py

@@ -5,6 +5,7 @@ from uuid import UUID
 
 import pytest
 import sqlalchemy as sa
+from pydantic import BaseModel, Field
 
 from ferro import FerroField, Model, clear_registry, reset_engine
 from ferro.migrations import get_metadata
@@ -58,6 +59,26 @@ def test_complex_type_mapping():
     assert isinstance(table.c.tags.type, sa.JSON)
 
 
+def test_list_of_nested_pydantic_models_maps_to_json_column():
+    """list[BaseModel] should emit an array JSON Schema and map to sa.JSON like other JSON columns."""
+
+    class JsonListPart(BaseModel):
+        name: str
+        count: int
+
+    class ModelWithNestedListJson(Model):
+        id: Annotated[int, FerroField(primary_key=True)]
+        parts: list[JsonListPart] = Field(default_factory=list)
+
+    meta = get_metadata()
+    table = meta.tables["modelwithnestedlistjson"]
+    assert isinstance(table.c.parts.type, sa.JSON)
+
+    props = ModelWithNestedListJson.__ferro_schema__["properties"]["parts"]
+    assert props.get("type") == "array"
+    assert props.get("items", {}).get("$ref") == "#/$defs/JsonListPart"
+
+
 def test_optional_complex_types():
     """Verify that Optional complex types are still mapped correctly."""
 

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/tests/test_connection.py

@@ -479,6 +479,7 @@ async def test_connect_passes_pool_config_to_core(monkeypatch):
                 "default": False,
                 "max_connections": 3,
                 "min_connections": 1,
+                "identity_map": True,
             },
         )
     ]

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/tests/test_crud.py

@@ -101,6 +101,27 @@ async def test_identity_map_consistency(db_url):
     assert user_a.id == 100
 
 
+@pytest.mark.asyncio
+async def test_identity_map_disabled_returns_distinct_instances(db_url):
+    """With identity_map=False, repeated loads are distinct objects (same field values)."""
+
+    class CrudUser(Model):
+        id: int = Field(default=None, json_schema_extra={"primary_key": True})
+        username: str
+        email: str
+
+    await ferro.connect(db_url, auto_migrate=True, identity_map=False)
+    u1 = CrudUser(id=200, username="nomap", email="nomap@test.com")
+    await u1.save()
+    results_1 = await CrudUser.all()
+    results_2 = await CrudUser.all()
+    user_a = results_1[0]
+    user_b = results_2[0]
+    assert user_a is not user_b
+    assert user_a.id == user_b.id == 200
+    assert user_a.username == user_b.username
+
+
 @pytest.mark.asyncio
 async def test_model_get_operation(db_url):
     """Test fetching a single record by primary key."""

{ferro_orm-0.6.1 → ferro_orm-0.7.0}/tests/test_structural_types.py

@@ -3,6 +3,9 @@ import uuid
 from decimal import Decimal
 from enum import Enum
 from typing import Annotated, Dict, List
+
+from pydantic import BaseModel, Field
+
 from ferro import Model, connect, FerroField
 
 pytestmark = pytest.mark.backend_matrix
@@ -78,6 +81,45 @@ async def test_structural_types_roundtrip(db_url):
     assert fetched.balance == balance
 
 
+@pytest.mark.asyncio
+async def test_json_column_list_of_nested_pydantic_models_roundtrip(db_url):
+    """list[BaseModel] stores as JSON; accepts models on write; reload yields dicts."""
+
+    class JsonListItem(BaseModel):
+        field_a: str
+        field_b: int
+
+    class JsonListParent(Model):
+        id: Annotated[int | None, FerroField(primary_key=True)] = None
+        items: list[JsonListItem] = Field(default_factory=list)
+
+    await connect(db_url, auto_migrate=True)
+
+    empty = await JsonListParent.create(items=[])
+    from ferro import evict_instance
+
+    evict_instance("JsonListParent", str(empty.id))
+    fetched_empty = await JsonListParent.get(empty.id)
+    assert fetched_empty is not None
+    assert fetched_empty.items == []
+
+    payload = [
+        JsonListItem(field_a="x", field_b=1),
+        JsonListItem(field_a="y", field_b=2),
+    ]
+    row = await JsonListParent.create(items=payload)
+    assert all(isinstance(it, JsonListItem) for it in row.items)
+    evict_instance("JsonListParent", str(row.id))
+    fetched = await JsonListParent.get(row.id)
+    assert fetched is not None
+    assert isinstance(fetched.items, list)
+    assert len(fetched.items) == 2
+    assert all(isinstance(it, dict) for it in fetched.items)
+    assert fetched.items == [p.model_dump() for p in payload]
+    revived = [JsonListItem.model_validate(it) for it in fetched.items]
+    assert revived == payload
+
+
 @pytest.mark.asyncio
 async def test_structural_filtering(db_url):
     """Test filtering by UUID and Decimal."""