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

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

@@ -1,6 +1,15 @@
 # CHANGELOG
 
 
+## v0.8.0 (2026-05-09)
+
+### Features
+
+- **query**: Typed query predicates via col() and lambda
+  ([#48](https://github.com/syn54x/ferro-orm/pull/48),
+  [`e34e3ca`](https://github.com/syn54x/ferro-orm/commit/e34e3ca43adfc851d757d8232d5736fb453db55e))
+
+
 ## v0.7.0 (2026-05-08)
 
 ### Features

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

@@ -294,7 +294,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "dashmap",
  "once_cell",

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.7.0
+Version: 0.8.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.8.0/docs/api/query.md

@@ -0,0 +1,97 @@
+# Query API
+
+Complete reference for the Query Builder API.
+
+## `Query`
+
+`Query.where` accepts either a `QueryNode` (the operator and `col()` paths) or a lambda predicate of shape `Callable[[QueryProxy[TModel]], QueryNode]`. See [Typed Query Predicates](../concepts/query-typing.md) for a full treatment of the three predicate styles.
+
+::: ferro.query.Query
+    options:
+      members:
+        - where
+        - order_by
+        - limit
+        - offset
+        - all
+        - first
+        - count
+        - exists
+        - update
+        - delete
+      show_source: false
+      heading_level: 3
+
+## `Relation`
+
+`Relation` is the lazy collection-relationship subclass of `Query` returned by `BackRef` and `ManyToMany` fields. It accepts the same three predicate styles on `where`.
+
+::: ferro.query.Relation
+    options:
+      members:
+        - where
+        - order_by
+        - limit
+        - offset
+        - all
+        - first
+        - add
+        - remove
+        - clear
+      show_source: false
+      heading_level: 3
+
+## `col`
+
+Runtime-identity wrapper that statically narrows a model class attribute back to `FieldProxy[T]`. Use it when a single attribute on an existing chain trips your type checker; for new code prefer the lambda predicate style.
+
+::: ferro.query.col
+    options:
+      show_source: false
+      heading_level: 3
+
+## `FieldProxy`
+
+The typed proxy installed by Ferro's metaclass on every model class field. Generic over the column's Python type; operator overloads accept `T | FieldProxy[T]` and return `QueryNode`.
+
+::: ferro.query.FieldProxy
+    options:
+      members:
+        - in_
+        - like
+      show_source: false
+      heading_level: 3
+
+## `QueryProxy`
+
+The attribute proxy passed to lambda predicates. Each attribute access returns a fresh `FieldProxy` for the accessed name.
+
+::: ferro.query.QueryProxy
+    options:
+      show_source: false
+      heading_level: 3
+
+## `QueryNode`
+
+The serializable AST node produced by every predicate style. You normally do not construct these directly.
+
+::: ferro.query.QueryNode
+    options:
+      members:
+        - to_dict
+      show_source: false
+      heading_level: 3
+
+## `Predicate`
+
+Type alias for lambda predicates accepted by `Query.where`, `Relation.where`, and `Model.where`.
+
+```python
+Predicate[TModel] = Callable[[QueryProxy[TModel]], QueryNode]
+```
+
+## See Also
+
+- [Queries Guide](../guide/queries.md)
+- [Typed Query Predicates](../concepts/query-typing.md)
+- [How-To: Pagination](../howto/pagination.md)

ferro_orm-0.8.0/docs/brainstorms/2026-05-08-typed-query-predicates-requirements.md

@@ -0,0 +1,95 @@
+---
+date: 2026-05-08
+topic: typed-query-predicates
+---
+
+# Typed Query Predicates
+
+## Summary
+
+Add two opt-in query-predicate styles to Ferro — a `col()` wrapper and a lambda predicate API — so that `Model.field` comparisons type-check cleanly under Pyright and `ty` without changing user model annotations or breaking the current operator API. A concept doc covers when to reach for each.
+
+---
+
+## Problem Frame
+
+Ferro models are Pydantic models, so user fields carry plain-type annotations like `archived: bool` and `transcript_id: int`. At runtime the metaclass replaces each class attribute with a `FieldProxy` whose operator overloads return `QueryNode`, so `User.archived == False` builds a query predicate that `Query.where()` accepts.
+
+Static type checkers don't see that runtime swap. Pyright and `ty` resolve `User.archived` from the source annotation as `bool`, so `User.archived == False` is interpreted as `bool.__eq__(bool)` and returns `bool`. `Query.where()` then complains that it expected a `QueryNode`. Users hitting this on every typed predicate currently silence each line with a `# type: ignore` pragma.
+
+Other Python ORMs work around this by changing what users annotate (SQLAlchemy 2.x uses `Mapped[T]`), changing the API away from class-attribute predicates (Django and Tortoise use kwargs), or shipping a mypy plugin. None of those fit Ferro: `Mapped[T]`-style breaks the "user types directly" stance and adds Pydantic interop work, and a mypy plugin doesn't help Pyright or `ty` users — Pyright has no public plugin API.
+
+---
+
+## Requirements
+
+**`col()` wrapper**
+
+- R1. Ferro exposes a `col()` function whose static signature is `(value: T) -> FieldProxy[T]`. At runtime it is identity, with a guard that raises `TypeError` if the input is not a `FieldProxy`.
+- R2. `col(Model.field) == value` (and the other comparison operators) produces a `QueryNode` that `Query.where()` accepts in mypy, Pyright, basedpyright, and `ty` without ignore pragmas.
+- R3. `FieldProxy` becomes generic over its column type (`FieldProxy[T]`), with operator overloads typed to accept `T | FieldProxy[T]` and return `QueryNode`. Runtime behavior is unchanged; users do not write the generic parameter directly.
+
+**Lambda predicate API**
+
+- R4. `Query.where()` accepts a callable that takes a typed query proxy and returns a `QueryNode`. The proxy's static type is parameterized on the model type; attribute access on the proxy is statically typed as `FieldProxy[Any]`.
+- R5. At runtime, when `where()` receives a callable that is not a `QueryNode`, it constructs a per-call proxy whose `__getattr__` returns `FieldProxy(name)`, invokes the callable with the proxy, and appends the returned node to the query.
+- R6. Lambda predicates support compound expressions via the existing `&` and `|` operators on `QueryNode`.
+
+**Backward compatibility**
+
+- R7. The existing `Model.field == value` operator path continues to work unchanged at runtime. No existing test, query, or user model needs modification.
+- R8. Adding the lambda overload does not change the runtime semantics of any current `where()` call. Dispatch checks `isinstance(QueryNode)` first, then `callable()`.
+- R9. No changes to the model metaclass, Pydantic schema generation, JSON schema bridge, or the Rust hydration paths.
+
+**Documentation**
+
+- R10. A concept document under `docs/concepts/` covers the three predicate styles (operator, `col()`, lambda), shows them combined in one query chain, and recommends when to reach for each. Lambda is positioned as the recommended idiom for new code; `col()` is the lower-ceremony fallback for users who want to keep the operator shape.
+
+---
+
+## Acceptance Examples
+
+- AE1. **Covers R1, R2.** Given `archived: bool` declared on a model and a strict type checker run, when the user writes `.where(col(T.archived) == False)`, the line type-checks without ignore pragmas in mypy, Pyright, basedpyright, and `ty`.
+- AE2. **Covers R7, R8.** Given an existing test that uses `.where(T.field == value)`, when the new code lands, the test continues to pass with no modification.
+- AE3. **Covers R4, R5, R6.** Given the predicate `lambda t: (t.archived == False) & (t.org_id == 42)`, when passed to `.where(...)`, the runtime invokes the lambda with a model proxy, appends a single compound `QueryNode` to the query, and produces the same SQL as the equivalent operator-form predicate.
+- AE4. **Covers R1.** Given a value that is not a `FieldProxy` (e.g., a raw string), when passed to `col()` at runtime, `col()` raises `TypeError` whose message names the actual argument type.
+- AE5. **Covers R2, R7, R4.** Given a single `Query` chain that combines `.where(T.a == 1)`, `.where(col(T.b) == 2)`, and `.where(lambda t: t.c == 3)` in any order, when executed, the resulting SQL contains all three predicates and the result hydrates correctly.
+
+---
+
+## Success Criteria
+
+- Ferro users hitting the original `ty` complaint can fix it by wrapping the attribute reference with `col(...)` — a single small change per call site, with no model edits and no plugin installation.
+- New Ferro code in user projects can adopt the lambda predicate style and have those predicates type-check cleanly in every supported checker.
+- Downstream agents (planning, future API work) and human reviewers have a clear definition of which `where()` shapes are supported and which were deliberately deferred.
+- Backward-compat tests in `tests/` pass without modification, demonstrating the operator-path runtime is unchanged.
+
+---
+
+## Scope Boundaries
+
+- `Mapped[T]` / descriptor-based field annotations are deferred indefinitely; they conflict with Ferro's "user types directly" stance and would require Pydantic interop work disproportionate to the typing win.
+- A mypy plugin for Ferro is out of scope; Pyright and `ty` are the target checkers and neither has an equivalent plugin API.
+- Per-field type precision in the lambda proxy via `@dataclass_transform` is deferred; this work uses `FieldProxy[Any]` for proxy attribute types.
+- A kwargs-style filter API (e.g., `.where_kw(field=value)`) is deferred until user demand surfaces.
+- A `t""` template-string predicate API is deferred until Ferro raises its minimum Python to 3.14.
+- Per-model code generation, distributed `.pyi` stubs for user models, and `if TYPE_CHECKING` shadow declarations as a documented pattern are not adopted.
+- No changes to the metaclass, Pydantic interop, JSON schema generation, or the Rust FFI bridge.
+
+---
+
+## Key Decisions
+
+- **Single PR over staged PRs.** The three pieces (`col()`, lambda API, doc) ship together on `feat/col-and-lambda-queries`. They are small, low-risk, and meaningfully more useful as a unit than incrementally.
+- **`col()` is identity at runtime, not a constructor.** `Model.field` is already a `FieldProxy` thanks to the metaclass, so `col()` is a typed pass-through, not a wrapping layer. This keeps the runtime cost zero and avoids a parallel class hierarchy.
+- **Lambda predicate proxy is per-call, not stored on the model.** Avoids touching the metaclass and keeps the lambda path opt-in. Users who never call `where(lambda ...)` never construct the proxy.
+- **`FieldProxy[Any]` over per-field precision for the lambda proxy.** Per-field types would require `@dataclass_transform` plumbing and tighter user-facing typing semantics. Deferred to a follow-up if real demand materializes.
+- **Lambda is the recommended idiom; `col()` is the fallback.** Lambda has lower per-call ceremony for chains with several predicates; `col()` is one wrapper per reference but doesn't ask users to rewrite their query shape.
+
+---
+
+## Dependencies / Assumptions
+
+- The current metaclass behavior of replacing each `model_fields` attribute with a `FieldProxy` is a stable invariant the runtime no-op `col()` relies on.
+- `QueryNode` does not currently expose `__call__`; the runtime dispatch rule "isinstance(QueryNode) first, then callable()" depends on this remaining true.
+- Generic parameters on `FieldProxy[T]` are runtime-erased (standard Python typing semantics); existing `isinstance(x, FieldProxy)` checks remain valid.

{ferro_orm-0.7.0 → ferro_orm-0.8.0}/docs/changelog.md

@@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- Typed query predicates: `col()` wrapper and lambda predicate API on `Query.where`, `Relation.where`, and `Model.where` for static-typing-clean predicates without model annotation changes ([#48](https://github.com/syn54x/ferro-orm/pull/48)). See [Typed Query Predicates](concepts/query-typing.md).
+- `FieldProxy` is now generic (`FieldProxy[T]`); operator overloads are typed `T | FieldProxy[T] -> QueryNode`, `.like()` is gated to `FieldProxy[str]`.
+- New public symbols re-exported from `ferro.query`: `col`, `QueryProxy`, `Predicate`.
 - Comprehensive documentation restructure
 - Tutorial for new users
 - How-to guides for common patterns

ferro_orm-0.8.0/docs/concepts/query-typing.md

@@ -0,0 +1,105 @@
+# Typed Query Predicates
+
+Ferro's query DSL accepts three predicate styles on `Model.where`, `Query.where`, and `Relation.where`. They are interchangeable, run on the same code path, and can be mixed freely in the same chain. Pick the one that reads best for the call site you're writing.
+
+## Why this exists
+
+Ferro's metaclass replaces every model field with a `FieldProxy` at class-creation time, so `User.archived` is a `FieldProxy` at runtime — and `User.archived == False` builds a `QueryNode`, not a Python `bool`. Static type checkers (Pyright, `ty`, mypy, basedpyright) only see your Pydantic annotations, though, so they read `User.archived` as a `bool` and reject the same expression they would happily run.
+
+The two new predicate styles below give you the runtime ergonomics back without forcing a model-annotation rewrite, a type-checker plugin, or any change to the existing operator path.
+
+## The three styles
+
+### 1. Operator (the original)
+
+```python
+rows = await User.where(User.id == 1).all()
+rows = await User.where(User.email.like("%@example.com")).all()
+```
+
+Works at runtime, always has, always will. Type checkers may flag boolean-column comparisons (`User.archived == False` resolves statically to `bool`) — when that bites, reach for one of the styles below.
+
+### 2. `col()` wrapper
+
+```python
+from ferro.query import col
+
+rows = await User.where(col(User.archived) == False).all()
+```
+
+`col()` is a runtime-identity helper that statically narrows its argument back to `FieldProxy[T]`. It does no work at runtime beyond an `isinstance` guard (and raises `TypeError` if you accidentally hand it a literal). Reach for it when a single attribute trips your type checker and you don't want to restructure the call site.
+
+### 3. Lambda predicate
+
+```python
+rows = await User.where(lambda t: t.archived == False).all()
+rows = await User.where(
+    lambda t: (t.role == "admin") & (t.active == True)
+).all()
+```
+
+The lambda receives a `QueryProxy` whose attribute access yields a fresh `FieldProxy` for each name — so `t.archived == False` is a `QueryNode` from the type checker's point of view as well as at runtime. This is the recommended style for new code: it keeps the call site free of `# type: ignore` even when comparing booleans, integers, or any other value type.
+
+The proxy attribute type is currently `FieldProxy[Any]`, which is a deliberate scope decision (see [Scope boundaries](#scope-boundaries) below). Pyright still resolves the predicate's *return* type as `QueryNode` correctly.
+
+## When to use which
+
+| Style | Use when |
+|------|----------|
+| Operator | Existing code that already type-checks; quick filters where the value type isn't `bool`. |
+| `col()` | One attribute on an existing chain trips your type checker and you want minimal diff. |
+| Lambda | New code, especially boolean comparisons or compound predicates; preferred idiom. |
+
+All three are equally efficient at runtime — every one of them produces a `QueryNode` and appends it to `where_clause`.
+
+## Combining styles
+
+You can mix all three on a single chain. They compose because they all funnel through the same dispatch in `Query.where`:
+
+```python
+rows = await (
+    User.where(User.id == 1)                    # operator
+    .where(col(User.archived) == False)         # col()
+    .where(lambda t: t.role == "admin")         # lambda
+    .all()
+)
+```
+
+`Relation.where` (used on `BackRef` collections) accepts the same three shapes:
+
+```python
+published = await author.posts.where(lambda t: t.published == True).all()
+```
+
+## What this does not change
+
+- Your model annotations. `archived: bool = False` stays exactly as it is.
+- The metaclass's `FieldProxy` injection. Class attribute access is unchanged.
+- Pydantic schema generation, JSON schema output, or model validation.
+- The Rust FFI bridge or how `QueryNode`s are serialized for the engine.
+- The operator-path runtime. Existing `Model.field == value` calls take the same code path they always have.
+
+## Scope boundaries
+
+The current implementation deliberately stops short of:
+
+- **Per-field types on the lambda proxy.** `t.archived` resolves to `FieldProxy[Any]`, not `FieldProxy[bool]`. Wiring per-field types through the proxy needs `@dataclass_transform` plumbing on the metaclass; that's a future PR.
+- **A type-checker plugin.** Ferro stays plugin-free.
+- **A kwargs-style or template-string predicate API.** Both have been considered; neither shipped here.
+
+If `t.archived` resolving as `FieldProxy[Any]` ever bites you statically, drop back to `col(Model.archived) == ...` for that one comparison — that's exactly the role `col()` plays.
+
+## Reference
+
+- `ferro.query.col` — runtime-identity wrapper, raises `TypeError` for non-`FieldProxy` input.
+- `ferro.query.QueryProxy` — attribute proxy passed to lambda predicates.
+- `ferro.query.Predicate` — `Callable[[QueryProxy[TModel]], QueryNode]`, the type of any lambda predicate.
+- `ferro.query.FieldProxy` — generic over the column's Python type (`FieldProxy[T]`).
+
+See the [Query API reference](../api/query.md) for full signatures.
+
+## See Also
+
+- [Queries Guide](../guide/queries.md)
+- [Type Safety](type-safety.md)
+- [Query API](../api/query.md)

{ferro_orm-0.7.0 → ferro_orm-0.8.0}/docs/concepts/type-safety.md

@@ -85,6 +85,27 @@ User.where(
 )
 ```
 
+## Query Predicates and the Type Checker
+
+Static checkers see your Pydantic annotations, not the `FieldProxy` instances Ferro's metaclass installs at class-creation time. That means `User.archived == False` is statically a `bool` even though it is a `QueryNode` at runtime, and Pyright or `ty` will flag it where `Query.where` expects a `QueryNode`.
+
+Ferro ships three predicate styles to address this without any model-annotation changes or type-checker plugins:
+
+```python
+from ferro.query import col
+
+# Operator (unchanged)
+await User.where(User.id == 1).all()
+
+# col() — runtime identity, statically narrows back to FieldProxy[T]
+await User.where(col(User.archived) == False).all()
+
+# Lambda — receives a QueryProxy whose attributes return FieldProxy
+await User.where(lambda t: t.archived == False).all()
+```
+
+See [Typed Query Predicates](query-typing.md) for the full discussion, including when to reach for each style and how they compose.
+
 ## Field Type Validation
 
 Ferro validates field types match database types:

{ferro_orm-0.7.0 → ferro_orm-0.8.0}/docs/guide/queries.md

@@ -31,6 +31,32 @@ alice_users = await User.where(User.name.like("Alice%")).all()
 | `.like()` | `LIKE` | `User.email.like("%@example.com")` |
 | `.in_()` | `IN` | `User.status.in_(["active", "pending"])` |
 
+## Predicate Styles
+
+`where()` accepts three interchangeable predicate styles. They share one runtime path and one dispatcher, and you can mix them on a single chain.
+
+```python
+from ferro.query import col
+
+# 1. Operator (the original)
+await User.where(User.id == 1).all()
+
+# 2. col() wrapper — runtime identity, statically narrows to FieldProxy[T]
+await User.where(col(User.archived) == False).all()
+
+# 3. Lambda predicate — receives a QueryProxy with FieldProxy attributes
+await User.where(lambda t: t.archived == False).all()
+```
+
+The operator style works at runtime for every column type, but static type checkers (Pyright, `ty`) flag boolean and other value-type comparisons because they see your Pydantic annotations rather than the runtime `FieldProxy`. Reach for `col()` when one attribute trips the checker, or write new code with the lambda style to sidestep the issue entirely.
+
+!!! tip "When to use which"
+    - **Operator** — existing code that already type-checks; quick filters where the column type isn't `bool`.
+    - **`col()`** — one attribute on an existing chain trips your type checker and you want minimal diff.
+    - **Lambda** — new code, especially boolean comparisons or compound predicates. Recommended idiom going forward.
+
+See [Typed Query Predicates](../concepts/query-typing.md) for the full treatment, including combined-style chains and the deliberate scope boundaries.
+
 ## Logical Operators
 
 Combine conditions with `&` (AND) and `|` (OR). **Always use parentheses** around each condition:
@@ -51,6 +77,14 @@ query = User.where(
 inactive_users = await User.where(User.is_active != True).all()
 ```
 
+The same compound expressions work inside lambda predicates — useful when you want the whole expression to type-check without `col()`:
+
+```python
+admins = await User.where(
+    lambda t: (t.role == "admin") & (t.active == True)
+).all()
+```
+
 ## Chaining
 
 Methods can be chained to build complex queries incrementally:
@@ -201,8 +235,9 @@ author = await User.where(User.username == "alice").first()
 # Get all posts by author
 author_posts = await author.posts.all()
 
-# Filter reverse relation
+# Filter reverse relation (any of the three predicate styles works)
 published_posts = await author.posts.where(Post.published == True).all()
+published_posts = await author.posts.where(lambda t: t.published == True).all()
 
 # Count reverse relation
 post_count = await author.posts.count()