ferrum-orm 0.1.13__tar.gz → 0.1.15__tar.gz

{ferrum_orm-0.1.13 → ferrum_orm-0.1.15}/Cargo.lock

@@ -223,7 +223,7 @@ checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
 [[package]]
 name = "ferrum-core"
-version = "0.1.13"
+version = "0.1.15"
 dependencies = [
  "criterion",
  "proptest",
@@ -234,7 +234,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-migrate"
-version = "0.1.13"
+version = "0.1.15"
 dependencies = [
  "ferrum-core",
  "serde",
@@ -243,7 +243,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-pyo3"
-version = "0.1.13"
+version = "0.1.15"
 dependencies = [
  "ferrum-core",
  "ferrum-sql",
@@ -255,7 +255,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-sql"
-version = "0.1.13"
+version = "0.1.15"
 dependencies = [
  "criterion",
  "ferrum-core",

{ferrum_orm-0.1.13 → ferrum_orm-0.1.15}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/ferrum-core", "crates/ferrum-sql", "crates/ferrum-pyo3"]
 resolver = "2"
 
 [workspace.package]
-version = "0.1.13"
+version = "0.1.15"
 edition = "2021"
 authors = ["Ferrum Contributors"]
 license = "Apache-2.0"

{ferrum_orm-0.1.13 → ferrum_orm-0.1.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferrum-orm
-Version: 0.1.13
+Version: 0.1.15
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers

{ferrum_orm-0.1.13 → ferrum_orm-0.1.15}/crates/ferrum-core/src/ir/mod.rs

@@ -208,6 +208,9 @@ pub struct JoinFieldRef {
     /// Operator allowlist copied from the remote field's ``FieldMeta`` (SQL-2).
     #[serde(default)]
     pub allowed_operators: Vec<String>,
+    /// Remote field type used for type-specific SQL operator emission.
+    #[serde(default)]
+    pub field_type: Option<metadata::FieldType>,
 }
 
 /// The SQL operation this IR node represents.

{ferrum_orm-0.1.13 → ferrum_orm-0.1.15}/crates/ferrum-sql/src/emit.rs

@@ -976,7 +976,7 @@ fn resolve_filter_column(
     joins: &[JoinSpec],
     table: &str,
     qualify_columns: bool,
-) -> Result<String, CompileError> {
+) -> Result<(String, ferrum_core::ir::metadata::FieldType), CompileError> {
     if let Some(alias) = &filter.join_alias {
         let join =
             joins
@@ -995,13 +995,17 @@ fn resolve_filter_column(
             })?;
         let alias_q = dialect.quote_ident(&join.alias);
         let col_q = dialect.quote_ident(&remote.column);
-        Ok(format!("{alias_q}.{col_q}"))
+        Ok((
+            format!("{alias_q}.{col_q}"),
+            remote
+                .field_type
+                .unwrap_or(ferrum_core::ir::metadata::FieldType::Text),
+        ))
     } else {
-        Ok(qualify_base_column(
-            dialect,
-            table,
-            &metadata.fields[filter.field.index].column_name,
-            qualify_columns,
+        let field = &metadata.fields[filter.field.index];
+        Ok((
+            qualify_base_column(dialect, table, &field.column_name, qualify_columns),
+            field.field_type,
         ))
     }
 }
@@ -1018,12 +1022,15 @@ fn build_where_sql(
     let mut parts: Vec<String> = Vec::new();
 
     for filter in &ir.filters {
-        let col =
+        let (col, field_type) =
             resolve_filter_column(dialect, metadata, filter, &ir.joins, table, qualify_columns)?;
         let (clause, param) = filter_clause(
             dialect,
-            metadata,
-            filter.field.index,
+            FilterFieldContext {
+                metadata,
+                index: filter.field.index,
+                field_type,
+            },
             &col,
             &filter.operator,
             bound_params.len() + 1,
@@ -1125,12 +1132,15 @@ fn emit_predicate(
             )?
         )),
         Predicate::Filter { filter } => {
-            let col =
+            let (col, field_type) =
                 resolve_filter_column(dialect, metadata, filter, joins, table, qualify_columns)?;
             let (clause, param) = filter_clause(
                 dialect,
-                metadata,
-                filter.field.index,
+                FilterFieldContext {
+                    metadata,
+                    index: filter.field.index,
+                    field_type,
+                },
                 &col,
                 &filter.operator,
                 bound_params.len() + 1,
@@ -1154,10 +1164,16 @@ fn emit_predicate(
 /// The `match` operator maps to `@@ plainto_tsquery($N)` on `PostgreSQL` and
 /// falls back to `LIKE $N` on other dialects that lack full-text search.
 /// All other operators are mapped by `operator_to_sql`.
+#[derive(Clone, Copy)]
+struct FilterFieldContext<'a> {
+    metadata: &'a ModelMetadata,
+    index: usize,
+    field_type: ferrum_core::ir::metadata::FieldType,
+}
+
 fn filter_clause(
     dialect: Dialect,
-    metadata: &ModelMetadata,
-    field_index: usize,
+    field: FilterFieldContext<'_>,
     col: &str,
     operator: &str,
     param_index: usize,
@@ -1166,8 +1182,29 @@ fn filter_clause(
     match operator {
         "is_null" => (format!("{col} IS NULL"), None),
         "is_not_null" => (format!("{col} IS NOT NULL"), None),
-        op if fts::is_fts_operator(op) => {
-            fts::emit_match(dialect, metadata, field_index, col, op, param_index, value)
+        op if fts::is_fts_operator(op) => fts::emit_match(
+            dialect,
+            field.metadata,
+            field.index,
+            col,
+            op,
+            param_index,
+            value,
+        ),
+        op if dialect == Dialect::Postgres
+            && field.field_type == ferrum_core::ir::metadata::FieldType::Json =>
+        {
+            let placeholder = dialect.placeholder(param_index);
+            let clause = match op {
+                "contains" => format!("{col} @> {placeholder}::jsonb"),
+                "has_key" => format!("{col} ? {placeholder}"),
+                "has_any_keys" => format!("{col} ?| {placeholder}"),
+                _ => {
+                    let sql_op = operator_to_sql(op, dialect);
+                    format!("{col} {sql_op} {placeholder}::jsonb")
+                }
+            };
+            (clause, Some(value))
         }
         op => {
             let placeholder = dialect.placeholder(param_index);

{ferrum_orm-0.1.13 → ferrum_orm-0.1.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "ferrum-orm"
-version = "0.1.13"
+version = "0.1.15"
 description = "Next-generation async ORM for Python with a Rust-powered core"
 license = { text = "Apache-2.0" }
 readme = "README.md"

{ferrum_orm-0.1.13 → ferrum_orm-0.1.15}/python/ferrum/__init__.py

@@ -6,7 +6,7 @@ Import paths are stable API; internal module paths are not.
 
 from __future__ import annotations
 
-__version__ = "0.1.13"
+__version__ = "0.1.15"
 __all__ = [
     "Aggregate",
     "CreateExtension",

{ferrum_orm-0.1.13 → ferrum_orm-0.1.15}/python/ferrum/drivers/postgres.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import contextlib
+import json
 from collections.abc import AsyncGenerator
 from typing import Any
 
@@ -11,6 +12,41 @@ from ferrum.drivers.streaming import AsyncpgChunkStream
 from ferrum.errors import FerrumConfigError, FerrumConnectionError, map_db_error
 
 
+def _encode_json_param(value: Any) -> str:
+    """Encode a Python value for asyncpg ``json`` / ``jsonb`` text codecs.
+
+    Ferrum's bind path already ``json.dumps`` JSON fields to text before the
+    driver (with SQL ``::jsonb`` casts). Accept pre-serialized strings so a
+    codec encoder never double-encodes those binds if a future path sends the
+    parameter as a native json/jsonb OID.
+    """
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, default=str, separators=(",", ":"))
+
+
+def _decode_json_param(value: str) -> Any:
+    """Decode asyncpg ``json`` / ``jsonb`` text into native Python objects."""
+    return json.loads(value)
+
+
+async def _register_json_codecs(conn: Any) -> None:
+    """Make JSONB/JSON columns hydrate as ``dict`` / ``list``, not ``str``.
+
+    asyncpg's default is to return ``json``/``jsonb`` as text. Without this,
+    ``model_construct`` leaves JSON fields as strings and Pydantic consumers
+    that expect ``dict`` fail at the agent/MCP boundary.
+    """
+    for type_name in ("jsonb", "json"):
+        await conn.set_type_codec(
+            type_name,
+            schema="pg_catalog",
+            encoder=_encode_json_param,
+            decoder=_decode_json_param,
+            format="text",
+        )
+
+
 class _BoundConnection:
     """Execution surface pinned to a single raw connection inside a transaction.
 
@@ -139,13 +175,15 @@ class AsyncpgDriver:
         }
         if self._max_lifetime is not None:
             pool_kwargs["max_inactive_connection_lifetime"] = self._max_lifetime
-        if self._statement_timeout_ms is not None:
-            timeout_ms = self._statement_timeout_ms
 
-            async def _init_conn(conn: Any) -> None:
-                await conn.execute(f"SET statement_timeout = {timeout_ms}")
+        statement_timeout_ms = self._statement_timeout_ms
+
+        async def _init_conn(conn: Any) -> None:
+            await _register_json_codecs(conn)
+            if statement_timeout_ms is not None:
+                await conn.execute(f"SET statement_timeout = {statement_timeout_ms}")
 
-            pool_kwargs["init"] = _init_conn
+        pool_kwargs["init"] = _init_conn
         try:
             self._pool = await asyncpg.create_pool(self._dsn, **pool_kwargs)
         except Exception as exc:

{ferrum_orm-0.1.13 → ferrum_orm-0.1.15}/python/ferrum/ext/pgvector.py

@@ -31,7 +31,19 @@ _METRIC_OPS: dict[str, tuple[str, str]] = {
 _VALID_METRICS: frozenset[str] = frozenset(_METRIC_OPS)
 
 
-def _encode_vector(value: list[float]) -> str:
+def _encode_vector(value: list[float] | str) -> str:
+    """Encode a float list as a pgvector text literal.
+
+    Idempotent for an already-encoded ``"[f,f,...]"`` string. Ferrum's
+    ``nearest_to()`` / ``vector_search()`` bind a text literal plus
+    ``$N::vector``; when this codec is registered, asyncpg still runs the
+    encoder on that string — re-iterating characters would produce garbage
+    like ``"[[,-,0,.,1,...]]"`` and Postgres raises
+    ``InvalidTextRepresentationError``.
+    """
+    if isinstance(value, str):
+        # Already a pgvector text literal (or opaque text the server will cast).
+        return value
     return "[" + ",".join(str(v) for v in value) + "]"
 
 

{ferrum_orm-0.1.13 → ferrum_orm-0.1.15}/python/ferrum/models.py

@@ -97,8 +97,8 @@ _SUPPORTED_TYPES[TSVector] = "tsvector"
 # Operator allowlists per Ferrum field type (QUERY_ENGINE.md §4.2)
 # ---------------------------------------------------------------------------
 _ALLOWED_OPERATORS: dict[str, tuple[str, ...]] = {
-    "int": ("eq", "gt", "gte", "lt", "lte", "in", "is_null", "ne", "range"),
-    "big_int": ("eq", "gt", "gte", "lt", "lte", "in", "is_null", "ne", "range"),
+    "int": ("eq", "gt", "gte", "lt", "lte", "in", "is_null", "is_not_null", "ne", "range"),
+    "big_int": ("eq", "gt", "gte", "lt", "lte", "in", "is_null", "is_not_null", "ne", "range"),
     "text": (
         "eq",
         "iexact",
@@ -110,27 +110,35 @@ _ALLOWED_OPERATORS: dict[str, tuple[str, ...]] = {
         "iendswith",
         "in",
         "is_null",
+        "is_not_null",
         "ne",
     ),
-    "bool": ("eq", "is_null", "ne"),
-    "float": ("eq", "gt", "gte", "lt", "lte", "in", "is_null", "ne", "range"),
-    "decimal": ("eq", "gt", "gte", "lt", "lte", "in", "is_null", "ne", "range"),
-    "datetime": ("eq", "gt", "gte", "lt", "lte", "is_null", "ne", "range"),
-    "date": ("eq", "gt", "gte", "lt", "lte", "is_null", "ne", "range"),
-    "time": ("eq", "gt", "gte", "lt", "lte", "is_null", "ne", "range"),
-    "uuid": ("eq", "in", "is_null", "ne"),
-    "bytes": ("eq", "in", "is_null", "ne"),
+    "bool": ("eq", "is_null", "is_not_null", "ne"),
+    "float": ("eq", "gt", "gte", "lt", "lte", "in", "is_null", "is_not_null", "ne", "range"),
+    "decimal": ("eq", "gt", "gte", "lt", "lte", "in", "is_null", "is_not_null", "ne", "range"),
+    "datetime": ("eq", "gt", "gte", "lt", "lte", "is_null", "is_not_null", "ne", "range"),
+    "date": ("eq", "gt", "gte", "lt", "lte", "is_null", "is_not_null", "ne", "range"),
+    "time": ("eq", "gt", "gte", "lt", "lte", "is_null", "is_not_null", "ne", "range"),
+    "uuid": ("eq", "in", "is_null", "is_not_null", "ne"),
+    "bytes": ("eq", "in", "is_null", "is_not_null", "ne"),
     # JSONB: containment + key existence operators (PostgreSQL @>, ?, ?|)
-    "json": ("eq", "is_null", "contains", "has_key", "has_any_keys"),
-    "vector": ("is_null",),
-    "tsvector": ("match", "match_phrase", "match_websearch", "match_boolean", "is_null"),
+    "json": ("eq", "is_null", "is_not_null", "contains", "has_key", "has_any_keys"),
+    "vector": ("is_null", "is_not_null"),
+    "tsvector": (
+        "match",
+        "match_phrase",
+        "match_websearch",
+        "match_boolean",
+        "is_null",
+        "is_not_null",
+    ),
     # PostgreSQL array types — array containment and overlap operators
-    "array_text": ("eq", "is_null", "contains", "contained_by", "overlap"),
-    "array_int": ("eq", "is_null", "contains", "contained_by", "overlap"),
-    "array_uuid": ("eq", "is_null", "contains", "contained_by", "overlap"),
-    "array_float": ("eq", "is_null", "contains", "contained_by", "overlap"),
+    "array_text": ("eq", "is_null", "is_not_null", "contains", "contained_by", "overlap"),
+    "array_int": ("eq", "is_null", "is_not_null", "contains", "contained_by", "overlap"),
+    "array_uuid": ("eq", "is_null", "is_not_null", "contains", "contained_by", "overlap"),
+    "array_float": ("eq", "is_null", "is_not_null", "contains", "contained_by", "overlap"),
     # Enum (TEXT + CHECK constraint) — equality and membership operators
-    "enum": ("eq", "is_null", "ne", "in"),
+    "enum": ("eq", "is_null", "is_not_null", "ne", "in"),
 }
 
 # Allowlist for ON DELETE actions in FK constraints (SQL injection guard).
@@ -907,7 +915,9 @@ def _build_metadata(cls: type[_PydanticBaseModel]) -> ModelMetadata:
                 column_name=column_name,
                 python_type_name=python_type_name,
                 field_type=db_type,
-                allowed_operators=_ALLOWED_OPERATORS.get(db_type, ("eq", "is_null", "ne")),
+                allowed_operators=_ALLOWED_OPERATORS.get(
+                    db_type, ("eq", "is_null", "is_not_null", "ne")
+                ),
                 nullable=nullable,
                 pk=is_pk,
                 max_length=ferrum_extras.get("max_length"),

{ferrum_orm-0.1.13 → ferrum_orm-0.1.15}/python/ferrum/queryset.py

@@ -43,7 +43,7 @@ from ferrum.expressions import Q, args_to_q
 
 if TYPE_CHECKING:
     from ferrum.connection import Connection, Transaction
-    from ferrum.models import Model, ModelMetadata
+    from ferrum.models import FieldMeta, Model, ModelMetadata
 
     # Terminals accept an open Connection or an active Transaction interchangeably:
     # both expose the ``dialect`` / ``_require_driver()`` surface the terminals use.
@@ -225,6 +225,17 @@ def _encode_field_bind_value(field: Any, value: object) -> dict[str, object]:  #
     return _encode_bind_value(_prepare_field_value(field, value))
 
 
+def _encode_filter_bind_value(
+    field: FieldMeta,
+    operator: str,
+    value: object,
+) -> dict[str, object]:
+    """Encode a lookup value according to its field and operator."""
+    if field.field_type == "json" and operator not in {"has_key", "has_any_keys"}:
+        return _encode_field_bind_value(field, value)
+    return _encode_bind_value(value)
+
+
 def _decode_bound_param(param: str | dict[str, Any]) -> object:
     """Decode one compiled BindValue to a Python value for the driver.
 
@@ -337,6 +348,24 @@ def _parse_lookup(lookup: str) -> tuple[str, str]:
     return lookup, "eq"
 
 
+def _normalize_null_lookup(operator: str, value: object) -> tuple[str, object]:
+    """Map Django-style ``__is_null=True/False`` onto ``is_null`` / ``is_not_null``.
+
+    The SQL emitter treats ``is_null`` / ``is_not_null`` as nullary operators and
+    ignores the bound value. Without this rewrite, ``field__is_null=False`` would
+    still emit ``IS NULL``.
+    """
+    if operator == "is_null":
+        if value is False:
+            return "is_not_null", None
+        return "is_null", None
+    if operator == "is_not_null":
+        if value is False:
+            return "is_null", None
+        return "is_not_null", None
+    return operator, value
+
+
 def _fk_oto_relations(metadata: ModelMetadata) -> dict[str, Any]:
     """Return ``{relation_name: RelationMeta}`` for forward FK / OneToOne only."""
     return {r.field_name: r for r in metadata.relations if r.kind in ("fk", "one_to_one")}
@@ -444,12 +473,16 @@ def _filter_dict_to_ir(
 ) -> dict[str, Any]:
     """Convert one normalized filter dict to a compiler-ready IR leaf."""
     field_name: str = flt["field"]
-    operator: str = flt["operator"]
+    operator, value = _normalize_null_lookup(flt["operator"], flt["value"])
     _validate_lookup(field_name, operator, metadata, field_index=field_index)
     return {
         "field": {"index": field_index[field_name], "name": field_name},
         "operator": operator,
-        "value": _encode_bind_value(flt["value"]),
+        "value": _encode_filter_bind_value(
+            metadata.fields[field_index[field_name]],
+            operator,
+            value,
+        ),
     }
 
 
@@ -466,13 +499,20 @@ def _kwargs_to_ir_filters(
     leaves: list[dict[str, Any]] = []
     filter_joins: dict[str, set[str]] = {}
     for lookup, value in kwargs.items():
-        field_name, operator, join_alias, target_index, _target_meta = _resolve_lookup(
+        field_name, operator, join_alias, target_index, target_meta = _resolve_lookup(
             lookup, metadata, field_index
         )
+        # Validate against the caller's operator (``is_null``), then rewrite
+        # ``is_null=False`` → ``is_not_null`` for the SQL emitter.
+        operator, value = _normalize_null_lookup(operator, value)
         filt: dict[str, Any] = {
             "field": {"index": target_index[field_name], "name": field_name},
             "operator": operator,
-            "value": _encode_bind_value(value),
+            "value": _encode_filter_bind_value(
+                target_meta.fields[target_index[field_name]],
+                operator,
+                value,
+            ),
         }
         if join_alias is not None:
             filt["join_alias"] = join_alias

{ferrum_orm-0.1.13 → ferrum_orm-0.1.15}/python/ferrum/relations.py

@@ -191,6 +191,7 @@ def build_join_ir(
             "name": f.name,
             "column": f.column_name,
             "allowed_operators": list(f.allowed_operators),
+            "field_type": f.field_type,
         }
         for i, f in enumerate(remote_meta.fields)
         if remote_field_names is None or f.name in remote_field_names