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

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

@@ -1,6 +1,15 @@
 # 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

{ferro_orm-0.10.2 → 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.2"
+version = "0.10.3"
 dependencies = [
  "dashmap",
  "once_cell",

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.10.2
+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.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.2 → ferro_orm-0.10.3}/docs/solutions/patterns/typed-null-binds.md

@@ -8,9 +8,10 @@ related_files:
   - src/query.rs
   - tests/test_typed_null_binds.py
   - tests/test_sqlite_alembic_reconnect_hydration.py
-related_issues: [38, 40, 56]
-related_prs: []
+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:
@@ -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.2 → ferro_orm-0.10.3}/pyproject.toml

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

{ferro_orm-0.10.2 → 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");

{ferro_orm-0.10.2 → ferro_orm-0.10.3}/tests/test_typed_null_binds.py

@@ -6,29 +6,22 @@ The original bug was a PostgreSQL-only "null is text" failure. Postgres rejects
 and never reproduced #38; many of the round-trip assertions here are
 ``postgres_only`` because that's where the failure shape lives.
 
-Two known pre-existing bugs are *out of scope* for this refactor and limit
-what the matrix can assert. When either is fixed, drop the corresponding
-``xfail``/``postgres_only`` marker on the test below.
-
-1. `#41 <https://github.com/syn54x/ferro-orm/issues/41>`_ --
-   ``Model.where(Model.col == None)`` panics in the Rust query builder
-   (``query.rs::node_to_condition_for_backend`` unwraps ``node.value``).
-   Backend-agnostic: surfaces on both SQLite and Postgres before any SQL
-   is generated, so ``test_filter_by_none_does_not_reproduce_38`` is
-   ``xfail(strict=True)`` until #41 closes -- the strict marker means the
-   test will XPASS-as-failure the moment #41 is fixed, prompting us to
-   drop the marker.
-2. `#42 <https://github.com/syn54x/ferro-orm/issues/42>`_ --
-   ``UPDATE col = NULL`` on SQLite reads back as ``0`` (or the type's zero
-   value) due to a hydration issue in ``materialize_engine_row``. SQLite-
-   specific, so ``test_update_to_none_for_each_type`` is ``postgres_only``.
+One known pre-existing bug is *out of scope* for this refactor and limits
+what the matrix can assert. When it is fixed, drop the corresponding
+``postgres_only`` marker on the test below.
+
+- `#42 <https://github.com/syn54x/ferro-orm/issues/42>`_ --
+  ``UPDATE col = NULL`` on SQLite reads back as ``0`` (or the type's zero
+  value) due to a hydration issue in ``materialize_engine_row``. SQLite-
+  specific, so ``test_update_to_none_for_each_type`` is ``postgres_only``.
 
 See ``docs/plans/2026-04-29-001-typed-null-binds-plan.md`` for context.
 """
 
 import uuid
+from datetime import UTC, datetime
 from decimal import Decimal
-from typing import Annotated
+from typing import Annotated, Any
 
 import pytest
 from pydantic import Field
@@ -284,22 +277,12 @@ async def test_update_to_none_executes_without_error(db_url):
 
 
 @pytest.mark.asyncio
-@pytest.mark.xfail(
-    strict=True,
-    reason=(
-        "Blocked by #41: filter `col == None` panics in "
-        "node_to_condition_for_backend (Option::unwrap on node.value) "
-        "before any SQL reaches the backend. Strict so we get an XPASS "
-        "signal the moment #41 is fixed, then drop this marker."
-    ),
-)
+@pytest.mark.backend_matrix
 async def test_filter_by_none_does_not_reproduce_38(db_url):
-    """Query filter ``WHERE col == None`` on a nullable integer column must
-    not fail with a Postgres OID type error.
+    """Query filter ``col == None`` compiles to ``IS NULL`` and matches rows.
 
-    Backend-agnostic: the panic from #41 short-circuits this test on every
-    backend, not just SQLite. Confirmed reproduced on Postgres while running
-    the full matrix during the typed-null-binds refactor."""
+    Regression for #41 (Rust panic on JSON null RHS). Also ensures the
+    typed-null bind path does not regress #38 on Postgres."""
 
     class Filterable(Model):
         id: Annotated[int | None, FerroField(primary_key=True)] = None
@@ -307,12 +290,57 @@ async def test_filter_by_none_does_not_reproduce_38(db_url):
 
     await connect(db_url, auto_migrate=True)
 
-    await Filterable.create(count=1)
-    await Filterable.create()  # count = None
+    with_value = await Filterable.create(count=1)
+    null_row = await Filterable.create()  # count = None
+
+    matched_null = await Filterable.where(Filterable.count == None).all()  # noqa: E711
+    assert len(matched_null) == 1
+    assert matched_null[0].id == null_row.id
+
+    matched_non_null = await Filterable.where(Filterable.count != None).all()  # noqa: E711
+    assert len(matched_non_null) == 1
+    assert matched_non_null[0].id == with_value.id
+
+
+@pytest.mark.asyncio
+@pytest.mark.backend_matrix
+async def test_lambda_predicate_null_filter_datetime_and_json(db_url):
+    """Lambda ``where`` with ``== None`` / ``!= None`` on nullable datetime and JSON.
+
+    Regression for #41 using the API shape from the bug report (``QueryProxy``
+    + JSON ``null`` RHS), not only ``FieldProxy`` comparisons."""
+
+    class Pending(Model):
+        id: Annotated[int | None, FerroField(primary_key=True)] = None
+        name: str
+        attached_at: datetime | None = None
+        payload: list[Any] | None = None
+
+    await connect(db_url, auto_migrate=True)
+
+    null_dt = await Pending.create(name="null-dt", attached_at=None, payload=[{"x": 1}])
+    null_json = await Pending.create(name="null-json", attached_at=datetime.now(UTC))
+    with_values = await Pending.create(
+        name="set",
+        attached_at=datetime.now(UTC),
+        payload=[{"x": 2}],
+    )
+
+    matched_dt_null = await Pending.where(lambda t: t.attached_at == None).all()  # noqa: E711
+    assert len(matched_dt_null) == 1
+    assert matched_dt_null[0].id == null_dt.id
+
+    matched_json_null = await Pending.where(lambda t: t.payload == None).all()  # noqa: E711
+    assert len(matched_json_null) == 1
+    assert matched_json_null[0].id == null_json.id
+
+    matched_dt_set = await Pending.where(lambda t: t.attached_at != None).all()  # noqa: E711
+    assert len(matched_dt_set) == 2
+    assert {r.id for r in matched_dt_set} == {null_json.id, with_values.id}
 
-    # The assertion is "no Postgres OID error", not match counts.
-    matched = await Filterable.where(Filterable.count == None).all()  # noqa: E711
-    assert isinstance(matched, list)
+    matched_json_set = await Pending.where(lambda t: t.payload != None).all()  # noqa: E711
+    assert len(matched_json_set) == 2
+    assert {r.id for r in matched_json_set} == {null_dt.id, with_values.id}
 
 
 @pytest.mark.asyncio