rn-forge-fastapi 0.4.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,936 @@
1
+ """Tabular export and import, and batch get, create, update and delete, over FastAPI.
2
+
3
+ Requires the ``transfer`` extra. Not imported by :mod:`rn_forge.fastapi`.
4
+ Persistence is the application's: the route factories take a store dependency
5
+ that implements one of the store protocols, and :func:`read_rows` validates
6
+ without saving.
7
+ """
8
+
9
+ import csv
10
+ import io
11
+ from collections.abc import (
12
+ Callable,
13
+ Collection,
14
+ Iterable,
15
+ Iterator,
16
+ Mapping,
17
+ Sequence,
18
+ )
19
+ from dataclasses import dataclass, field
20
+ from typing import Any, Protocol, cast
21
+
22
+ import tablib
23
+ from fastapi import (
24
+ APIRouter,
25
+ Body,
26
+ Depends,
27
+ Header,
28
+ Query,
29
+ Request,
30
+ UploadFile,
31
+ )
32
+ from fastapi.concurrency import run_in_threadpool
33
+ from fastapi.exceptions import RequestValidationError
34
+ from fastapi.params import Depends as DependsParam
35
+ from fastapi.responses import JSONResponse, Response, StreamingResponse
36
+ from pydantic import BaseModel, Field, TypeAdapter, ValidationError, create_model
37
+ from rn_forge.data import write_xlsx
38
+ from rn_forge.fastapi.openapi import operation_id
39
+ from rn_forge.fastapi.read_mask import read_mask_param
40
+ from rn_forge.web import (
41
+ NULL_FIELD_DETAIL,
42
+ PROBLEM_MEDIA_TYPE,
43
+ REQUIRED_FIELD_DETAIL,
44
+ VALIDATION_ERROR,
45
+ BatchUpdateItem,
46
+ ETagCodec,
47
+ ProblemResponse,
48
+ ReadMask,
49
+ RowsInvalid,
50
+ VersionETagCodec,
51
+ check_item_precondition,
52
+ default_registry,
53
+ field_error,
54
+ merge_representation,
55
+ render_problem,
56
+ )
57
+ from rn_forge.web.transfer import (
58
+ NON_EMPTY_LIST_DETAIL,
59
+ TABULAR_FORMATS,
60
+ ImportCounts,
61
+ RowError,
62
+ TabularFormat,
63
+ batch_get_ids,
64
+ content_disposition,
65
+ export_cap_problem,
66
+ import_report_body,
67
+ negotiate_tabular_format,
68
+ parse_batch_update,
69
+ parse_flag,
70
+ row_cap_problem,
71
+ row_errors_problem,
72
+ unreadable_file_detail,
73
+ unsupported_file_detail,
74
+ )
75
+
76
+ __all__ = [
77
+ "BatchCreateStore",
78
+ "BatchDeleteStore",
79
+ "BatchGetStore",
80
+ "BatchUpdateStore",
81
+ "Current",
82
+ "ImportStore",
83
+ "RowsResult",
84
+ "TemplateSource",
85
+ "batch_create_router",
86
+ "batch_delete_router",
87
+ "batch_get_router",
88
+ "batch_update_router",
89
+ "import_router",
90
+ "import_template_router",
91
+ "problem_response",
92
+ "read_rows",
93
+ "tabular_export",
94
+ "tabular_format",
95
+ "tabular_response",
96
+ ]
97
+
98
+ _READABLE = ("csv", "tsv", "xlsx")
99
+
100
+
101
+ def tabular_format(
102
+ allowed: Iterable[str] = ("csv", "xlsx"),
103
+ ) -> Callable[..., TabularFormat | None]:
104
+ """Return a dependency yielding the tabular format the request asks for.
105
+
106
+ The ``format`` query parameter wins over ``Accept``; see
107
+ :func:`rn_forge.web.transfer.negotiate_tabular_format`. The dependency
108
+ yields ``None`` when the response should be the endpoint's JSON.
109
+
110
+ Args:
111
+ allowed: The extensions the endpoint offers.
112
+ """
113
+ offered = tuple(allowed)
114
+
115
+ def dependency(
116
+ accept: str | None = Header(default=None),
117
+ format: str | None = Query(default=None),
118
+ ) -> TabularFormat | None:
119
+ return negotiate_tabular_format(accept, format, offered)
120
+
121
+ return dependency
122
+
123
+
124
+ def problem_response(problem: ProblemResponse) -> JSONResponse:
125
+ """Send a rendered problem, such as ``row_errors_problem(...)``, as a response."""
126
+ return JSONResponse(
127
+ problem.body,
128
+ status_code=problem.status,
129
+ media_type=PROBLEM_MEDIA_TYPE,
130
+ headers=dict(problem.headers),
131
+ )
132
+
133
+
134
+ def _columns(model: type[BaseModel]) -> list[str]:
135
+ fields = [
136
+ info.serialization_alias or name for name, info in model.model_fields.items()
137
+ ]
138
+ computed = [
139
+ info.alias or name for name, info in model.model_computed_fields.items()
140
+ ]
141
+ return [*fields, *computed]
142
+
143
+
144
+ def _records(
145
+ rows: Iterable[Any], model: type[BaseModel], mode: str
146
+ ) -> Iterator[dict[str, Any]]:
147
+ for row in rows:
148
+ yield model.model_validate(row, from_attributes=True).model_dump(
149
+ by_alias=True,
150
+ mode=mode,
151
+ )
152
+
153
+
154
+ async def tabular_response(
155
+ rows: Iterable[Any], model: type[BaseModel], fmt: TabularFormat, filename: str
156
+ ) -> Response:
157
+ """Render *rows* as a file download in *fmt*.
158
+
159
+ Each row is validated into *model* with ``from_attributes=True`` and
160
+ dumped by alias, so the model's serialization aliases are the column
161
+ headers and its computed fields are columns. Use ``serialization_alias``
162
+ for a header that differs from the attribute name: a plain ``alias`` would
163
+ also rename the attribute read from an ORM object. CSV is streamed; the other
164
+ formats are built in memory in a worker thread.
165
+
166
+ Args:
167
+ rows: ORM objects, mappings or *model* instances.
168
+ model: The export model.
169
+ fmt: The chosen format.
170
+ filename: The download name, extension included.
171
+
172
+ Returns:
173
+ A ``StreamingResponse`` for CSV, otherwise a ``Response``.
174
+ """
175
+ headers = {"Content-Disposition": content_disposition(filename)}
176
+ columns = _columns(model)
177
+ if fmt.extension == "csv":
178
+
179
+ def lines() -> Iterator[str]:
180
+ buffer = io.StringIO()
181
+ writer = csv.writer(buffer)
182
+ writer.writerow(columns)
183
+ yield buffer.getvalue()
184
+ buffer.seek(0)
185
+ buffer.truncate()
186
+ for record in _records(rows, model, "json"):
187
+ writer.writerow([record[c] for c in columns])
188
+ yield buffer.getvalue()
189
+ buffer.seek(0)
190
+ buffer.truncate()
191
+
192
+ return StreamingResponse(lines(), media_type=fmt.media_type, headers=headers)
193
+
194
+ return Response(
195
+ await run_in_threadpool(_build_body, rows, model, fmt, columns),
196
+ media_type=fmt.media_type,
197
+ headers=headers,
198
+ )
199
+
200
+
201
+ def _build_body(
202
+ rows: Iterable[Any], model: type[BaseModel], fmt: TabularFormat, columns: list[str]
203
+ ) -> bytes | str:
204
+ dataset: Any = tablib.Dataset(headers=columns)
205
+ for record in _records(rows, model, "python"):
206
+ dataset.append([record[c] for c in columns])
207
+ if fmt.extension == "xlsx":
208
+ return write_xlsx(dataset)
209
+ return dataset.export(fmt.tablib_name)
210
+
211
+
212
+ @dataclass
213
+ class RowsResult[T]:
214
+ """The outcome of :func:`read_rows`: the valid rows and every failed cell."""
215
+
216
+ valid: list[T] = field(default_factory=list[T])
217
+ errors: list[RowError] = field(default_factory=list[RowError])
218
+ total: int = 0
219
+
220
+
221
+ async def read_rows[T: BaseModel](
222
+ upload: UploadFile, model: type[T], *, formats: Sequence[str] = _READABLE
223
+ ) -> RowsResult[T]:
224
+ """Load *upload* with tablib and validate each row against *model*.
225
+
226
+ The format comes from the file extension, else from the part's content
227
+ type, among *formats*. Row indexes
228
+ are zero-based positions after the header row. An error's ``field`` is the
229
+ column header (the model's alias); a validator that raises ``ValueError``
230
+ reports its own message. ``total`` is the number of data rows read.
231
+
232
+ Args:
233
+ upload: The uploaded file.
234
+ model: The row model.
235
+ formats: The accepted extensions, a subset of csv, tsv and xlsx.
236
+
237
+ Raises:
238
+ ValueError: The file's type is not in *formats*, with
239
+ :func:`~rn_forge.web.transfer.unsupported_file_detail` as its
240
+ message, or its content cannot be parsed, with
241
+ :func:`~rn_forge.web.transfer.unreadable_file_detail`.
242
+ """
243
+ accepted = tuple(e for e in formats if e in _READABLE)
244
+ name = upload.filename or ""
245
+ candidates = (
246
+ [name.rpartition(".")[2].lower()]
247
+ if "." in name
248
+ else [
249
+ f.extension
250
+ for f in TABULAR_FORMATS.values()
251
+ if f.media_type == upload.content_type
252
+ ]
253
+ )
254
+ extension = next((ext for ext in candidates if ext in accepted), "")
255
+ if not extension:
256
+ raise ValueError(unsupported_file_detail(formats))
257
+ raw = await upload.read()
258
+ return await run_in_threadpool(_parse_rows, raw, extension, model)
259
+
260
+
261
+ def _parse_rows[T: BaseModel](
262
+ raw: bytes, extension: str, model: type[T]
263
+ ) -> RowsResult[T]:
264
+ data: bytes | str = raw if extension == "xlsx" else raw.decode("utf-8-sig")
265
+ try:
266
+ dataset: Any = tablib.Dataset()
267
+ dataset.load(data, format=TABULAR_FORMATS[extension].tablib_name)
268
+ except Exception as exc:
269
+ raise ValueError(unreadable_file_detail(extension)) from exc
270
+ adapter = TypeAdapter(model)
271
+ rows = _dicts(dataset)
272
+ result = RowsResult[T](total=len(rows))
273
+ for index, row in enumerate(rows):
274
+ try:
275
+ result.valid.append(adapter.validate_python(row))
276
+ except ValidationError as exc:
277
+ result.errors.extend(_row_errors(index, exc))
278
+ return result
279
+
280
+
281
+ def _dicts(dataset: Any) -> list[Mapping[str, Any]]:
282
+ return dataset.dict
283
+
284
+
285
+ def _row_errors(index: int, exc: ValidationError) -> Iterator[RowError]:
286
+ for err in exc.errors():
287
+ message = (
288
+ str(err["ctx"]["error"])
289
+ if err["type"] == "value_error" and "ctx" in err
290
+ else err["msg"]
291
+ )
292
+ yield RowError(index, str(err["loc"][0]) if err["loc"] else "", message)
293
+
294
+
295
+ async def tabular_export(
296
+ rows: Sequence[Any],
297
+ model: type[BaseModel],
298
+ fmt: TabularFormat,
299
+ filename: str,
300
+ *,
301
+ max_rows: int | None = None,
302
+ instance: str,
303
+ ) -> Response:
304
+ """Answer an export request: *rows* as a download, or the cap problem.
305
+
306
+ Call it from a list route once :func:`tabular_format` yielded a format.
307
+
308
+ Args:
309
+ rows: The rows to export, as for :func:`tabular_response`.
310
+ model: The export model.
311
+ fmt: The chosen format.
312
+ filename: The download name, extension included.
313
+ max_rows: The most rows an export may hold; ``None`` for no limit.
314
+ instance: The ``instance`` of the problem, in practice the request path.
315
+
316
+ Returns:
317
+ A 422 problem when ``len(rows) > max_rows``, otherwise
318
+ :func:`tabular_response`'s response.
319
+ """
320
+ if max_rows is not None and len(rows) > max_rows:
321
+ return problem_response(export_cap_problem(max_rows, instance=instance))
322
+ return await tabular_response(rows, model, fmt, filename)
323
+
324
+
325
+ class ImportStore[T](Protocol):
326
+ """Persists the rows of an import."""
327
+
328
+ async def import_rows(
329
+ self, rows: Sequence[T], *, validate_only: bool
330
+ ) -> ImportCounts:
331
+ """Upsert every row in one transaction, rolling back when *validate_only*.
332
+
333
+ Raises:
334
+ RowsInvalid: A row fails a check only the store can make.
335
+ """
336
+ ...
337
+
338
+
339
+ class TemplateSource(Protocol):
340
+ """Supplies the rows that prefill an import template."""
341
+
342
+ async def rows(self) -> Iterable[Any]:
343
+ """Return the current filtered rows; called only when ``prefill`` is set."""
344
+ ...
345
+
346
+
347
+ class BatchCreateStore[T](Protocol):
348
+ """Persists a batch of new resources."""
349
+
350
+ async def create_many(self, items: Sequence[T]) -> Sequence[Any]:
351
+ """Create every item in one transaction and return the created objects.
352
+
353
+ Raises:
354
+ ItemsDenied: An item is not permitted, raised before anything is written.
355
+ """
356
+ ...
357
+
358
+
359
+ class BatchDeleteStore(Protocol):
360
+ """Finds and deletes a batch of resources."""
361
+
362
+ async def find(self, ids: Sequence[str]) -> Collection[str]:
363
+ """Return which of *ids* exist within the caller's scope."""
364
+ ...
365
+
366
+ async def delete_many(self, ids: Sequence[str]) -> None:
367
+ """Delete every id in one transaction.
368
+
369
+ Raises:
370
+ ItemsDenied: An id may not be deleted, raised before anything is deleted.
371
+ """
372
+ ...
373
+
374
+
375
+ class BatchGetStore(Protocol):
376
+ """Finds a batch of resources."""
377
+
378
+ async def get_many(self, ids: Sequence[str]) -> Mapping[str, Any]:
379
+ """Return the rows of *ids* that exist within the caller's scope, keyed by id as a string."""
380
+ ...
381
+
382
+
383
+ class Current(Protocol):
384
+ """A row as :class:`BatchUpdateStore` reports it: the row, and its version if it has one."""
385
+
386
+ @property
387
+ def row(self) -> Any:
388
+ """The stored row."""
389
+ ...
390
+
391
+ @property
392
+ def version(self) -> int | None:
393
+ """The row's version, or ``None`` when the resource is unversioned."""
394
+ ...
395
+
396
+
397
+ class BatchUpdateStore[T](Protocol):
398
+ """Finds and updates a batch of resources."""
399
+
400
+ async def current(self, ids: Sequence[str]) -> Mapping[str, Current]:
401
+ """Return each of *ids* that exists within the caller's scope, keyed by id as a string."""
402
+ ...
403
+
404
+ async def update_many(self, items: Sequence[tuple[str, T]]) -> Sequence[Any]:
405
+ """Write every validated document in one transaction and return the updated rows.
406
+
407
+ Bumps each versioned row's version. The rows are returned in the order
408
+ of *items*.
409
+
410
+ Raises:
411
+ ItemsDenied: An item is not permitted, with ``root="requests"``,
412
+ raised before anything is written.
413
+ """
414
+ ...
415
+
416
+
417
+ def _router(dependencies: Sequence[DependsParam]) -> APIRouter:
418
+ return APIRouter(
419
+ dependencies=list(dependencies), generate_unique_id_function=operation_id
420
+ )
421
+
422
+
423
+ def _list_model(name: str, member: str, item: Any) -> type[BaseModel]:
424
+ """Build ``{member: [item]}``, the schema FastAPI documents and validates."""
425
+ make = cast("Callable[..., type[BaseModel]]", create_model)
426
+ return make(name, **{member: (list[item], ...)})
427
+
428
+
429
+ def _rejection(loc: str, kind: str, message: str) -> RequestValidationError:
430
+ return RequestValidationError(
431
+ [{"type": kind, "loc": ("body", loc), "msg": message}]
432
+ )
433
+
434
+
435
+ def _error_message(err: Mapping[str, Any]) -> str:
436
+ if err["type"] == "missing":
437
+ return REQUIRED_FIELD_DETAIL
438
+ if "input" in err and err["input"] is None:
439
+ return NULL_FIELD_DETAIL
440
+ if err["type"] == "value_error" and "ctx" in err:
441
+ return str(err["ctx"]["error"])
442
+ return err["msg"]
443
+
444
+
445
+ def _item_errors(index: int, exc: ValidationError) -> Iterator[RowError]:
446
+ for err in exc.errors():
447
+ yield RowError(
448
+ index, ".".join(str(part) for part in err["loc"]), _error_message(err)
449
+ )
450
+
451
+
452
+ async def _checked_list(
453
+ request: Request, key: str, max_rows: int | None
454
+ ) -> list[object]:
455
+ """Return the raw body's *key* member, which must be a non-empty list within *max_rows*."""
456
+ try:
457
+ body: object = await request.json()
458
+ except ValueError:
459
+ body = None
460
+ members: Mapping[str, object] = (
461
+ cast("Mapping[str, object]", body) if isinstance(body, Mapping) else {}
462
+ )
463
+ if key not in members:
464
+ raise _rejection(key, "missing", "Field required")
465
+ value: object = members[key]
466
+ if not isinstance(value, list) or not value:
467
+ raise _rejection(key, "value_error", NON_EMPTY_LIST_DETAIL)
468
+ entries = cast("list[object]", value)
469
+ if max_rows is not None and len(entries) > max_rows:
470
+ raise ValueError(
471
+ row_cap_problem("batch", max_rows, instance=request.url.path).problem.detail
472
+ )
473
+ return entries
474
+
475
+
476
+ def _list_guard(
477
+ key: str, max_rows: int | None, item_model: type[BaseModel] | None = None
478
+ ) -> DependsParam:
479
+ """Check the raw body's *key* member, and its items against *item_model*.
480
+
481
+ Runs before FastAPI validates the body, so the checks fire in the order
482
+ the wire contract states and item failures use the row-error wording.
483
+ """
484
+ items = TypeAdapter(item_model) if item_model is not None else None
485
+
486
+ async def guard(request: Request) -> None:
487
+ value = await _checked_list(request, key, max_rows)
488
+ if items is not None:
489
+ errors: list[RowError] = []
490
+ for index, item in enumerate(value):
491
+ try:
492
+ items.validate_python(item)
493
+ except ValidationError as exc:
494
+ errors.extend(_item_errors(index, exc))
495
+ if errors:
496
+ raise RowsInvalid(errors, root=key)
497
+
498
+ return Depends(guard)
499
+
500
+
501
+ def import_router[T: BaseModel](
502
+ collection: str,
503
+ *,
504
+ model: type[T],
505
+ store: Callable[..., ImportStore[T]],
506
+ formats: Sequence[str] = ("csv", "xlsx"),
507
+ max_rows: int | None = None,
508
+ dependencies: Sequence[DependsParam] = (),
509
+ ) -> APIRouter:
510
+ """Build ``POST {collection}:import``, a multipart upload of a ``file`` part.
511
+
512
+ Each row is validated into *model*, whose aliases are the column headers.
513
+ Any failed row answers a 422 problem and nothing reaches the store. The
514
+ ``validateOnly`` query parameter is parsed by
515
+ :func:`~rn_forge.web.transfer.parse_flag`. The response is 200 with
516
+ :func:`~rn_forge.web.transfer.import_report_body`.
517
+
518
+ Args:
519
+ collection: The collection path, for example ``/orders``.
520
+ model: The row model.
521
+ store: A dependency returning the :class:`ImportStore`.
522
+ formats: The accepted file extensions.
523
+ max_rows: The most data rows an import may hold; ``None`` for no limit.
524
+ dependencies: Dependencies of the route, as for ``APIRouter``.
525
+
526
+ Returns:
527
+ The router.
528
+ """
529
+ router = _router(dependencies)
530
+ offered = tuple(formats)
531
+
532
+ async def import_items(
533
+ request: Request,
534
+ file: UploadFile,
535
+ validate_only: str | None = Query(default=None, alias="validateOnly"),
536
+ target: ImportStore[T] = Depends(store),
537
+ ) -> Response:
538
+ try:
539
+ result = await read_rows(file, model, formats=offered)
540
+ except ValueError as exc:
541
+ raise _rejection("file", "value_error", str(exc)) from exc
542
+ path = request.url.path
543
+ if max_rows is not None and result.total > max_rows:
544
+ return problem_response(row_cap_problem("import", max_rows, instance=path))
545
+ if result.errors:
546
+ return problem_response(row_errors_problem(result.errors, instance=path))
547
+ flag = parse_flag(validate_only)
548
+ counts = await target.import_rows(result.valid, validate_only=flag)
549
+ return JSONResponse(
550
+ import_report_body(
551
+ created=counts.created,
552
+ updated=counts.updated,
553
+ skipped=counts.skipped,
554
+ validate_only=flag,
555
+ )
556
+ )
557
+
558
+ router.add_api_route(f"{collection}:import", import_items, methods=["POST"])
559
+ return router
560
+
561
+
562
+ def import_template_router[T: BaseModel](
563
+ collection: str,
564
+ *,
565
+ model: type[T],
566
+ source: Callable[..., TemplateSource],
567
+ formats: Sequence[str] = ("csv", "xlsx"),
568
+ max_rows: int | None = None,
569
+ dependencies: Sequence[DependsParam] = (),
570
+ ) -> APIRouter:
571
+ """Build ``GET {collection}:importTemplate``, the import columns as a file.
572
+
573
+ The format is negotiated as for :func:`tabular_format`, else the first of
574
+ *formats*. The columns are *model*'s aliases, so the file round-trips
575
+ through :func:`import_router`. Without ``prefill`` the file holds the
576
+ header row only; with it, the rows of :class:`TemplateSource`. The download
577
+ is named ``import-template.<ext>``.
578
+
579
+ Args:
580
+ collection: The collection path, for example ``/orders``.
581
+ model: The import model.
582
+ source: A dependency returning the :class:`TemplateSource`.
583
+ formats: The offered file extensions.
584
+ max_rows: The most rows a prefilled template may hold; ``None`` for no limit.
585
+ dependencies: Dependencies of the route, as for ``APIRouter``.
586
+
587
+ Returns:
588
+ The router.
589
+ """
590
+ router = _router(dependencies)
591
+ offered = tuple(formats)
592
+
593
+ async def import_template(
594
+ request: Request,
595
+ fmt: TabularFormat | None = Depends(tabular_format(offered)), # noqa: B008 # dependency factory
596
+ prefill: str | None = Query(default=None),
597
+ supplier: TemplateSource = Depends(source),
598
+ ) -> Response:
599
+ chosen = fmt or TABULAR_FORMATS[offered[0]]
600
+ rows = list(await supplier.rows()) if parse_flag(prefill) else []
601
+ return await tabular_export(
602
+ rows,
603
+ model,
604
+ chosen,
605
+ f"import-template.{chosen.extension}",
606
+ max_rows=max_rows,
607
+ instance=request.url.path,
608
+ )
609
+
610
+ router.add_api_route(
611
+ f"{collection}:importTemplate", import_template, methods=["GET"]
612
+ )
613
+ return router
614
+
615
+
616
+ def batch_create_router[T: BaseModel](
617
+ collection: str,
618
+ *,
619
+ model: type[T],
620
+ response_model: type[BaseModel],
621
+ resource_name: str,
622
+ store: Callable[..., BatchCreateStore[T]],
623
+ max_rows: int | None = None,
624
+ dependencies: Sequence[DependsParam] = (),
625
+ ) -> APIRouter:
626
+ """Build ``POST {collection}:batchCreate``, taking ``{"requests": [...]}``.
627
+
628
+ Every item is validated into *model* and every failure is reported, as a
629
+ 422 problem pointing at ``/requests/<i>/<field>``, and the store is not called. The response is 200 with
630
+ the created objects, as *response_model* dumped by alias, under
631
+ *resource_name*.
632
+
633
+ Args:
634
+ collection: The collection path, for example ``/orders``.
635
+ model: The create model of one item.
636
+ response_model: The model of one created resource.
637
+ resource_name: The response member that holds the created resources.
638
+ store: A dependency returning the :class:`BatchCreateStore`.
639
+ max_rows: The most items a batch may hold; ``None`` for no limit.
640
+ dependencies: Dependencies of the route, as for ``APIRouter``.
641
+
642
+ Returns:
643
+ The router.
644
+ """
645
+ router = _router(dependencies)
646
+ request_model = _list_model(
647
+ f"{model.__name__}BatchCreateRequest", "requests", model
648
+ )
649
+ result_model = _list_model(
650
+ f"{response_model.__name__}BatchCreateResponse", resource_name, response_model
651
+ )
652
+
653
+ async def batch_create(
654
+ body: Any = Body(),
655
+ target: BatchCreateStore[T] = Depends(store),
656
+ ) -> dict[str, Any]:
657
+ created = await target.create_many(body.requests)
658
+ return {
659
+ resource_name: [
660
+ response_model.model_validate(c, from_attributes=True).model_dump(
661
+ by_alias=True, mode="json"
662
+ )
663
+ for c in created
664
+ ]
665
+ }
666
+
667
+ batch_create.__annotations__["body"] = request_model
668
+ router.add_api_route(
669
+ f"{collection}:batchCreate",
670
+ batch_create,
671
+ methods=["POST"],
672
+ response_model=result_model,
673
+ dependencies=[_list_guard("requests", max_rows, model)],
674
+ )
675
+ return router
676
+
677
+
678
+ def batch_delete_router(
679
+ collection: str,
680
+ *,
681
+ resource_label: str,
682
+ store: Callable[..., BatchDeleteStore],
683
+ max_rows: int | None = None,
684
+ dependencies: Sequence[DependsParam] = (),
685
+ ) -> APIRouter:
686
+ """Build ``POST {collection}:batchDelete``, taking ``{"ids": [...]}``.
687
+
688
+ Ids may be strings or integers and are compared as strings. The first id
689
+ that :meth:`BatchDeleteStore.find` does not return is a 404 reading
690
+ ``{resource_label} {id} not found``. The response is 204.
691
+
692
+ Args:
693
+ collection: The collection path, for example ``/orders``.
694
+ resource_label: The resource's name in the 404 detail, for example ``Order``.
695
+ store: A dependency returning the :class:`BatchDeleteStore`.
696
+ max_rows: The most ids a batch may hold; ``None`` for no limit.
697
+ dependencies: Dependencies of the route, as for ``APIRouter``.
698
+
699
+ Returns:
700
+ The router.
701
+ """
702
+ router = _router(dependencies)
703
+ request_model = _list_model("BatchDeleteRequest", "ids", str | int)
704
+
705
+ async def batch_delete(
706
+ body: Any = Body(),
707
+ target: BatchDeleteStore = Depends(store),
708
+ ) -> Response:
709
+ ids = [str(i) for i in body.ids]
710
+ found = set(await target.find(ids))
711
+ for item in ids:
712
+ if item not in found:
713
+ raise LookupError(f"{resource_label} {item} not found")
714
+ await target.delete_many(ids)
715
+ return Response(status_code=204)
716
+
717
+ batch_delete.__annotations__["body"] = request_model
718
+ router.add_api_route(
719
+ f"{collection}:batchDelete",
720
+ batch_delete,
721
+ methods=["POST"],
722
+ status_code=204,
723
+ response_class=Response,
724
+ dependencies=[_list_guard("ids", max_rows)],
725
+ )
726
+ return router
727
+
728
+
729
+ def _no_mask() -> None:
730
+ return None
731
+
732
+
733
+ def batch_get_router(
734
+ collection: str,
735
+ *,
736
+ response_model: type[BaseModel],
737
+ resource_name: str,
738
+ resource_label: str,
739
+ store: Callable[..., BatchGetStore],
740
+ max_rows: int | None = None,
741
+ read_mask: bool = True,
742
+ dependencies: Sequence[DependsParam] = (),
743
+ ) -> APIRouter:
744
+ """Build ``GET {collection}:batchGet``, taking a repeated ``ids`` query parameter.
745
+
746
+ A missing ``ids`` parameter, or more ids than *max_rows*, is a 400 problem.
747
+ The first id that :meth:`BatchGetStore.get_many` does not return is a 404
748
+ reading ``{resource_label} {id} not found``. The response is 200 with one
749
+ entry per requested id, in request order and repeating duplicates, as
750
+ *response_model* dumped by alias, under *resource_name*. With *read_mask*,
751
+ the route also takes ``readMask`` (see :func:`rn_forge.fastapi.read_mask_param`)
752
+ and each resource holds only the fields it names.
753
+
754
+ Args:
755
+ collection: The collection path, for example ``/orders``.
756
+ response_model: The model of one resource.
757
+ resource_name: The response member that holds the resources.
758
+ resource_label: The resource's name in the 404 detail, for example ``Order``.
759
+ store: A dependency returning the :class:`BatchGetStore`.
760
+ max_rows: The most ids a batch may hold; ``None`` for no limit.
761
+ read_mask: Whether the route accepts ``readMask``.
762
+ dependencies: Dependencies of the route, as for ``APIRouter``.
763
+
764
+ Returns:
765
+ The router.
766
+ """
767
+ router = _router(dependencies)
768
+ result_model = _list_model(
769
+ f"{response_model.__name__}BatchGetResponse", resource_name, response_model
770
+ )
771
+ mask_dependency = read_mask_param(response_model) if read_mask else _no_mask
772
+
773
+ async def batch_get(
774
+ ids: list[str] = Query(default_factory=list),
775
+ target: BatchGetStore = Depends(store),
776
+ mask: ReadMask | None = Depends(mask_dependency),
777
+ ) -> Any:
778
+ wanted = batch_get_ids(ids, cap=max_rows)
779
+ found = await target.get_many(wanted)
780
+ for item in wanted:
781
+ if item not in found:
782
+ raise LookupError(f"{resource_label} {item} not found")
783
+ resources = [_dump(response_model, found[i]) for i in wanted]
784
+ if mask is None:
785
+ return {resource_name: resources}
786
+ # A returned response is not validated against the full model.
787
+ return JSONResponse({resource_name: [mask.apply(r) for r in resources]})
788
+
789
+ router.add_api_route(
790
+ f"{collection}:batchGet",
791
+ batch_get,
792
+ methods=["GET"],
793
+ response_model=result_model,
794
+ )
795
+ return router
796
+
797
+
798
+ def batch_update_router[T: BaseModel](
799
+ collection: str,
800
+ *,
801
+ model: type[T],
802
+ response_model: type[BaseModel],
803
+ resource_name: str,
804
+ resource_label: str,
805
+ store: Callable[..., BatchUpdateStore[T]],
806
+ max_rows: int | None = None,
807
+ require_if_match: bool = False,
808
+ codec: ETagCodec | None = None,
809
+ dependencies: Sequence[DependsParam] = (),
810
+ ) -> APIRouter:
811
+ """Build ``POST {collection}:batchUpdate``, taking ``{"requests": [...]}``.
812
+
813
+ Each item is ``{"id", "patch", "ifMatch"}``: *patch* is a JSON Merge Patch
814
+ and ``ifMatch`` an optional precondition. The current row is dumped through
815
+ *model* by alias, merged with the patch and validated as *model*. The first
816
+ failing step answers: the list and item shape are 422 problems, a missing
817
+ id is a 404 reading ``{resource_label} {id} not found``, a failed
818
+ precondition is a 428, 400 or 412 pointing at ``/requests/<i>/ifMatch``,
819
+ and an invalid merged document is a 422 problem pointing at
820
+ ``/requests/<i>/patch/<field>``. The store is not asked to write after a
821
+ failure. Ids may be strings or integers and are compared as strings. The
822
+ response is 200 with the updated rows, as *response_model* dumped by alias,
823
+ under *resource_name*.
824
+
825
+ Args:
826
+ collection: The collection path, for example ``/orders``.
827
+ model: The model of one full resource document.
828
+ response_model: The model of one updated resource.
829
+ resource_name: The response member that holds the updated resources.
830
+ resource_label: The resource's name in the 404 detail, for example ``Order``.
831
+ store: A dependency returning the :class:`BatchUpdateStore`.
832
+ max_rows: The most items a batch may hold; ``None`` for no limit.
833
+ require_if_match: When ``True``, a versioned item without ``ifMatch``
834
+ is a 428.
835
+ codec: The validator format; ``None`` uses
836
+ :class:`rn_forge.web.VersionETagCodec`.
837
+ dependencies: Dependencies of the route, as for ``APIRouter``.
838
+
839
+ Returns:
840
+ The router.
841
+ """
842
+ router = _router(dependencies)
843
+ item_model = create_model(
844
+ f"{model.__name__}BatchUpdateItem",
845
+ id=(str | int, ...),
846
+ patch=(dict[str, Any], ...),
847
+ if_match=(str | None, Field(default=None, alias="ifMatch")),
848
+ )
849
+ request_model = _list_model(
850
+ f"{model.__name__}BatchUpdateRequest", "requests", item_model
851
+ )
852
+ result_model = _list_model(
853
+ f"{response_model.__name__}BatchUpdateResponse", resource_name, response_model
854
+ )
855
+ etag_codec = codec or VersionETagCodec()
856
+
857
+ async def parse(request: Request) -> list[BatchUpdateItem]:
858
+ await _checked_list(request, "requests", max_rows)
859
+ parsed = parse_batch_update(
860
+ await request.json(), cap=max_rows, instance=request.url.path
861
+ )
862
+ assert not isinstance(parsed, ProblemResponse) # _checked_list ruled both out # noqa: S101 # type narrowing, not validation
863
+ return parsed
864
+
865
+ async def batch_update(
866
+ request: Request,
867
+ body: Any = Body(),
868
+ items: list[BatchUpdateItem] = Depends(parse),
869
+ target: BatchUpdateStore[T] = Depends(store),
870
+ ) -> Response | dict[str, Any]:
871
+ del body
872
+ found = await target.current([item.id for item in items])
873
+ for item in items:
874
+ if item.id not in found:
875
+ raise LookupError(f"{resource_label} {item.id} not found")
876
+ for item in items:
877
+ version = found[item.id].version
878
+ if version is not None:
879
+ check_item_precondition(
880
+ item,
881
+ current_version=version,
882
+ entity_id=item.id,
883
+ codec=etag_codec,
884
+ required=require_if_match,
885
+ )
886
+
887
+ documents: list[tuple[str, T]] = []
888
+ failures: list[dict[str, str]] = []
889
+ for item in items:
890
+ current = model.model_validate(
891
+ found[item.id].row, from_attributes=True
892
+ ).model_dump(by_alias=True, mode="json")
893
+ try:
894
+ documents.append(
895
+ (
896
+ item.id,
897
+ model.model_validate(merge_representation(current, item.patch)),
898
+ )
899
+ )
900
+ except ValidationError as exc:
901
+ failures.extend(
902
+ field_error(
903
+ ("requests", item.index, "patch", *err["loc"]),
904
+ _error_message(err),
905
+ )
906
+ for err in exc.errors()
907
+ )
908
+ if failures:
909
+ return problem_response(
910
+ render_problem(
911
+ default_registry(),
912
+ ValueError("Validation Error"),
913
+ instance=request.url.path,
914
+ problem=VALIDATION_ERROR,
915
+ detail="One or more rows are invalid.",
916
+ extensions={"errors": failures},
917
+ )
918
+ )
919
+
920
+ updated = await target.update_many(documents)
921
+ return {resource_name: [_dump(response_model, row) for row in updated]}
922
+
923
+ batch_update.__annotations__["body"] = request_model
924
+ router.add_api_route(
925
+ f"{collection}:batchUpdate",
926
+ batch_update,
927
+ methods=["POST"],
928
+ response_model=result_model,
929
+ )
930
+ return router
931
+
932
+
933
+ def _dump(model: type[BaseModel], row: object) -> dict[str, Any]:
934
+ return model.model_validate(row, from_attributes=True).model_dump(
935
+ by_alias=True, mode="json"
936
+ )