fastapi-rtk 2.19.1__tar.gz → 2.20.1__tar.gz

{fastapi_rtk-2.19.1 → fastapi_rtk-2.20.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-rtk
-Version: 2.19.1
+Version: 2.20.1
 Summary: A package that provides a set of tools to build a FastAPI application with a Class-Based CRUD API.
 Project-URL: Homepage, https://codeberg.org/datatactics/fastapi-rtk
 Project-URL: Issues, https://codeberg.org/datatactics/fastapi-rtk/issues
@@ -119,7 +119,7 @@ project/
 1. Install FastAPI React Toolkit:
 
    ```bash
-   pip install fastapi-rtk
+   pip install fastapi-rtk aiosqlite  # aiosqlite: async driver for the sqlite URI below (asyncpg for Postgres)
    mkdir -p app
    touch run.py app/__init__.py app/app.py app/config.py app/models.py app/apis.py
    ```
@@ -231,6 +231,7 @@ project/
    - `GET /api/v1/items/_image/{filename}` - Serve image files (If image column is present)
    - `GET /api/v1/items/_file/{filename}` - Serve file downloads (If file column is present)
    - `GET /api/v1/items/_info` - Get metadata about the model, including which columns can be added, edited, filtered, etc.
+   - `GET /api/v1/items/_lookup/{column}` - Search a column's values, or resolve ids to labels, for form and filter inputs (If the column is enabled in `lookup_columns`)
    - `POST /api/v1/items/bulk/{handler}` - Bulk operations, if set on the API class
    - `GET /api/v1/items/download` - Download items as CSV
    - `GET /api/v1/items/` - List items
@@ -249,6 +250,14 @@ project/
 
 2. Project files:
 
+   **webapp/.env**
+
+   The path the app is served under, with a trailing slash; `index.html` reads it as `%VITE_BASE_PATH%`.
+
+   ```bash
+   VITE_BASE_PATH=/
+   ```
+
    **webapp/index.html**
 
    ```html
@@ -295,7 +304,7 @@ project/
 
    createRoot(document.getElementById("root")).render(
      <StrictMode>
-       <MantineProvider>
+       <MantineProvider getStyleNonce={() => window.nonce}>
          <Provider baseUrl={BASE_PATH + "api/v1"}>
            <BrowserRouter basename={BASE_PATH}>
              <App />
@@ -326,8 +335,9 @@ import { createReactNativeAdapters } from "fastapi-rtk/react-native-adapters";
 const rnAdapters = createReactNativeAdapters({
   asyncStorage,
   fileSystem,
-  sharing,
+  sharing, // optional
   webBrowser,
+  oauthRedirectUrl: "myapp://oauth", // required for OAuth sign-in; one URL or a map per provider
 });
 
 <Provider baseUrl="https://api.example.com/api/v1" adapters={rnAdapters}>

{fastapi_rtk-2.19.1 → fastapi_rtk-2.20.1}/README.md

@@ -60,7 +60,7 @@ project/
 1. Install FastAPI React Toolkit:
 
    ```bash
-   pip install fastapi-rtk
+   pip install fastapi-rtk aiosqlite  # aiosqlite: async driver for the sqlite URI below (asyncpg for Postgres)
    mkdir -p app
    touch run.py app/__init__.py app/app.py app/config.py app/models.py app/apis.py
    ```
@@ -172,6 +172,7 @@ project/
    - `GET /api/v1/items/_image/{filename}` - Serve image files (If image column is present)
    - `GET /api/v1/items/_file/{filename}` - Serve file downloads (If file column is present)
    - `GET /api/v1/items/_info` - Get metadata about the model, including which columns can be added, edited, filtered, etc.
+   - `GET /api/v1/items/_lookup/{column}` - Search a column's values, or resolve ids to labels, for form and filter inputs (If the column is enabled in `lookup_columns`)
    - `POST /api/v1/items/bulk/{handler}` - Bulk operations, if set on the API class
    - `GET /api/v1/items/download` - Download items as CSV
    - `GET /api/v1/items/` - List items
@@ -190,6 +191,14 @@ project/
 
 2. Project files:
 
+   **webapp/.env**
+
+   The path the app is served under, with a trailing slash; `index.html` reads it as `%VITE_BASE_PATH%`.
+
+   ```bash
+   VITE_BASE_PATH=/
+   ```
+
    **webapp/index.html**
 
    ```html
@@ -236,7 +245,7 @@ project/
 
    createRoot(document.getElementById("root")).render(
      <StrictMode>
-       <MantineProvider>
+       <MantineProvider getStyleNonce={() => window.nonce}>
          <Provider baseUrl={BASE_PATH + "api/v1"}>
            <BrowserRouter basename={BASE_PATH}>
              <App />
@@ -267,8 +276,9 @@ import { createReactNativeAdapters } from "fastapi-rtk/react-native-adapters";
 const rnAdapters = createReactNativeAdapters({
   asyncStorage,
   fileSystem,
-  sharing,
+  sharing, // optional
   webBrowser,
+  oauthRedirectUrl: "myapp://oauth", // required for OAuth sign-in; one URL or a map per provider
 });
 
 <Provider baseUrl="https://api.example.com/api/v1" adapters={rnAdapters}>

{fastapi_rtk-2.19.1 → fastapi_rtk-2.20.1}/fastapi_rtk/__init__.py

@@ -41,12 +41,15 @@ __all__ = [
     "P_ID",
     "P_IDS",
     "P_Q",
+    "P_LOOKUP_Q",
+    "P_COLUMN",
     "P_SESSION",
     "P_BODY",
     "P_ITEM",
     "P_ITEMS",
     "PARAM_Q",
     "PARAM_IDS_Q_SESSION_ITEMS",
+    "PARAM_LOOKUP_Q_COLUMN_SESSION",
     "PARAM_ID_SESSION",
     "PARAM_ID_SESSION_ITEM",
     "PARAM_BODY_SESSION",
@@ -87,6 +90,8 @@ __all__ = [
     "GenericFilterGreaterEqual",
     "GenericFilterSmallerEqual",
     "GenericFilterIn",
+    "GenericFilterSearch",
+    # TODO: Remove when the deprecated global_filter alias is dropped
     "GenericFilterGlobal",
     "GenericBaseOprFilter",
     "GenericFilterConverter",
@@ -139,6 +144,8 @@ __all__ = [
     "FilterRelationOneToOneOrManyToOneNotEqual",
     "FilterRelationOneToManyOrManyToManyIn",
     "FilterRelationOneToManyOrManyToManyNotIn",
+    "FilterSearch",
+    # TODO: Remove when the deprecated global_filter alias is dropped
     "FilterGlobal",
     "BaseOprFilter",
     "SQLAFilterConverter",
@@ -248,6 +255,7 @@ __all__ = [
     "ColumnRelationInfo",
     "SearchFilter",
     "InfoResponse",
+    "LookupResponse",
     "BaseResponse",
     "BaseResponseSingle",
     "BaseResponseMany",
@@ -255,6 +263,7 @@ __all__ = [
     "FilterSchema",
     "QuerySchema",
     "QueryBody",
+    "LookupQuerySchema",
     # .security
     "Api",
     "Permission",

fastapi_rtk-2.20.1/fastapi_rtk/_version.py

@@ -0,0 +1 @@
+__version__ = "2.20.1"

{fastapi_rtk-2.19.1 → fastapi_rtk-2.20.1}/fastapi_rtk/agent_docs/guide/backend.md

@@ -150,6 +150,7 @@ Registers a full CRUD surface:
 - `PUT /items/{id}`: update
 - `DELETE /items/{id}`: delete
 - `GET /items/_info`: metadata (columns, filters, permissions), which the frontend uses
+- `GET /items/_lookup/{column}?mode=add|edit|search`: paged values of one column (see "Column lookup" in §8)
 - `GET /items/download`: CSV export
 - `POST /items/bulk/{handler}`: bulk operations (see §12)
 - `GET /items/_file/{filename}` / `_image/{filename}`: served when the model has file/image columns
@@ -245,6 +246,8 @@ class ItemApi(ModelRestApi):
     async def post_delete(self, item: Item, params): ...
 ```
 
+The read routes have response hooks that receive the response body before it is returned and edit it in place: `pre_info(info, permissions, session)`, `pre_get_list(body, params)`, `pre_get(body, params)` and `pre_lookup(body, params)` (`params.q` is the `LookupQuerySchema`, plus `params.column` and `params.session`).
+
 To reject a request from a pre-hook, `raise fastapi.HTTPException(...)` (a bare `raise ValueError(...)` becomes HTTP 500; there is no auto-translation). To override the response without rejecting, return a non-`Model` value from the hook, and the dispatcher treats that value as the response and skips the rest of the pipeline (see `services/_add_service.py:66-72` and `services/_edit_service.py:90-96`).
 
 Use hooks for normalization, cross-field validation, audit logging, cache invalidation: anything policy, not wire format (use Pydantic for that at the schema level).
@@ -292,6 +295,39 @@ More per-Api knobs:
 - `order_columns` / `search_columns`: restrict which columns are sortable / searchable.
 - `add_jsonforms_schema` / `edit_jsonforms_schema`, `..._uischema`, `..._translations`, `..._use_enum`, `..._jsonforms_list_as_object`: override the JsonForms schema/uischema/translations that `/_info` ships to the frontend add/edit dialogs (frontend reference §9 is the consumer).
 
+### Column lookup
+
+`/_info` ships only the first `max_page_size` options of a relation; `GET /items/_lookup/{column}` searches and pages the values of one column instead. Query params, bound as one `LookupQuerySchema` (per-Api `lookup_query_schema`): `mode` (required: `add`, `edit` or `search`; any other value is 422), `search` (text the values must contain, matched by `FilterSearch` like the list route's `search` param), `page` (zero-based, default 0), `page_size` (default and cap `max_page_size`), `ids` (a JSON list of primary keys to resolve, default `[]`). The response is `LookupResponse`, `{"count": int, "values": [...]}`: `{"id", "value"}` entries for a relation (`value` is `str(item)`), distinct non-null scalars in ascending order for a plain column. The route is dropped from `routes` when no column is lookup-enabled in any mode.
+
+- Query validation (400, before access): `ids` that is not JSON (`json_invalid`) or not a list (`list_type`), a negative `page` (`greater_than_equal`), a `page_size` below 1 (`greater_than`).
+- Gating order: 401 (route protected, no user), 404 `COLUMN_NOT_FOUND` (column not lookup-enabled in that mode), 403 (user lacks `can_post` for `add`, `can_put` for `edit`, `can_get` for `search`). There is no `can_lookup` permission; `"lookup"` in `exclude_protected_routes` skips the 401 and 403 checks.
+- After access, without a custom `query`: `ids` on a plain column is 400 `invalid_key` (ids are for relations), and an id that does not parse as the related primary key is 400 `value_error` at `ids[<index>]`.
+- `pre_lookup(self, body: LookupResponse, params)` runs on every response before it is returned (custom `query` included); `params` is `PARAM_LOOKUP_Q_COLUMN_SESSION` with `q` (the `LookupQuerySchema`), `column` and `session`. Edit `body` in place.
+- Lookup is opt-in: a column is lookup-enabled only when its `lookup_columns` entry has `"enabled": True` (a bare `True` / `False` entry is short for `{"enabled": True}` / `{"enabled": False}`), so an Api without `lookup_columns` has no `lookup` route. An enabled relation is looked up in each mode whose `add_columns` / `edit_columns` / `search_columns` holds it, and needs something to search: the entry's `columns` or `query`, or a related model `__repr_columns__` that names at least one column, relation or dotted path (`search` matches those entries; a `@property` entry is skipped). An enabled plain column is looked up only in `search` mode, from `search_columns`. A dotted column and a composite-pk relation are never lookup-enabled.
+- A relation lookup applies that mode's `*_query_rel_fields` and orders by `order_rel_fields[column]`, else ascending on the first search column that is a plain column of the related model; a plain-column lookup applies `base_filters` and `base_opr_filters`.
+- `ids` lookups apply that mode's `*_query_rel_fields` too and take any number of ids in one request: a saved value those filters now exclude comes back without its row, so it gets no label.
+
+```python
+class ItemApi(ModelRestApi):
+    datamodel = SQLAInterface(Item)
+    lookup_columns = {
+        "city": True,                                              # plain column, search mode; short for {"enabled": True}
+        "supplier": {"enabled": True},                             # searches the related __repr_columns__
+        "category": {"enabled": True, "columns": ["name", "code"]},  # columns search matches
+        "owner": {"enabled": True, "query": my_query},             # (api, column, q, session) -> {"count": int, "values": list}
+    }
+
+    async def pre_lookup(self, body, params):                      # every lookup response
+        if params.column == "city":
+            body.values = [v.title() for v in body.values]
+```
+
+A `query` callable (sync or async) receives `q`, the request's `LookupQuerySchema`: `q.mode` (`"add"`, `"edit"` or `"search"`), `q.search` (search text or `None`), `q.page` (zero-based), `q.page_size` (already capped at `max_page_size`) and `q.ids` (a list of primary key strings, empty when not resolving). When `q.ids` is not empty, a relation's `query` must return exactly the rows with those primary keys.
+
+An invalid entry raises `ValueError` at setup: a dotted key, a key that is not a column or relation, a `columns` name that matches nothing on the related model, an enabled relation with nothing to search, a relation in none of `add_columns` / `edit_columns` / `search_columns`, a plain column outside `search_columns` or of a JSON / binary / file / image / list kind.
+
+`/_info` tells the frontend which columns to look up. A relation in `add_schema` gets `properties[col]["x-lookup"] = {"mode": "add"}` (`edit_schema` likewise with `{"mode": "edit"}`) when it is lookup-enabled for that mode, the requester may call the route in that mode (the 401 / 403 rules above), and the first page holds fewer values than exist. On a to-many relation the marker sits on the array property, not on `items`. The first-page `oneOf` / `enum` stays beside the marker, so an older frontend keeps working. Every search column carries `filters[col]["lookup"]`, a bool following the same rules for `search` mode; a lookup-enabled plain column needs no count check. An anonymous caller of a public `_info` on a protected `lookup` route gets no marker and `false` everywhere. A custom `add_jsonforms_schema` / `edit_jsonforms_schema` is served without the marker.
+
 ## 9. Filters and custom filters
 
 Available filter classes (import from `fastapi_rtk`, whose top level re-exports `backends.sqla.filters`; the legacy `fastapi_rtk.filters` module still works but emits a deprecation warning):
@@ -300,12 +336,12 @@ Available filter classes (import from `fastapi_rtk`, whose top level re-exports
 FilterEqual, FilterNotEqual, FilterGreater, FilterSmaller, FilterGreaterEqual, FilterSmallerEqual,
 FilterStartsWith, FilterNotStartsWith, FilterEndsWith, FilterNotEndsWith,
 FilterContains, FilterNotContains, FilterTextContains,
-FilterIn, FilterBetween, FilterGlobal,
+FilterIn, FilterBetween, FilterSearch,
 FilterRelationOneToOneOrManyToOneEqual, FilterRelationOneToOneOrManyToOneNotEqual,
 FilterRelationOneToManyOrManyToManyIn, FilterRelationOneToManyOrManyToManyNotIn,
 ```
 
-(`FilterGlobal`, arg `global`, backs the frontend's global search box.)
+(`FilterSearch` is not a column operator: it applies the list route's `search` query param across the shown columns, and an interface swaps it through `search_filter_class`. The old names `global_filter` (query param and `DBQueryParams` key), `FilterGlobal`, `global_filter_class` and `apply_global_filter` still work but emit a `DeprecationWarning`.)
 
 Apply as always-on filters on the Api class:
 

{fastapi_rtk-2.19.1 → fastapi_rtk-2.20.1}/fastapi_rtk/agent_docs/guide/frontend.md

@@ -10,7 +10,7 @@ The toolkit expects Mantine as the UI kit. Use `Stack`, `Group`, `Grid`, `Simple
 pnpm add fastapi-rtk @mantine/core @mantine/dates @mantine/form @mantine/hooks dayjs react-router
 ```
 
-Peer deps: the four `@mantine/*` packages (`^9.0.0`), `react` / `react-dom` (`^19.2.3`), `dayjs` (`^1.11.0`) and `react-router` (`^7.5.3 || ^8.0.0`). Everything else (mantine-react-table, TanStack Query, zustand, i18next, JsonForms) is bundled inside `fastapi-rtk`. Mantine >= 9.4.1 requires fastapi-rtk >= 2.8.0; older releases loop forever in the grid's `useColumns` ("Maximum update depth exceeded").
+Peer deps: the four `@mantine/*` packages (`^9.0.0`), `react` / `react-dom` (`^19.2.3`), `dayjs` (`^1.11.0`) and `react-router` (`^7.5.3 || ^8.0.0`), plus the optional `@jsonforms/core` / `@jsonforms/react` (`^3.6.0`), needed only when importing from `fastapi-rtk/jsonforms` (every other subpath, its types included, works without them). `fastapi-rtk` has no other dependencies: TanStack Query, zustand, i18next, react-i18next, yup, lodash, clsx, dompurify, mantine-form-yup-resolver, mantine-react-table (patched) and the JsonForms copy behind the built-in forms are bundled inside it. An app's own install of any of these is a separate copy that never sees the toolkit's: `Provider` always creates its own `QueryClient`, and only `rq` / `i18nr` / `useTranslation` imported from `fastapi-rtk` reach the Provider's client and i18next instance. Mantine >= 9.4.1 requires fastapi-rtk >= 2.8.0; older releases loop forever in the grid's `useColumns` ("Maximum update depth exceeded").
 
 **Provider order is load-bearing.** Mantine must wrap the fastapi-rtk `Provider`, and the stylesheet order matters: Mantine CSS first, fastapi-rtk CSS last (RTK overrides).
 
@@ -59,7 +59,7 @@ Other `Provider` props: `langProps` (i18n extension, §12), `adapters` (§14), `
 Key props:
 
 - `resource_name`: **must match** the backend's `ModelRestApi.resource_name`. If the backend says `items`, this says `items`: not `item`, not `/items`, not `Items`. This is the contract; no magic fixes a mismatch.
-- `initialQueryParams`: seeds pagination, sort, and filters. Use a small, stable object; don't reconstruct inline each render. Full `QueryParams` keys: `page`, `page_size`, `order_column`, `order_direction`, `filters` (list of `{col, opr, value}`), `opr_filters`, `global_filter`, `columns`, `with_count`.
+- `initialQueryParams`: seeds pagination, sort, and filters. Use a small, stable object; don't reconstruct inline each render. Full `QueryParams` keys: `page`, `page_size`, `order_column`, `order_direction`, `filters` (list of `{col, opr, value}`), `opr_filters`, `search`, `columns`, `with_count` (`global_filter` is the deprecated name of `search`).
 - `streaming`: switch the provider to infinite-scroll mode (§11).
 - Behavior knobs: `relation`, `fetchInfo`, `clearInfoOnRefetch`, `clearDataOnRefetch`, `refetchInfoBasedOnLang`, `refetchDataBasedOnLang`, `resetQueryParamsOnPathChange`, plus raw TanStack overrides `infoQueryProps` / `dataQueryProps` / `streamingQueryProps`. `withApiProvider` is the HOC variant.
 
@@ -70,7 +70,8 @@ Filter operators are the backend filter classes' `arg_name` strings (defined in
 - string: `sw` (starts with), `nsw` (not), `ew` (ends with), `new` (not), `ct` (contains), `nct` (not), `tc` (text-contains, case-insensitive)
 - set / range: `in`, `bw` (between)
 - relations: `rel_o_m` / `nrel_o_m` (one-to-many), `rel_m_m` / `nrel_m_m` (many-to-many)
-- global search: `global`
+
+Text search across the shown columns is the `search` query param, not an operator.
 
 ## 3. `useApi`: the CRUD hook
 
@@ -116,6 +117,8 @@ function ItemsPage() {
 
 There is no `execute(...)` on `useApi`; for arbitrary requests see §4.
 
+`lookup(column, { mode, search?, page?, page_size?, ids? })` fetches one page of the backend's `/_lookup/{column}` route and resolves to `{ count, values }`: `{ id, value }` rows for a relation, scalars for a plain column. `mode` is `add`, `edit` or `search`; `ids` resolves saved primary keys to labels instead of searching, all in one request. A server-searched input is a plain Mantine `Select` or `MultiSelect` with the props of `useLookupOptions({ column, lookup, mode, relation?, values, infiniteQueryProps? })` (`fastapi-rtk/hooks`) spread after its own, `lookup` usually being `useApi().lookup`: it calls `lookup` when the dropdown opens and after typing pauses (`DEBOUNCE_LOOKUP_DELAY`, 200 ms), appends the next page each time the dropdown is scrolled to the bottom (until `count` values arrived or a page is empty, then closes a list that took more than one page with a disabled, translated `No more results` option), resolves a selected relation id missing from the loaded values through `ids` when it passes the mode's `*_query_rel_fields` (a plain value is its own label), and returns `data`, `loading` (true from the keystroke until the request finishes), `filter`, `onSearchChange`, `onDropdownOpen`, `onDropdownClose` and `scrollAreaProps`. Without a `lookup` or a `column` it fetches nothing. Every reopening starts again from the first page, each hook instance runs its own requests, and by default nothing is cached and a failed request is not retried; `infiniteQueryProps` (TanStack `useInfiniteQuery` options) is spread over those defaults of the search query. It runs on TanStack Query, so it (and `HeaderSelectInput` / `HeaderMultiSelectInput`, which always call it) needs a `QueryClientProvider` ancestor, which `Provider` supplies.
+
 Use `setQueryParams` rather than constructing URLs manually; it keeps the filter shape aligned with the backend's `/_info` contract.
 
 Also on the hook: `upload(file, options?)` (CSV import against the resource; `delimiter` / `quotechar` options), `getFileURL` / `getImageURL` (build URLs for file/image columns), `refetchInfo({force?})`, `path`, `queryParams`, and the raw TanStack queries `infoQuery` / `dataQuery` / `streamingQuery` as escape hatches.
@@ -144,7 +147,7 @@ await addEntry({ name: "x" }); // POST /{resource}
 await updateEntry(id, { name: "y" }); // PUT  /{resource}/{id}
 ```
 
-**Option B, use the TanStack Query namespace `rq`.** `fastapi-rtk` re-exports `@tanstack/react-query` as `rq` (`export * as rq from '@tanstack/react-query'` in `api/src/index.ts:38`, surfaced by `core/src/index.ts:94`; the sibling `mrt` namespace re-exports `mantine-react-table` from `core/src/index.ts:95`, with long-form aliases `reactQuery` / `mantineReactTable`). Wrap a `useApi` action (or any toolkit-provided async function) in `rq.useQuery` / `rq.useMutation` so the result participates in the shared query cache (invalidation, refetch-on-focus, devtools). Never call raw `fetch` from the `queryFn` / `mutationFn`, since that re-introduces the exact problems `useCustomFetch` has.
+**Option B, use the TanStack Query namespace `rq`.** `fastapi-rtk` re-exports its bundled `@tanstack/react-query` as `rq` (`export * as rq from './rq'` in `externals/src/index.ts`, surfaced by `core/src/index.ts:94`; import it from there rather than from `@tanstack/react-query`, whose separate copy cannot see the Provider's `QueryClient`; the sibling `mrt` namespace re-exports the bundled `mantine-react-table` the same way, with long-form aliases `reactQuery` / `mantineReactTable` at `core/src/index.ts:96`). The same namespaces, plus `ld` (lodash), `zs` (zustand), `yup` and `i18nr` (react-i18next), are importable from `fastapi-rtk` or `fastapi-rtk/externals`; importing them from `fastapi-rtk/api`, `/utils`, `/zustand` or `/contexts` is deprecated. Wrap a `useApi` action (or any toolkit-provided async function) in `rq.useQuery` / `rq.useMutation` so the result participates in the shared query cache (invalidation, refetch-on-focus, devtools). Never call raw `fetch` from the `queryFn` / `mutationFn`, since that re-introduces the exact problems `useCustomFetch` has.
 
 ```jsx
 import { useApi, rq } from "fastapi-rtk";
@@ -255,7 +258,8 @@ import { NextGenDataGrid } from "fastapi-rtk";
 Key props:
 
 - Columns are auto-generated from `/_info` + `list_columns`; there is NO `columns` prop. Per-column overrides go in `columnProps`: a dict keyed by column name whose values are partial MRT `ColumnDef` objects (or factories).
-- Row identity comes from the list response's top-level `ids` array, never from a column. `useProvideApi` maps the payload to `{...item, id: data.ids[index]}` (`api/src/ApiProvider/hooks/useProvideApi.ts:183-186`, plus the streaming twin at `:236-239`), and `getRowId` reads `getItemId` = `item.id_ ?? item.id`. The zipped `id` is spread last, so it also overrides a same-named column. So adding `"id"` to the backend `list_columns` gives the grid nothing it does not already have, and only surfaces a raw `id` column to the user; `list_obj_schema` is generated `with_id=False`, which is why the raw JSON lacks one and a backend test reading `row["id"]` fails. Such a test should read the response's `ids` array instead of widening the projection.
+- Row identity comes from the list response's top-level `ids` array, never from a column. `useProvideApi` maps the payload to `{...item, id: data.ids[index]}` (`api/src/ApiProvider/hooks/useProvideApi.ts:185-188`, plus the streaming twin at `:238-241`), and `getRowId` reads `getItemId` = `item.id_ ?? item.id`. The zipped `id` is spread last, so it also overrides a same-named column. So adding `"id"` to the backend `list_columns` gives the grid nothing it does not already have, and only surfaces a raw `id` column to the user; `list_obj_schema` is generated `with_id=False`, which is why the raw JSON lacks one and a backend test reading `row["id"]` fails. Such a test should read the response's `ids` array instead of widening the projection.
+- Header filters follow `/_info`: a column whose `filters[col].lookup` is `true` (a relation with more rows than `_info` sent, or a plain column enabled in `lookup_columns`) searches the server through `HeaderSelectInput` for `eq` / `neq` / `rel_o_m` / `nrel_o_m` and `HeaderMultiSelectInput` for `in` / `rel_m_m` / `nrel_m_m`, both given a `lookup={{ column, relation }}` prop; every other operator keeps its regular input.
 - `quickFilters`: one-click filter presets rendered above the grid (`quickFiltersComponent` swaps the renderer).
 - `enableAdvancedFilters`: shows the structured filter builder.
 - `queryOnlyVisibleColumns`: perf, only requests visible columns from the backend.
@@ -399,7 +403,7 @@ const { t } = useTranslation(); // or: translation.t
 <LanguageSelector />;
 ```
 
-`useLang` reads/writes the selected language to localStorage. The translation function `t(key)` comes from react-i18next via `useTranslation()` (also re-exported from `fastapi-rtk`) or via the `translation` field on `useLang()`. Source strings double as the English keys; a German dictionary ships built-in. Extend or override through the `Provider`'s `langProps` prop: `langProps.getI18nProps.translations` takes `{locale: {key: value}}`, `langProps.i18n` accepts a full i18next instance, and `langProps.MRTLocalization` overrides the grid's Mantine React Table strings.
+`useLang` reads/writes the selected language to localStorage. The translation function `t(key)` comes from the `useTranslation()` exported by `fastapi-rtk` (the bundled react-i18next's, which the Provider wires to its i18next instance, as it does `i18nr.Trans`; the one imported from `react-i18next` itself is a separate copy that never sees it) or via the `translation` field on `useLang()`. Source strings double as the English keys; a German dictionary ships built-in. Extend or override through the `Provider`'s `langProps` prop: `langProps.getI18nProps.translations` takes `{locale: {key: value}}`, `langProps.i18n` accepts a full i18next instance, and `langProps.MRTLocalization` overrides the grid's Mantine React Table strings.
 
 ## 13. Standard routes: `UserMenu`
 

{fastapi_rtk-2.19.1 → fastapi_rtk-2.20.1}/fastapi_rtk/api/__init__.py

@@ -9,12 +9,15 @@ __all__ = [
     "P_ID",
     "P_IDS",
     "P_Q",
+    "P_LOOKUP_Q",
+    "P_COLUMN",
     "P_SESSION",
     "P_BODY",
     "P_ITEM",
     "P_ITEMS",
     "PARAM_Q",
     "PARAM_IDS_Q_SESSION_ITEMS",
+    "PARAM_LOOKUP_Q_COLUMN_SESSION",
     "PARAM_ID_SESSION",
     "PARAM_ID_SESSION_ITEM",
     "PARAM_BODY_SESSION",

{fastapi_rtk-2.19.1 → fastapi_rtk-2.20.1}/fastapi_rtk/api/model_rest_api/__init__.py

@@ -7,12 +7,15 @@ __all__ = [
     "P_ID",
     "P_IDS",
     "P_Q",
+    "P_LOOKUP_Q",
+    "P_COLUMN",
     "P_SESSION",
     "P_BODY",
     "P_ITEM",
     "P_ITEMS",
     "PARAM_Q",
     "PARAM_IDS_Q_SESSION_ITEMS",
+    "PARAM_LOOKUP_Q_COLUMN_SESSION",
     "PARAM_ID_SESSION",
     "PARAM_ID_SESSION_ITEM",
     "PARAM_BODY_SESSION",

{fastapi_rtk-2.19.1 → fastapi_rtk-2.20.1}/fastapi_rtk/api/model_rest_api/model_rest_api.py

@@ -9,6 +9,7 @@ plus one shared column / schema / body service:
 
 - ``image`` / ``file`` routes + ``pre_image`` / ``pre_file`` live on ``ModelRestApi``, backed by :class:`~.services.FileService` (``file_service``).
 - ``info`` route + ``pre_info`` + ``_generate_info_schema`` live on ``ModelRestApi``, backed by :class:`~.services.InfoService` (``info_service``).
+- ``lookup`` route + ``pre_lookup`` live on ``ModelRestApi``, backed by :class:`~.services.LookupService` (``lookup_service``), which also owns the ``is_enabled`` and ``can_call`` rules ``_info`` reads.
 - ``get_list`` route + ``pre_get_list`` live on ``ModelRestApi``, backed by :class:`~.services.ListService` (``list_service``).
 - ``get`` route + ``pre_get`` live on ``ModelRestApi``, backed by :class:`~.services.ShowService` (``show_service``).
 - ``post`` route + ``pre_add`` / ``post_add`` live on ``ModelRestApi``, backed by :class:`~.services.AddService` (``add_service``).
@@ -49,7 +50,7 @@ from ...backends.sqla.interface import SQLAInterface
 from ...backends.sqla.model import Model
 from ...backends.sqla.session import SQLASession
 from ...bases import AbstractFileManager, AbstractInterface, DBQueryParams
-from ...const import AVAILABLE_ROUTES
+from ...const import AVAILABLE_ROUTES, LookupMode
 from ...decorators import expose, permission_name, priority, protect
 from ...dependencies import current_permissions
 from ...exceptions import HTTPWithValidationException, raise_exception
@@ -62,6 +63,8 @@ from ...schemas import (
     ColumnRelationInfo,
     GeneralResponse,
     InfoResponse,
+    LookupQuerySchema,
+    LookupResponse,
     QueryBody,
     QuerySchema,
 )
@@ -73,6 +76,7 @@ from .params import (
     PARAM_ID_SESSION,
     PARAM_ID_SESSION_ITEM,
     PARAM_IDS_Q_SESSION_ITEMS,
+    PARAM_LOOKUP_Q_COLUMN_SESSION,
 )
 from .services import (
     AddService,
@@ -83,9 +87,11 @@ from .services import (
     FileService,
     InfoService,
     ListService,
+    LookupService,
     SchemaService,
     ShowService,
 )
+from .services._lookup_service import LookupColumn
 
 if typing.TYPE_CHECKING:
     from .services._download_service import DownloadPageSizeResolver
@@ -108,7 +114,7 @@ class ModelRestApi(BaseApi):
     ``ModelRestApi`` is a facade over one lazily constructed ``*_service``
     instance per route family (``add_service``, ``edit_service``,
     ``delete_service``, ``bulk_service``, ``list_service``, ``show_service``,
-    ``info_service``, ``download_service``, ``file_service``), plus
+    ``info_service``, ``lookup_service``, ``download_service``, ``file_service``), plus
     ``schema_service`` for the shared column / schema / body helpers.
     Config attributes, hooks, route registration, and delegator methods stay
     on this class; a route's logic lives on its service, reachable via the
@@ -182,6 +188,7 @@ class ModelRestApi(BaseApi):
                 "image",
                 "file",
                 "info",
+                "lookup",
                 "download",
                 "bulk",
                 "get_list",
@@ -194,13 +201,13 @@ class ModelRestApi(BaseApi):
         ]
     )
     """
-    The list of routes to expose. Available routes: `info`, `download`, `bulk`, `get_list`, `get`, `post`, `put`, `delete`.
+    The list of routes to expose. Available routes: `info`, `lookup`, `download`, `bulk`, `get_list`, `get`, `post`, `put`, `delete`.
     """
     exclude_routes: list[AVAILABLE_ROUTES] = lazy(
         list[AVAILABLE_ROUTES], with_target=False
     )
     """
-    The list of routes to exclude. Available routes: `info`, `download`, `bulk`, `get_list`, `get`, `post`, `put`, `delete`.
+    The list of routes to exclude. Available routes: `info`, `lookup`, `download`, `bulk`, `get_list`, `get`, `post`, `put`, `delete`.
     """
     protected_routes: list[AVAILABLE_ROUTES] = lazy(
         lambda self: [x for x in self.routes if x not in self.exclude_protected_routes]
@@ -331,6 +338,19 @@ class ModelRestApi(BaseApi):
     """
     The body schema for the download endpoint.
 
+    DO NOT MODIFY UNLESS YOU KNOW WHAT YOU ARE DOING.
+    """
+    lookup_query_schema: type[LookupQuerySchema] = lazy(
+        lambda self: merge_schema(
+            LookupQuerySchema,
+            {"page_size": (int | None, pydantic.Field(default=self.max_page_size))},
+            True,
+            f"{self.__class__.__name__}-LookupQuerySchema",
+        )
+    )
+    """
+    The query schema for the lookup endpoint.
+
     DO NOT MODIFY UNLESS YOU KNOW WHAT YOU ARE DOING.
     """
 
@@ -429,6 +449,24 @@ class ModelRestApi(BaseApi):
     }
     ```
     """
+    lookup_columns: dict[str, bool | LookupColumn] = lazy(
+        dict[str, bool | LookupColumn], with_target=False
+    )
+    """
+    Configures the `/_lookup/{column}` route per column. A bare bool is short for `{"enabled": <bool>}`.
+
+    - `enabled`: `True` turns the lookup on; every column defaults to off. Plain columns only from search columns, relations only when the related model has `__repr_columns__` or `columns` is set.
+    - `columns`: the related columns `search` matches, instead of `__repr_columns__`.
+    - `query`: replaces the lookup with `(api, column, q: LookupQuerySchema, session) -> {"count", "values"}`; with `q.ids` set it returns exactly those rows.
+
+    Example:
+    ```python
+    lookup_columns = {
+        "city": True,
+        "owner": {"enabled": True, "columns": ["first_name", "last_name"]},
+    }
+    ```
+    """
     search_filters: dict[str, list[type[BaseFilter]]] = lazy(
         lambda: dict[str, list[type[BaseFilter]]]()
     )
@@ -1104,6 +1142,10 @@ class ModelRestApi(BaseApi):
     """
     The service backing the info route's ``info`` / ``generate_info_schema`` implementations.
     """
+    lookup_service: LookupService = lazy(lambda self: LookupService(self))
+    """
+    The service backing the lookup route's ``lookup`` implementation and the ``is_enabled`` and ``can_call`` rules the info route reads.
+    """
     download_service: DownloadService = lazy(lambda self: DownloadService(self))
     """
     The service backing the download route's ``download`` / ``download_page_size`` / ``export_data`` / ``import_data`` implementations.
@@ -1286,6 +1328,8 @@ class ModelRestApi(BaseApi):
                 },
             )
 
+        self.lookup_service.validate_config()
+
     def _init_routes(self):
         """
         Init routes for the API.
@@ -1295,6 +1339,12 @@ class ModelRestApi(BaseApi):
             unavailable.append("image")
         if not self.datamodel.get_file_column_list():
             unavailable.append("file")
+        if not any(
+            self.lookup_service.is_enabled(col, mode)
+            for mode in typing.get_args(LookupMode)
+            for col in [*self.add_columns, *self.edit_columns, *self.search_columns]
+        ):
+            unavailable.append("lookup")
 
         # Rebind on the instance instead of removing in place: `routes` may be a
         # class attribute shared with subclasses.
@@ -1342,6 +1392,21 @@ class ModelRestApi(BaseApi):
 
         return dependency
 
+    def get_lookup_q_factory(self):
+        """
+        Returns a dependency that yields the lookup route's LookupQuerySchema.
+
+        Returns:
+            collections.abc.Callable[..., Coroutine[typing.Any, typing.Any, LookupQuerySchema]]: The dependency that yields the query schema.
+        """
+
+        async def dependency(
+            q: typing.Annotated[self.lookup_query_schema, fastapi.Query()],  # type: ignore
+        ):
+            return typing.cast(LookupQuerySchema, q)
+
+        return dependency
+
     """
     --------------------------------------------------------------------------------------------------------
         ROUTE HELPER METHODS
@@ -1406,9 +1471,7 @@ class ModelRestApi(BaseApi):
             filter_classes=self.base_filters,
             opr_filters=q.opr_filters,
             opr_filter_classes=self.base_opr_filters,
-            global_filter=(q.columns or self.list_columns, q.global_filter)
-            if q.global_filter
-            else None,
+            search=(q.columns or self.list_columns, q.search) if q.search else None,
         )
 
     """
@@ -1492,6 +1555,67 @@ class ModelRestApi(BaseApi):
             permissions, session, session_count
         )
 
+    """
+    -------------
+     LOOKUP
+    -------------
+    """
+
+    def lookup(self):
+        """
+        Lookup endpoint for the API.
+        """
+        expose_params = {
+            "name": "Lookup Column Values",
+            "description": f"Search the values of a column of the model {self.datamodel.obj.__name__}: related rows by their display columns, or the distinct values of a plain column.",
+            "response_model": LookupResponse | typing.Any,
+            **self.expose_params.get("lookup", {}),
+        }
+        priority(7)(self.lookup_headless)
+        expose("/_lookup/{column}", methods=["GET"], **expose_params)(
+            self.lookup_headless
+        )
+
+    async def lookup_headless(
+        self,
+        column: str,
+        q: LookupQuerySchema = SelfDepends().get_lookup_q_factory,
+        permissions: list[str] = SelfDepends().get_current_permissions,
+        session: SQLASession = SelfDepends().datamodel.get_session_factory,
+        session_count: SQLASession = SelfDepends().datamodel.get_session_factory,
+    ):
+        """
+        Retrieves one page of lookup values in headless mode.
+
+        Args:
+            column (str): The column to look up.
+            q (LookupQuerySchema): The query schema. Its `page_size` is capped at `max_page_size`.
+            permissions (list[str]): The current user's permissions on this API.
+            session (SQLASession): The session for the values query.
+            session_count (SQLASession): The session for the count query.
+
+        Returns:
+            LookupResponse: The matching values and their total count.
+
+        ### Note:
+            If you are overriding this method, make sure to copy all the decorators too.
+        """
+        return await self.lookup_service.lookup(
+            column, q, permissions, session, session_count
+        )
+
+    async def pre_lookup(
+        self, body: LookupResponse, params: PARAM_LOOKUP_Q_COLUMN_SESSION
+    ):
+        """
+        Pre-process the lookup response before returning it.
+        The response still needs to adhere to the LookupResponse schema.
+
+        Args:
+            body (LookupResponse): The response body.
+            params (Params): Additional data passed to the handler.
+        """
+
     """
     -------------
      LIST