Skip to content

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 True, a versioned item without ifMatch is a 428.

etag_codec ETagCodec | None

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

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 import_export.resources.Resource subclass.

export_formats tuple[str, ...]

Extensions offered; keys of :data:rn_forge.web.TABULAR_FORMATS.

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_export.resources.Resource subclass.

import_formats tuple[str, ...]

Extensions accepted for upload and offered for the template.

import_rollback_on_validation_errors bool

False commits the valid rows and answers 200 with the failures listed under errors.

get_import_resource()

Return the resource instance that performs the import.