Transfer
Requires the transfer extra; see the
Transfer guide.
rn_forge.django.drf.transfer
Tabular export and import, and batch get, create, update and delete, for DRF viewsets.
Requires the transfer extra. Not re-exported by :mod:rn_forge.django.drf.
Register the viewset with :class:~rn_forge.django.drf.routers.CustomMethodRouter
so the actions are served as /orders:import and /orders:batchCreate.
BatchCreateMixin
Bases: _BatchResourceMixin
Add POST :batchCreate: {"requests": [...]}, all or nothing.
Each item goes through the view's serializer. The response is 200 with
the created resources under the plural resource name. A validation failure
is a 422 problem with errors[].pointer = "/requests/<i>/<field>"; an
error string from :meth:validate_batch_create_item is a 403 problem
pointing at the item. Nothing is persisted on failure.
Attributes:
| Name | Type | Description |
|---|---|---|
batch_resource_name |
str | None
|
The response key; the model's plural verbose name in camelCase when unset. |
prepare_batch_create_item(item)
Return one request item before serializer validation.
validate_batch_create_item(item)
Return an error message for one validated item, or None when allowed.
BatchDeleteMixin
Bases: GenericAPIView
Add POST :batchDelete: {"ids": [...]}, all or nothing, 204.
Ids are matched within filter_queryset(get_queryset()); an id outside it
is a 404 problem naming the id. An error string from
:meth:validate_batch_delete_instance is a 403 problem pointing at the id.
Each instance is deleted through the view's perform_destroy.
validate_batch_delete_instance(instance)
Return an error message for one delete target, or None when allowed.
BatchGetMixin
Bases: _BatchResourceMixin
Add GET :batchGet?ids=1&ids=2.
Ids are matched within filter_queryset(get_queryset()) and serialized
with the view's serializer. The response is 200 with the resources
under the plural resource name, one per requested id in request order. A
missing ids parameter, or more ids than transfer.max_rows, is a 400
problem; an id outside the view's scope is a 404 problem naming the id.
Django's DATA_UPLOAD_MAX_NUMBER_FIELDS (1,000 by default) also bounds
ids, and more is a 400 problem.
Attributes:
| Name | Type | Description |
|---|---|---|
batch_resource_name |
str | None
|
The response key; the model's plural verbose name in camelCase when unset. |
BatchUpdateMixin
Bases: _BatchResourceMixin
Add POST :batchUpdate: {"requests": [{"id", "patch", "ifMatch"}]}, all or nothing.
Each item's patch is an RFC 7396 JSON Merge Patch, merged into the
row's current representation and validated through the view's serializer
as a full update. ifMatch is the item's precondition, checked when the
row is a :class:~rn_forge.django.models.VersionedModelMixin. The response
is 200 with the updated resources under the plural resource name, in
request order.
A malformed list or item is a 422 problem, an id outside
filter_queryset(get_queryset()) a 404, a failed precondition a 428, 400
or 412 pointing at /requests/<i>/ifMatch (a version conflict at save time
included), a failed merged document a 422 pointing at
/requests/<i>/patch/<field>, and an error string from
:meth:validate_batch_update_item a 403 pointing at the item. Nothing is
persisted on failure.
Attributes:
| Name | Type | Description |
|---|---|---|
batch_resource_name |
str | None
|
The response key; the model's plural verbose name in camelCase when unset. |
batch_update_requires_if_match |
bool
|
When |
etag_codec |
ETagCodec | None
|
The validator format; |
validate_batch_update_item(instance, data)
Return an error message for one validated update, or None when allowed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
instance
|
Any
|
The row before the update. |
required |
data
|
dict[str, Any]
|
The item's validated data. |
required |
ResourceExportMixin
Bases: ListModelMixin, GenericAPIView
Answer list as CSV or XLSX when the client asks for it.
Accept: text/csv, or ?format=csv, runs
filter_queryset() then export_resource_class().export(). The result
is not paginated. More rows than transfer.max_rows is a 422 problem
naming the cap. Without a tabular Accept the JSON list is unchanged.
Forward foreign-key and one-to-one paths the resource reads are joined with
select_related.
Attributes:
| Name | Type | Description |
|---|---|---|
export_resource_class |
type[Any] | None
|
An |
export_formats |
tuple[str, ...]
|
Extensions offered; keys of
:data: |
export_filename |
str | None
|
The download name without extension; the router basename when unset. |
export_column_formats |
Mapping[str, str]
|
Excel number format per header, for XLSX. |
get_export_resource()
Return the resource instance that builds the export.
ResourceImportMixin
Bases: GenericAPIView
Add POST :import and GET :importTemplate.
:import takes a multipart/form-data file part (CSV, TSV, XLSX or
ODS, by extension) and upserts through import_resource_class. The
request user is passed to the resource as the user keyword, so
before_import_row can set audit fields and authorize each row. The
response is 200 with {created, updated, skipped, validateOnly};
with ?validateOnly=true nothing is persisted. Any row error is a 422
problem with errors[].pointer = "/rows/<row>/<column>" and nothing
persisted.
:importTemplate returns the import columns as an empty file,
negotiated like an export; ?prefill=true adds the current filtered rows.
Attributes:
| Name | Type | Description |
|---|---|---|
import_resource_class |
type[Any] | None
|
An |
import_formats |
tuple[str, ...]
|
Extensions accepted for upload and offered for the template. |
import_rollback_on_validation_errors |
bool
|
|
get_import_resource()
Return the resource instance that performs the import.