Skip to content

Transfer

rn_forge.web.transfer

Wire shapes for tabular export, import and bulk operations.

DUPLICATE_ID_DETAIL = 'Duplicate id in batch.' module-attribute

The detail for a repeated id in a :batchUpdate request.

NON_EMPTY_IDS_DETAIL = 'A non-empty ids parameter is required.' module-attribute

The detail for a :batchGet request with no usable ids value.

NON_EMPTY_LIST_DETAIL = 'A non-empty list is required.' module-attribute

The detail for a bulk member that is an empty list or not a list.

TABULAR_FORMATS = {(fmt.extension): fmt for fmt in (TabularFormat('text/csv', 'csv', 'csv'), TabularFormat('text/tab-separated-values', 'tsv', 'tsv'), TabularFormat('application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'xlsx', 'xlsx'), TabularFormat('application/vnd.oasis.opendocument.spreadsheet', 'ods', 'ods'))} module-attribute

The tabular formats, keyed by file extension (which is also the ?format= value).

BatchUpdateItem(index, id, patch, if_match) dataclass

One validated :batchUpdate item.

index is the item's position in requests, patch its JSON Merge Patch and if_match its ifMatch precondition, if any.

ImportCounts(created, updated, skipped) dataclass

What an import did: rows created, rows updated and rows skipped.

RowError(row, field, message) dataclass

One failed cell: the row's index, the column (or field), and the message.

An empty field points at the whole row.

TabularFormat(media_type, extension, tablib_name) dataclass

One tabular file format: its media type, extension and codec name.

batch_get_ids(values, *, cap)

Return the ids of a :batchGet request, from its repeated ids values.

Empty values are dropped; a value is never split, so a comma-joined value is one id.

Parameters:

Name Type Description Default
values Iterable[str]

The raw values of the repeated ids query parameter.

required
cap int | None

The most ids a request may name, or None for no limit.

required

Raises:

Type Description
InvalidBatchGet

No value is non-empty, or there are more than cap ids.

content_disposition(filename)

Return an attachment Content-Disposition value for filename.

Carries both the RFC 6266 quoted filename (non-ASCII and control characters replaced by _, path separators dropped) and the RFC 8187 filename* in UTF-8, which clients that understand it prefer.

Example::

content_disposition("Orders 2026.csv")
# 'attachment; filename="Orders 2026.csv"; filename*=UTF-8\'\'Orders%202026.csv'

export_cap_problem(cap, *, instance, registry=None)

Render "the export exceeds cap rows" as a 422 problem naming the cap.

import_report_body(*, created, updated, skipped, validate_only)

Return the body of a successful import: counts, and whether nothing was persisted.

negotiate_tabular_format(accept, format_param, allowed)

Choose the tabular format a GET should be answered in, if any.

format_param wins over accept, as a link cannot set headers. Otherwise the allowed format with the highest q in accept is chosen, but only when it beats every explicitly listed non-tabular range; wildcards never select a tabular format, so a client that did not ask for one gets the JSON representation.

Parameters:

Name Type Description Default
accept str | None

The Accept header value.

required
format_param str | None

The format query parameter value.

required
allowed Iterable[str]

The extensions (keys of :data:TABULAR_FORMATS) the endpoint offers.

required

Returns:

Type Description
TabularFormat | None

The format, or None when the response should not be tabular,

TabularFormat | None

including when format_param names a format that is not allowed.

parse_batch_update(body, *, cap, instance, registry=None)

Check a :batchUpdate body's list, its size, each item's shape and the ids.

Parameters:

Name Type Description Default
body object

The decoded JSON request body.

required
cap int | None

The most items a request may carry, or None for no limit.

required
instance str

The instance member, in practice the request path.

required
registry ProblemRegistry | None

The registry to render with; the default when omitted.

None

Returns:

Type Description
list[BatchUpdateItem] | ProblemResponse

The items in request order, or the problem to render when requests

list[BatchUpdateItem] | ProblemResponse

is missing, empty or not a list (422 at /requests) or over cap

list[BatchUpdateItem] | ProblemResponse

(:func:row_cap_problem).

Raises:

Type Description
RowsInvalid

An item has no id, a patch that is not a JSON object or an ifMatch that is not a string, or repeats an earlier item's id. Every failing item is reported, with root requests.

parse_flag(value)

Return whether value is "true" or "1", ignoring case.

Anything else, including None, is False. It parses the validateOnly and prefill query parameters.

row_cap_problem(kind, cap, *, instance, registry=None)

Render "the kind exceeds cap rows" as a 422 problem with no errors member.

Parameters:

Name Type Description Default
kind Literal['import', 'batch']

"import" or "batch".

required
cap int

The row limit.

required
instance str

The instance member, in practice the request path.

required
registry ProblemRegistry | None

The registry to render with; the default when omitted.

None

row_errors_problem(errors, *, instance, root='rows', registry=None)

Render row errors as a 422 application/problem+json response.

Each error becomes an errors entry whose pointer is /<root>/<row>/<field>, e.g. /rows/12/Quantity for an import and /requests/3/name for a batch create (root="requests").

Parameters:

Name Type Description Default
errors Iterable[RowError]

The failed cells.

required
instance str

The instance member, in practice the request path.

required
root str

The first pointer segment.

'rows'
registry ProblemRegistry | None

The registry to render with; the default when omitted.

None

unreadable_file_detail(extension)

Return the detail for an upload that could not be parsed as extension.

unsupported_file_detail(formats)

Return the detail for an upload whose type is not in formats.

Example::

unsupported_file_detail(("csv", "xlsx"))
# 'Unsupported file type; use one of: csv, xlsx.'