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 |
required |
cap
|
int | None
|
The most ids a request may name, or |
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 |
required |
format_param
|
str | None
|
The |
required |
allowed
|
Iterable[str]
|
The extensions (keys of :data: |
required |
Returns:
| Type | Description |
|---|---|
TabularFormat | None
|
The format, or |
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 |
required |
instance
|
str
|
The |
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 |
list[BatchUpdateItem] | ProblemResponse
|
is missing, empty or not a list (422 at |
list[BatchUpdateItem] | ProblemResponse
|
(:func: |
Raises:
| Type | Description |
|---|---|
RowsInvalid
|
An item has no |
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']
|
|
required |
cap
|
int
|
The row limit. |
required |
instance
|
str
|
The |
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 |
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.'