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

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

@@ -1,6 +1,24 @@
 # CHANGELOG
 
 
+## 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
+
+- **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.4}/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"
@@ -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.4"
 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",
@@ -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.2 → ferro_orm-0.10.4}/Cargo.toml

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.10.2
+Version: 0.10.4
 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.4/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.4}/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.4}/pyproject.toml

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

{ferro_orm-0.10.2 → ferro_orm-0.10.4}/src/lib.rs

@@ -9,6 +9,7 @@ mod connection;
 mod operations;
 mod query;
 mod schema;
+mod schema_bind;
 mod state;
 
 use crate::state::MODEL_REGISTRY;

{ferro_orm-0.10.2 → ferro_orm-0.10.4}/src/operations.rs

@@ -560,30 +560,6 @@ async fn postgres_temporal_cast_by_column(
     Ok(out)
 }
 
-fn postgres_enum_type_name_for_column(
-    col_name: &str,
-    enum_udt: &HashMap<String, String>,
-    col_info: Option<&serde_json::Value>,
-) -> Option<String> {
-    // db_type takes precedence over the JSON-schema enum_type_name: when the
-    // user has asked for `text` / `varchar(N)` / etc. storage, the column is
-    // no longer a native Postgres enum UDT and we must not CAST values to a
-    // non-existent type. This mirrors the Alembic-side _map_to_sa_type
-    // override. See AGENTS.md § I-1.
-    if let Some(info) = col_info
-        && info.get("db_type").and_then(|v| v.as_str()).is_some()
-    {
-        return None;
-    }
-
-    enum_udt.get(col_name).cloned().or_else(|| {
-        col_info?
-            .get("enum_type_name")?
-            .as_str()
-            .map(std::string::ToString::to_string)
-    })
-}
-
 fn schema_property<'a>(
     schema: &'a serde_json::Value,
     col_name: &str,
@@ -630,12 +606,10 @@ fn schema_value_expr(
 
     if let serde_json::Value::String(s) = value
         && backend == SqlDialect::Postgres
-        && let Some(tn) = postgres_enum_type_name_for_column(col_name, enum_udt, col_info)
+        && let Some(tn) =
+            crate::schema_bind::postgres_enum_type_name_for_column(col_name, enum_udt, col_info)
     {
-        return Ok(
-            Expr::value(sea_query::Value::String(Some(Box::new(s.clone()))))
-                .cast_as(Alias::new(tn.as_str())),
-        );
+        return Ok(crate::schema_bind::postgres_enum_string_rhs_expr(s, &tn));
     }
 
     if is_uuid_pg {
@@ -1572,7 +1546,7 @@ pub fn fetch_filtered<'py>(
     let name = cls.getattr("__name__")?.extract::<String>()?;
     let cls_py = cls.unbind();
 
-    let query_def: QueryDef = serde_json::from_str(&query_json).map_err(|e| {
+    let mut query_def: QueryDef = serde_json::from_str(&query_json).map_err(|e| {
         pyo3::exceptions::PyValueError::new_err(format!("Invalid query JSON: {}", e))
     })?;
 
@@ -1582,10 +1556,10 @@ pub fn fetch_filtered<'py>(
         let use_identity_map = engine.is_identity_map_enabled();
 
         let table_name = name.to_lowercase();
-        let pg_native_enum_cols: HashSet<String> = {
-            let m = postgres_enum_udt_by_column(&table_name, &engine, &tx_conn, backend).await?;
-            m.keys().cloned().collect()
-        };
+        let postgres_enum_udt =
+            postgres_enum_udt_by_column(&table_name, &engine, &tx_conn, backend).await?;
+        query_def.postgres_enum_udt = postgres_enum_udt.clone();
+        let pg_native_enum_cols: HashSet<String> = postgres_enum_udt.keys().cloned().collect();
         // ...
         let (sql, bind_values, pk_col, schema_for_decode) = {
             let registry = MODEL_REGISTRY.read().map_err(|_| {
@@ -1762,7 +1736,7 @@ pub fn count_filtered(
     tx_id: Option<String>,
     using: Option<String>,
 ) -> PyResult<Bound<'_, PyAny>> {
-    let query_def: QueryDef = serde_json::from_str(&query_json).map_err(|e| {
+    let mut query_def: QueryDef = serde_json::from_str(&query_json).map_err(|e| {
         pyo3::exceptions::PyValueError::new_err(format!("Invalid query JSON: {}", e))
     })?;
 
@@ -1770,6 +1744,8 @@ pub fn count_filtered(
         let (_, engine, tx_conn, backend) = active_route_for_operation(tx_id, using)?;
 
         let table_name = name.to_lowercase();
+        query_def.postgres_enum_udt =
+            postgres_enum_udt_by_column(&table_name, &engine, &tx_conn, backend).await?;
         // ... sql ...
         let (sql, bind_values) = {
             let mut select = Query::select();
@@ -1964,7 +1940,7 @@ pub fn delete_filtered(
     tx_id: Option<String>,
     using: Option<String>,
 ) -> PyResult<Bound<'_, PyAny>> {
-    let query_def: QueryDef = serde_json::from_str(&query_json).map_err(|e| {
+    let mut query_def: QueryDef = serde_json::from_str(&query_json).map_err(|e| {
         pyo3::exceptions::PyValueError::new_err(format!("Invalid query JSON: {}", e))
     })?;
 
@@ -1972,6 +1948,8 @@ pub fn delete_filtered(
         let (_, engine, tx_conn, backend) = active_route_for_operation(tx_id, using)?;
 
         let table_name = name.to_lowercase();
+        query_def.postgres_enum_udt =
+            postgres_enum_udt_by_column(&table_name, &engine, &tx_conn, backend).await?;
         // ... sql ...
         let (sql, bind_values) = {
             let mut delete = Query::delete();
@@ -2008,7 +1986,7 @@ pub fn update_filtered(
     tx_id: Option<String>,
     using: Option<String>,
 ) -> PyResult<Bound<'_, PyAny>> {
-    let query_def: QueryDef = serde_json::from_str(&query_json).map_err(|e| {
+    let mut query_def: QueryDef = serde_json::from_str(&query_json).map_err(|e| {
         pyo3::exceptions::PyValueError::new_err(format!("Invalid query JSON: {}", e))
     })?;
 
@@ -2025,6 +2003,7 @@ pub fn update_filtered(
 
         let table_name = name.to_lowercase();
         let enum_udt = postgres_enum_udt_by_column(&table_name, &engine, &tx_conn, backend).await?;
+        query_def.postgres_enum_udt = enum_udt.clone();
         let uuid_columns =
             postgres_uuid_column_names(&table_name, &engine, &tx_conn, backend).await?;
         let ts_cast =