Transfer
rn_forge.fastapi.transfer
Tabular export and import, and batch get, create, update and delete, over FastAPI.
Requires the transfer extra. Not imported by :mod:rn_forge.fastapi.
Persistence is the application's: the route factories take a store dependency
that implements one of the store protocols, and :func:read_rows validates
without saving.
BatchCreateStore
Bases: Protocol
Persists a batch of new resources.
create_many(items)
async
Create every item in one transaction and return the created objects.
Raises:
| Type | Description |
|---|---|
ItemsDenied
|
An item is not permitted, raised before anything is written. |
BatchDeleteStore
Bases: Protocol
Finds and deletes a batch of resources.
delete_many(ids)
async
Delete every id in one transaction.
Raises:
| Type | Description |
|---|---|
ItemsDenied
|
An id may not be deleted, raised before anything is deleted. |
find(ids)
async
Return which of ids exist within the caller's scope.
BatchGetStore
Bases: Protocol
Finds a batch of resources.
get_many(ids)
async
Return the rows of ids that exist within the caller's scope, keyed by id as a string.
BatchUpdateStore
Bases: Protocol
Finds and updates a batch of resources.
current(ids)
async
Return each of ids that exists within the caller's scope, keyed by id as a string.
update_many(items)
async
Write every validated document in one transaction and return the updated rows.
Bumps each versioned row's version. The rows are returned in the order of items.
Raises:
| Type | Description |
|---|---|
ItemsDenied
|
An item is not permitted, with |
Current
Bases: Protocol
A row as :class:BatchUpdateStore reports it: the row, and its version if it has one.
row
property
The stored row.
version
property
The row's version, or None when the resource is unversioned.
ImportStore
Bases: Protocol
Persists the rows of an import.
import_rows(rows, *, validate_only)
async
Upsert every row in one transaction, rolling back when validate_only.
Raises:
| Type | Description |
|---|---|
RowsInvalid
|
A row fails a check only the store can make. |
RowsResult(valid=list[T](), errors=list[RowError](), total=0)
dataclass
The outcome of :func:read_rows: the valid rows and every failed cell.
TemplateSource
Bases: Protocol
Supplies the rows that prefill an import template.
rows()
async
Return the current filtered rows; called only when prefill is set.
batch_create_router(collection, *, model, response_model, resource_name, store, max_rows=None, dependencies=())
Build POST {collection}:batchCreate, taking {"requests": [...]}.
Every item is validated into model and every failure is reported, as a
422 problem pointing at /requests/<i>/<field>, and the store is not called. The response is 200 with
the created objects, as response_model dumped by alias, under
resource_name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
collection
|
str
|
The collection path, for example |
required |
model
|
type[T]
|
The create model of one item. |
required |
response_model
|
type[BaseModel]
|
The model of one created resource. |
required |
resource_name
|
str
|
The response member that holds the created resources. |
required |
store
|
Callable[..., BatchCreateStore[T]]
|
A dependency returning the :class: |
required |
max_rows
|
int | None
|
The most items a batch may hold; |
None
|
dependencies
|
Sequence[Depends]
|
Dependencies of the route, as for |
()
|
Returns:
| Type | Description |
|---|---|
APIRouter
|
The router. |
batch_delete_router(collection, *, resource_label, store, max_rows=None, dependencies=())
Build POST {collection}:batchDelete, taking {"ids": [...]}.
Ids may be strings or integers and are compared as strings. The first id
that :meth:BatchDeleteStore.find does not return is a 404 reading
{resource_label} {id} not found. The response is 204.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
collection
|
str
|
The collection path, for example |
required |
resource_label
|
str
|
The resource's name in the 404 detail, for example |
required |
store
|
Callable[..., BatchDeleteStore]
|
A dependency returning the :class: |
required |
max_rows
|
int | None
|
The most ids a batch may hold; |
None
|
dependencies
|
Sequence[Depends]
|
Dependencies of the route, as for |
()
|
Returns:
| Type | Description |
|---|---|
APIRouter
|
The router. |
batch_get_router(collection, *, response_model, resource_name, resource_label, store, max_rows=None, read_mask=True, dependencies=())
Build GET {collection}:batchGet, taking a repeated ids query parameter.
A missing ids parameter, or more ids than max_rows, is a 400 problem.
The first id that :meth:BatchGetStore.get_many does not return is a 404
reading {resource_label} {id} not found. The response is 200 with one
entry per requested id, in request order and repeating duplicates, as
response_model dumped by alias, under resource_name. With read_mask,
the route also takes readMask (see :func:rn_forge.fastapi.read_mask_param)
and each resource holds only the fields it names.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
collection
|
str
|
The collection path, for example |
required |
response_model
|
type[BaseModel]
|
The model of one resource. |
required |
resource_name
|
str
|
The response member that holds the resources. |
required |
resource_label
|
str
|
The resource's name in the 404 detail, for example |
required |
store
|
Callable[..., BatchGetStore]
|
A dependency returning the :class: |
required |
max_rows
|
int | None
|
The most ids a batch may hold; |
None
|
read_mask
|
bool
|
Whether the route accepts |
True
|
dependencies
|
Sequence[Depends]
|
Dependencies of the route, as for |
()
|
Returns:
| Type | Description |
|---|---|
APIRouter
|
The router. |
batch_update_router(collection, *, model, response_model, resource_name, resource_label, store, max_rows=None, require_if_match=False, codec=None, dependencies=())
Build POST {collection}:batchUpdate, taking {"requests": [...]}.
Each item is {"id", "patch", "ifMatch"}: patch is a JSON Merge Patch
and ifMatch an optional precondition. The current row is dumped through
model by alias, merged with the patch and validated as model. The first
failing step answers: the list and item shape are 422 problems, a missing
id is a 404 reading {resource_label} {id} not found, a failed
precondition is a 428, 400 or 412 pointing at /requests/<i>/ifMatch,
and an invalid merged document is a 422 problem pointing at
/requests/<i>/patch/<field>. The store is not asked to write after a
failure. Ids may be strings or integers and are compared as strings. The
response is 200 with the updated rows, as response_model dumped by alias,
under resource_name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
collection
|
str
|
The collection path, for example |
required |
model
|
type[T]
|
The model of one full resource document. |
required |
response_model
|
type[BaseModel]
|
The model of one updated resource. |
required |
resource_name
|
str
|
The response member that holds the updated resources. |
required |
resource_label
|
str
|
The resource's name in the 404 detail, for example |
required |
store
|
Callable[..., BatchUpdateStore[T]]
|
A dependency returning the :class: |
required |
max_rows
|
int | None
|
The most items a batch may hold; |
None
|
require_if_match
|
bool
|
When |
False
|
codec
|
ETagCodec | None
|
The validator format; |
None
|
dependencies
|
Sequence[Depends]
|
Dependencies of the route, as for |
()
|
Returns:
| Type | Description |
|---|---|
APIRouter
|
The router. |
import_router(collection, *, model, store, formats=('csv', 'xlsx'), max_rows=None, dependencies=())
Build POST {collection}:import, a multipart upload of a file part.
Each row is validated into model, whose aliases are the column headers.
Any failed row answers a 422 problem and nothing reaches the store. The
validateOnly query parameter is parsed by
:func:~rn_forge.web.transfer.parse_flag. The response is 200 with
:func:~rn_forge.web.transfer.import_report_body.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
collection
|
str
|
The collection path, for example |
required |
model
|
type[T]
|
The row model. |
required |
store
|
Callable[..., ImportStore[T]]
|
A dependency returning the :class: |
required |
formats
|
Sequence[str]
|
The accepted file extensions. |
('csv', 'xlsx')
|
max_rows
|
int | None
|
The most data rows an import may hold; |
None
|
dependencies
|
Sequence[Depends]
|
Dependencies of the route, as for |
()
|
Returns:
| Type | Description |
|---|---|
APIRouter
|
The router. |
import_template_router(collection, *, model, source, formats=('csv', 'xlsx'), max_rows=None, dependencies=())
Build GET {collection}:importTemplate, the import columns as a file.
The format is negotiated as for :func:tabular_format, else the first of
formats. The columns are model's aliases, so the file round-trips
through :func:import_router. Without prefill the file holds the
header row only; with it, the rows of :class:TemplateSource. The download
is named import-template.<ext>.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
collection
|
str
|
The collection path, for example |
required |
model
|
type[T]
|
The import model. |
required |
source
|
Callable[..., TemplateSource]
|
A dependency returning the :class: |
required |
formats
|
Sequence[str]
|
The offered file extensions. |
('csv', 'xlsx')
|
max_rows
|
int | None
|
The most rows a prefilled template may hold; |
None
|
dependencies
|
Sequence[Depends]
|
Dependencies of the route, as for |
()
|
Returns:
| Type | Description |
|---|---|
APIRouter
|
The router. |
problem_response(problem)
Send a rendered problem, such as row_errors_problem(...), as a response.
read_rows(upload, model, *, formats=_READABLE)
async
Load upload with tablib and validate each row against model.
The format comes from the file extension, else from the part's content
type, among formats. Row indexes
are zero-based positions after the header row. An error's field is the
column header (the model's alias); a validator that raises ValueError
reports its own message. total is the number of data rows read.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
upload
|
UploadFile
|
The uploaded file. |
required |
model
|
type[T]
|
The row model. |
required |
formats
|
Sequence[str]
|
The accepted extensions, a subset of csv, tsv and xlsx. |
_READABLE
|
Raises:
| Type | Description |
|---|---|
ValueError
|
The file's type is not in formats, with
:func: |
tabular_export(rows, model, fmt, filename, *, max_rows=None, instance)
async
Answer an export request: rows as a download, or the cap problem.
Call it from a list route once :func:tabular_format yielded a format.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rows
|
Sequence[Any]
|
The rows to export, as for :func: |
required |
model
|
type[BaseModel]
|
The export model. |
required |
fmt
|
TabularFormat
|
The chosen format. |
required |
filename
|
str
|
The download name, extension included. |
required |
max_rows
|
int | None
|
The most rows an export may hold; |
None
|
instance
|
str
|
The |
required |
Returns:
| Type | Description |
|---|---|
Response
|
A 422 problem when |
Response
|
func: |
tabular_format(allowed=('csv', 'xlsx'))
Return a dependency yielding the tabular format the request asks for.
The format query parameter wins over Accept; see
:func:rn_forge.web.transfer.negotiate_tabular_format. The dependency
yields None when the response should be the endpoint's JSON.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
allowed
|
Iterable[str]
|
The extensions the endpoint offers. |
('csv', 'xlsx')
|
tabular_response(rows, model, fmt, filename)
async
Render rows as a file download in fmt.
Each row is validated into model with from_attributes=True and
dumped by alias, so the model's serialization aliases are the column
headers and its computed fields are columns. Use serialization_alias
for a header that differs from the attribute name: a plain alias would
also rename the attribute read from an ORM object. CSV is streamed in
chunks of 1,000 rows; the other
formats are built in memory in a worker thread.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rows
|
Iterable[Any]
|
ORM objects, mappings or model instances. |
required |
model
|
type[BaseModel]
|
The export model. |
required |
fmt
|
TabularFormat
|
The chosen format. |
required |
filename
|
str
|
The download name, extension included. |
required |
Returns:
| Type | Description |
|---|---|
Response
|
A |