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

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

@@ -1,6 +1,24 @@
 # CHANGELOG
 
 
+## v0.10.3 (2026-05-21)
+
+### Bug Fixes
+
+- **query**: Typed predicates `col == None` / `!= None` → IS NULL / IS NOT NULL
+  ([#62](https://github.com/syn54x/ferro-orm/pull/62),
+  [`fd4b53e`](https://github.com/syn54x/ferro-orm/commit/fd4b53e26e01f8cf41a9b73de7c29b6901dee786))
+
+
+## v0.10.2 (2026-05-19)
+
+### Bug Fixes
+
+- Hydrate SQLite INTEGER-backed Decimal columns on reconnect
+  ([#59](https://github.com/syn54x/ferro-orm/pull/59),
+  [`6f13906`](https://github.com/syn54x/ferro-orm/commit/6f13906850300bc9e85c1274763c49bc5b318b5d))
+
+
 ## v0.10.1 (2026-05-19)
 
 ### Bug Fixes

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

@@ -247,9 +247,9 @@ checksum = "1aaf95b3e5c8f23aa320147307562d361db0ae0d51242340f558153b4eb2439b"
 
 [[package]]
 name = "either"
-version = "1.15.0"
+version = "1.16.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"
 dependencies = [
  "serde",
 ]
@@ -294,7 +294,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.10.1"
+version = "0.10.3"
 dependencies = [
  "dashmap",
  "once_cell",

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.10.1
+Version: 0.10.3
 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.1 → ferro_orm-0.10.3}/docs/solutions/issues/sqlite-null-hydrates-as-int-zero.md

@@ -5,7 +5,7 @@ tags: [gotcha, sqlite, hydration, bridge, rust, sqlalchemy, alembic, datetime, f
 related_files:
   - src/backend.rs
   - src/operations.rs
-  - tests/test_sqlite_null_hydration.py
+  - tests/test_sqlite_alembic_reconnect_hydration.py
 related_issues: [56]
 related_prs: [57]
 captured: 2026-05-18
@@ -62,7 +62,7 @@ by treating `0` as missing.
 
 - Rust: `engine_handle_fetches_sqlite_null_columns_as_null_not_zero`,
   `engine_handle_fetches_sqlite_non_null_zero_integer` in `src/backend.rs`.
-- Python: `tests/test_sqlite_null_hydration.py` (Alembic `create_all` + reconnect).
+- Python: `tests/test_sqlite_alembic_reconnect_hydration.py` (Alembic `create_all` + reconnect).
   Requires `aiosqlite` and `greenlet` in `ci-test` / `dev` so CI does not skip.
 
 ## How to recognize

ferro_orm-0.10.3/docs/solutions/issues/typed-where-null-panics-is-null.md

@@ -0,0 +1,107 @@
+---
+title: Typed WHERE filters with None panic or wrong SQL (IS NULL)
+type: issue
+tags: [gotcha, query, filter, is-null, bridge, ffi, rust, pyo3, sea-query, serde]
+related_files:
+  - src/query.rs
+  - src/ferro/query/nodes.py
+  - tests/test_typed_null_binds.py
+  - docs/solutions/patterns/typed-null-binds.md
+related_issues: [41, 61]
+related_prs: [62]
+captured: 2026-05-20
+last_updated: 2026-05-20
+---
+
+## Problem
+
+`Model.where(lambda t: t.col == None)` or `Model.col == None` / `!= None` used to
+panic in Rust (`node_to_condition_for_backend`) or, if it did not panic, would
+compile to `col = NULL`, which never matches rows in SQL.
+
+## Takeaway
+
+Python `None` on the filter RHS becomes JSON `"value": null`, which serde
+deserializes as `Option<serde_json::Value>::None` — not `Some(Value::Null)`.
+For `==` / `!=`, emit `IS NULL` / `IS NOT NULL` in `node_to_condition_for_backend`;
+never `unwrap()` `node.value` before checking for a null RHS. Bind typing for
+other operators stays in the typed-null bind pipeline — see
+`docs/solutions/patterns/typed-null-binds.md`.
+
+## Explanation
+
+**Causal chain**
+
+1. `QueryNode.to_dict()` serializes Python `None` as JSON `null` on `value`.
+2. Rust `QueryNode { value: Option<serde_json::Value> }` deserializes absent/null
+   as `None`, not `Some(Null)`.
+3. Pre-fix code: `let val = node.value.as_ref().unwrap();` → panic across FFI
+   (AGENTS.md I-3).
+4. Even without panic, `col.eq(bind_null)` yields `col = NULL`, which is always
+   unknown/false in three-valued logic — filters return no rows.
+
+**Fix (PR #62, issue #41)**
+
+```rust
+let rhs_is_json_null = node.value.as_ref().map_or(true, serde_json::Value::is_null);
+
+let expr: SimpleExpr = if rhs_is_json_null {
+    match node.operator.as_str() {
+        "==" => col.is_null(),
+        "!=" => col.is_not_null(),
+        // other ops: value_rhs_simple_expr_for_backend(..., &Value::Null, ...)
+        ...
+    }
+} else {
+    let val = node.value.as_ref().unwrap();
+    // existing non-null paths
+};
+```
+
+**Discovery before fix (session history)**
+
+During the April `refactor/typed-null-binds` work, the same wire shape was
+identified and GitHub #41 was filed; `test_filter_by_none_does_not_reproduce_38`
+stayed `xfail(strict=True)` until this fix landed on branch
+`cursor/fix-typed-predicate-null-is-null-f3a4`.
+
+**Tests**
+
+| Layer | File | What it pins |
+|-------|------|----------------|
+| Integration | `tests/test_typed_null_binds.py` | `test_filter_by_none_does_not_reproduce_38` — FieldProxy `== None` / `!= None` |
+| Integration | `tests/test_typed_null_binds.py` | `test_lambda_predicate_null_filter_datetime_and_json` — QueryProxy lambda on nullable datetime + JSON |
+| Rust unit | `src/query.rs` | `json_null_deserializes_to_option_none_for_query_node_value` |
+| Rust unit | `src/query.rs` | `where_rhs_none_emits_is_null_for_eq_sqlite` / `where_rhs_none_emits_is_not_null_for_ne_sqlite` |
+
+## How to recognize
+
+- Crash or opaque unwind when filtering with `== None` / `!= None` on any column
+  type (including `datetime | None` and `list | None` / JSON).
+- Grep finds `node.value.as_ref().unwrap()` in `node_to_condition_for_backend`
+  without a prior null-RHS guard.
+- Generated SQL contains `= null` instead of `is null` for None filters.
+- Distinct from issue #38 (typed **bind** `null::text` on INSERT) and #56 (SQLite
+  **fetch** NULL → `int(0)`); this is the **WHERE compile** path in `src/query.rs`.
+
+## Prevention
+
+- Treat JSON `null` on optional Rust fields as “SQL null intent,” not as “missing
+  field” — use `map_or(true, Value::is_null)` (or equivalent) before `unwrap`.
+- For every filter API that accepts Python `None`, add both FieldProxy and
+  QueryProxy lambda integration tests plus a Rust unit test on deserialized
+  `{"value": null}`.
+- Keep the invariant in `typed-null-binds.md` § “IS NULL for typed `== None`”
+  when adding new schema-driven emitters.
+
+## Related
+
+- Pattern: `docs/solutions/patterns/typed-null-binds.md` (bind layer + IS NULL rule)
+- Issue [#41]: https://github.com/syn54x/ferro-orm/issues/41
+- Issue [#61]: https://github.com/syn54x/ferro-orm/issues/61 (duplicate report)
+- PR [#62]: https://github.com/syn54x/ferro-orm/pull/62
+- Issue [#38]: typed-null binds on Postgres (orthogonal root cause)
+
+[#38]: https://github.com/syn54x/ferro-orm/issues/38
+[#41]: https://github.com/syn54x/ferro-orm/issues/41
+[#61]: https://github.com/syn54x/ferro-orm/issues/61

{ferro_orm-0.10.1 → ferro_orm-0.10.3}/docs/solutions/patterns/typed-null-binds.md

@@ -7,10 +7,11 @@ related_files:
   - src/operations.rs
   - src/query.rs
   - tests/test_typed_null_binds.py
-  - tests/test_sqlite_null_hydration.py
-related_issues: [38, 40, 56]
-related_prs: []
+  - tests/test_sqlite_alembic_reconnect_hydration.py
+related_issues: [38, 40, 41, 56]
+related_prs: [62]
 captured: 2026-04-29
+last_updated: 2026-05-20
 ---
 
 ## Problem
@@ -72,6 +73,11 @@ digraph typed_null_flow {
 | Filter null pick | `typed_null_for_column` (called by ^)                    | `src/query.rs`     |
 | M2M target IDs   | `backend_column_value_expr`                              | `src/operations.rs`|
 
+**`IS NULL` for typed `== None`:** JSON `null` on `QueryNode::value` deserializes
+as `Option<serde_json::Value>::None` (serde), not `Some(Value::Null)`.
+`node_to_condition_for_backend` maps `==` / `!=` with a null RHS to
+`IS NULL` / `IS NOT NULL` — never `= NULL`, which is never true in SQL.
+
 These functions inspect column metadata (JSON type, format, `uuid_columns`
 introspection, `ts_cast` metadata) and emit one of the typed SeaQuery `None`
 variants:
@@ -112,7 +118,7 @@ typed `try_get`. Non-null integer `0` is unchanged; only SQL `NULL` is affected.
 | Fetch (read)     | `materialize_engine_row`     | `is_null()` before `decode_non_null_*`|
 
 Rust regression: `engine_handle_fetches_sqlite_null_columns_as_null_not_zero`.
-Integration: `tests/test_sqlite_null_hydration.py` (Alembic schema + reconnect).
+Integration: `tests/test_sqlite_alembic_reconnect_hydration.py` (Alembic schema + reconnect).
 
 ## Raw-SQL boundary (explicit exception)
 
@@ -193,7 +199,12 @@ Ferro itself.
   NULL → `int(0)` on SQLite (issue [#56]).
 - Issue [#38]: the original bug report.
 - Issue [#40]: temporal typed binds (deferred follow-up).
+- Issue [#41]: filter `== None` panic / `IS NULL` compile path — debugging story in
+  `docs/solutions/issues/typed-where-null-panics-is-null.md`.
+- PR [#62]: `fix(query): typed predicates col == None → IS NULL / IS NOT NULL`.
 
 [#38]: https://github.com/syn54x/ferro-orm/issues/38
 [#40]: https://github.com/syn54x/ferro-orm/issues/40
+[#41]: https://github.com/syn54x/ferro-orm/issues/41
 [#56]: https://github.com/syn54x/ferro-orm/issues/56
+[#62]: https://github.com/syn54x/ferro-orm/pull/62

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

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

{ferro_orm-0.10.1 → ferro_orm-0.10.3}/src/operations.rs

@@ -193,6 +193,7 @@ fn engine_value_to_rust_value(
 
     if is_decimal {
         return match value {
+            EngineValue::I64(v) => RustValue::Decimal(v.to_string()),
             EngineValue::F64(v) => RustValue::Decimal(v.to_string()),
             EngineValue::String(v) => RustValue::Decimal(v),
             _ => RustValue::None,
@@ -3077,3 +3078,125 @@ mod raw_sql_tests {
         });
     }
 }
+
+#[cfg(test)]
+mod engine_value_to_rust_value_tests {
+    use super::engine_value_to_rust_value;
+    use crate::backend::EngineValue;
+    use crate::state::RustValue;
+
+    fn decimal_schema() -> serde_json::Value {
+        serde_json::json!({
+            "properties": {
+                "hours": {
+                    "format": "decimal",
+                    "anyOf": [
+                        {"type": "number"},
+                        {"type": "string", "pattern": "^-?\\d+(\\.\\d+)?$"}
+                    ]
+                }
+            }
+        })
+    }
+
+    #[test]
+    fn decimal_column_maps_sqlite_integer_affinity_to_decimal() {
+        let schema = decimal_schema();
+        let out = engine_value_to_rust_value(EngineValue::I64(3), &schema, "hours");
+        assert!(matches!(out, RustValue::Decimal(ref s) if s == "3"));
+    }
+
+    #[test]
+    fn decimal_column_maps_real_and_text() {
+        let schema = decimal_schema();
+        let from_real =
+            engine_value_to_rust_value(EngineValue::F64(1.5), &schema, "hours");
+        assert!(matches!(from_real, RustValue::Decimal(ref s) if s == "1.5"));
+        let from_text =
+            engine_value_to_rust_value(EngineValue::String("2.25".into()), &schema, "hours");
+        assert!(matches!(from_text, RustValue::Decimal(ref s) if s == "2.25"));
+    }
+
+    fn datetime_schema() -> serde_json::Value {
+        serde_json::json!({
+            "properties": {
+                "happened_at": {"type": "string", "format": "date-time"}
+            }
+        })
+    }
+
+    fn binary_schema() -> serde_json::Value {
+        serde_json::json!({
+            "properties": {
+                "data": {"type": "string", "format": "binary"}
+            }
+        })
+    }
+
+    fn bool_schema() -> serde_json::Value {
+        serde_json::json!({
+            "properties": {
+                "is_active": {"type": "boolean"}
+            }
+        })
+    }
+
+    fn json_schema() -> serde_json::Value {
+        serde_json::json!({
+            "properties": {
+                "payload": {"type": "object"}
+            }
+        })
+    }
+
+    #[test]
+    fn datetime_column_only_accepts_string_engine_values() {
+        let schema = datetime_schema();
+        let ok = engine_value_to_rust_value(
+            EngineValue::String("2026-04-24T18:30:00+00:00".into()),
+            &schema,
+            "happened_at",
+        );
+        assert!(matches!(ok, RustValue::DateTime(_)));
+        let from_int = engine_value_to_rust_value(EngineValue::I64(1713984600), &schema, "happened_at");
+        assert!(matches!(from_int, RustValue::BigInt(1713984600)));
+    }
+
+    #[test]
+    fn binary_column_maps_bytes_and_text() {
+        let schema = binary_schema();
+        let from_bytes =
+            engine_value_to_rust_value(EngineValue::Bytes(vec![1, 2, 3]), &schema, "data");
+        assert!(matches!(from_bytes, RustValue::Blob(v) if v == vec![1, 2, 3]));
+        let from_text =
+            engine_value_to_rust_value(EngineValue::String("abc".into()), &schema, "data");
+        assert!(matches!(from_text, RustValue::Blob(v) if v == b"abc".to_vec()));
+        let from_int = engine_value_to_rust_value(EngineValue::I64(1), &schema, "data");
+        assert!(matches!(from_int, RustValue::None));
+    }
+
+    #[test]
+    fn bool_column_maps_integer_and_bool() {
+        let schema = bool_schema();
+        assert!(matches!(
+            engine_value_to_rust_value(EngineValue::I64(1), &schema, "is_active"),
+            RustValue::Bool(true)
+        ));
+        assert!(matches!(
+            engine_value_to_rust_value(EngineValue::Bool(false), &schema, "is_active"),
+            RustValue::Bool(false)
+        ));
+    }
+
+    #[test]
+    fn json_column_parses_string_payload() {
+        let schema = json_schema();
+        let out = engine_value_to_rust_value(
+            EngineValue::String(r#"{"k":"v"}"#.into()),
+            &schema,
+            "payload",
+        );
+        assert!(matches!(out, RustValue::Json(v) if v.get("k").and_then(|x| x.as_str()) == Some("v")));
+    }
+
+}

{ferro_orm-0.10.1 → ferro_orm-0.10.3}/src/query.rs

@@ -63,10 +63,75 @@ impl QueryDef {
             }
         } else {
             let col_name = node.column.as_ref().unwrap();
-            let val = node.value.as_ref().unwrap();
             let col = Expr::col(Alias::new(col_name));
 
-            let expr: SimpleExpr =
+            // Python `None` becomes JSON `null`, which serde deserializes as
+            // `Option<serde_json::Value>::None` (not `Some(Null)`). SQL `col = NULL`
+            // is never true — use `IS NULL` / `IS NOT NULL` for `== None` / `!= None`.
+            let rhs_is_json_null = node.value.as_ref().map_or(true, serde_json::Value::is_null);
+
+            let expr: SimpleExpr = if rhs_is_json_null {
+                match node.operator.as_str() {
+                    "==" => col.is_null(),
+                    "!=" => col.is_not_null(),
+                    "<" => col.lt(self.value_rhs_simple_expr_for_backend(
+                        col_name,
+                        &Value::Null,
+                        false,
+                        backend,
+                    )),
+                    "<=" => col.lte(self.value_rhs_simple_expr_for_backend(
+                        col_name,
+                        &Value::Null,
+                        false,
+                        backend,
+                    )),
+                    ">" => col.gt(self.value_rhs_simple_expr_for_backend(
+                        col_name,
+                        &Value::Null,
+                        false,
+                        backend,
+                    )),
+                    ">=" => col.gte(self.value_rhs_simple_expr_for_backend(
+                        col_name,
+                        &Value::Null,
+                        false,
+                        backend,
+                    )),
+                    "IN" => {
+                        let val = node.value.as_ref().unwrap_or(&Value::Null);
+                        if let Some(vals) = val.as_array() {
+                            let rhs: Vec<SimpleExpr> = vals
+                                .iter()
+                                .map(|v| {
+                                    self.value_rhs_simple_expr_for_backend(
+                                        col_name, v, false, backend,
+                                    )
+                                })
+                                .collect();
+                            col.is_in(rhs)
+                        } else {
+                            col.eq(self
+                                .value_rhs_simple_expr_for_backend(col_name, val, false, backend))
+                        }
+                    }
+                    "LIKE" => {
+                        let val = node.value.as_ref().unwrap_or(&Value::Null);
+                        let pattern = match val {
+                            Value::String(s) => s.clone(),
+                            _ => val.to_string(),
+                        };
+                        col.like(pattern)
+                    }
+                    _ => col.eq(self.value_rhs_simple_expr_for_backend(
+                        col_name,
+                        &Value::Null,
+                        false,
+                        backend,
+                    )),
+                }
+            } else {
+                let val = node.value.as_ref().unwrap();
                 match node.operator.as_str() {
                     "==" => col
                         .eq(self.value_rhs_simple_expr_for_backend(col_name, val, false, backend)),
@@ -105,7 +170,8 @@ impl QueryDef {
                     }
                     _ => col
                         .eq(self.value_rhs_simple_expr_for_backend(col_name, val, false, backend)),
-                };
+                }
+            };
             Condition::all().add(expr)
         }
     }
@@ -360,7 +426,7 @@ pub(crate) fn property_schema_is_uuid(col_info: &Value) -> bool {
 
 #[cfg(test)]
 mod tests {
-    use super::QueryDef;
+    use super::{QueryDef, QueryNode};
     use crate::backend::BackendKind;
     use sea_query::{Alias, PostgresQueryBuilder, Query, SqliteQueryBuilder, Value as SeaValue};
     use serde_json::json;
@@ -385,6 +451,75 @@ mod tests {
         values.0.into_iter().next().expect("one value")
     }
 
+    #[test]
+    fn json_null_deserializes_to_option_none_for_query_node_value() {
+        let node: QueryNode = serde_json::from_value(json!({
+            "is_compound": false,
+            "column": "count",
+            "operator": "==",
+            "value": null
+        }))
+        .unwrap();
+        assert!(node.value.is_none());
+    }
+
+    #[test]
+    fn where_rhs_none_emits_is_null_for_eq_sqlite() {
+        let node: QueryNode = serde_json::from_value(json!({
+            "is_compound": false,
+            "column": "attached_at",
+            "operator": "==",
+            "value": null
+        }))
+        .unwrap();
+        let q = QueryDef {
+            model_name: "Pending".to_string(),
+            where_clause: vec![node],
+            order_by: None,
+            limit: None,
+            offset: None,
+            m2m: None,
+        };
+        let mut select = Query::select();
+        select
+            .from(Alias::new("pending"))
+            .cond_where(q.to_condition_for_backend(BackendKind::Sqlite));
+        let sql = select.to_string(SqliteQueryBuilder).to_lowercase();
+        assert!(sql.contains("is null"), "expected IS NULL, got {sql}");
+        assert!(
+            !sql.contains("= null"),
+            "must not emit `= NULL` (always unknown in SQL): {sql}"
+        );
+    }
+
+    #[test]
+    fn where_rhs_none_emits_is_not_null_for_ne_sqlite() {
+        let node: QueryNode = serde_json::from_value(json!({
+            "is_compound": false,
+            "column": "payload",
+            "operator": "!=",
+            "value": null
+        }))
+        .unwrap();
+        let q = QueryDef {
+            model_name: "Pending".to_string(),
+            where_clause: vec![node],
+            order_by: None,
+            limit: None,
+            offset: None,
+            m2m: None,
+        };
+        let mut select = Query::select();
+        select
+            .from(Alias::new("pending"))
+            .cond_where(q.to_condition_for_backend(BackendKind::Sqlite));
+        let sql = select.to_string(SqliteQueryBuilder).to_lowercase();
+        assert!(
+            sql.contains("is not null"),
+            "expected IS NOT NULL, got {sql}"
+        );
+    }
+
     #[test]
     fn uuid_rhs_emits_typed_uuid_bind_on_postgres_no_cast() {
         let query_def = empty_query_def("Widget");