Skip to content

Responses

responses

Answering in the envelope.

success_response and error_response answer one request explicitly. EnvelopeMixin wraps whatever a view returns, once, in finalize_response - so no handler, list, create or a custom @action, has to remember.

What is never wrapped: a response that is not JSON (a file, a stream, a redirect, a page rendered by another renderer), a view that opts out with parcel_wrap = False, and a response already in the envelope.

EnvelopeResponse

Bases: Response

A response whose data is already the envelope.

Its class is what says so - not the keys in its data, which a view's own payload could happen to share.

EnvelopeMixin

Bases: _ViewBase

Wraps what a view answers in the envelope.

envelope_messages names a view's own message for each action - or, on a plain APIView, for each method:

envelope_messages = {'create': _('The product was added.')}
envelope_messages = {'post': _('Signed in.')}

envelope_message

envelope_message(request: Request, status_code: int) -> object

The message a success of this view says, when the answer chose none.

success_response

success_response(data: Any = None, *, message: object = None, status_code: int = status.HTTP_200_OK, pagination: Mapping[str, Any] | None = None, headers: Mapping[str, str] | None = None) -> EnvelopeResponse

A success, in the envelope.

Without a message it says the default for its status - and, in a view with EnvelopeMixin, the default for its request, which also knows the method.

A 204 carries no body by definition, so the envelope would be thrown away: it is answered as a 200, which a client can read. A 205 tells the client to clear its form and has no body either, and no 200 means that: it is refused - answer Response(status=205).

error_response

error_response(*, message: object, error_code: str, status_code: int = status.HTTP_400_BAD_REQUEST, data: Any = None, headers: Mapping[str, str] | None = None) -> EnvelopeResponse

A failure, in the envelope.

It marks the request's transaction for rollback, as raising does: under ATOMIC_REQUESTS, what a view wrote before it answered a failure is undone, whether the failure was raised or returned. It is for answering a request: made inside a task's own atomic block, in a project with ATOMIC_REQUESTS, it would mark that block for rollback too.