Skip to content

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 root="requests", raised before anything is written.

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 /orders.

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:BatchCreateStore.

required
max_rows int | None

The most items a batch may hold; None for no limit.

None
dependencies Sequence[Depends]

Dependencies of the route, as for APIRouter.

()

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 /orders.

required
resource_label str

The resource's name in the 404 detail, for example Order.

required
store Callable[..., BatchDeleteStore]

A dependency returning the :class:BatchDeleteStore.

required
max_rows int | None

The most ids a batch may hold; None for no limit.

None
dependencies Sequence[Depends]

Dependencies of the route, as for APIRouter.

()

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 /orders.

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 Order.

required
store Callable[..., BatchGetStore]

A dependency returning the :class:BatchGetStore.

required
max_rows int | None

The most ids a batch may hold; None for no limit.

None
read_mask bool

Whether the route accepts readMask.

True
dependencies Sequence[Depends]

Dependencies of the route, as for APIRouter.

()

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 /orders.

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 Order.

required
store Callable[..., BatchUpdateStore[T]]

A dependency returning the :class:BatchUpdateStore.

required
max_rows int | None

The most items a batch may hold; None for no limit.

None
require_if_match bool

When True, a versioned item without ifMatch is a 428.

False
codec ETagCodec | None

The validator format; None uses :class:rn_forge.web.VersionETagCodec.

None
dependencies Sequence[Depends]

Dependencies of the route, as for APIRouter.

()

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 /orders.

required
model type[T]

The row model.

required
store Callable[..., ImportStore[T]]

A dependency returning the :class:ImportStore.

required
formats Sequence[str]

The accepted file extensions.

('csv', 'xlsx')
max_rows int | None

The most data rows an import may hold; None for no limit.

None
dependencies Sequence[Depends]

Dependencies of the route, as for APIRouter.

()

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 /orders.

required
model type[T]

The import model.

required
source Callable[..., TemplateSource]

A dependency returning the :class:TemplateSource.

required
formats Sequence[str]

The offered file extensions.

('csv', 'xlsx')
max_rows int | None

The most rows a prefilled template may hold; None for no limit.

None
dependencies Sequence[Depends]

Dependencies of the route, as for APIRouter.

()

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:~rn_forge.web.transfer.unsupported_file_detail as its message, or its content cannot be parsed, with :func:~rn_forge.web.transfer.unreadable_file_detail.

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:tabular_response.

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 for no limit.

None
instance str

The instance of the problem, in practice the request path.

required

Returns:

Type Description
Response

A 422 problem when len(rows) > max_rows, otherwise

Response

func:tabular_response's response.

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 StreamingResponse for CSV, otherwise a Response.