Changelog¶
Unreleased¶
0.2.0 - 2026-11-15¶
Changed - what leaves the server is not what it was:
- A cursor is signed with the project's
SECRET_KEY, and carries the order it was made for. One changed by hand, made for another order, or signed with another key is400 invalid_cursorbefore the database is asked. The cursors given by 0.1.0 are refused: a client reads the feed again from the start.SECRET_KEY_FALLBACKSkeeps cursors working across a key change. A cursor is signed, not encrypted - the documents now say so. - Every 5xx is logged and reported - a designed one too: an
APIExceptionraised with a status of 500 or more,ServiceUnavailableError. It still says the message it was raised with. - A 205 is left as the view gave it: it has no body to put the envelope
in.
success_response(status_code=205)is refused.
Fixed:
-
A bug while a feed is read is a bug again. Telling a cursor the server cannot use from a broken row had meant answering every
ValueError,TypeErroror database error while a page was read asinvalid_cursor- which hid the project's own bugs, unlogged, on every page after the first. A signed cursor is refused before the query, so nothing is caught around it. -
A cursor that decodes and still cannot be used is a 400
invalid_cursor, as the contract says of every cursor the server cannot read. One written by hand, or kept while the list was re-sorted by another column, was a 500 - logged and reported as a bug - or avalidation_error. - A view cached with
cache_pageon its method is cached again. Wrapping the answer left the cache waiting for a response that was never rendered, so every request reached the view. error_responsemarks the request's transaction for rollback, as a raised failure does. UnderATOMIC_REQUESTS, what a view wrote before it returned a failure was kept.- What a model's
clean()refuses is undernon_field_errors, not under Django's own key,__all__. - A failure raised with the code
invalidkeeps it. Only a validation error is avalidation_error; a refusal that carriedinvalidwas sent as one, with nodata.fields. - A failure whose class names no code answers in the envelope, with DRF's
own code,
error, rather than as Django's 500. - A ceiling that is not above zero is no ceiling to choose under. A view
with
max_page_size = 0answered the whole list, unpaged, to a client that sent apage_size; it now answers its own page size. - A type a view names with
Response(content_type=...)is kept when the answer is wrapped. PAGE_SIZE_QUERY_PARAMset topageorcursoris reported at start-up (drf_parcel.E011): the paginators read those themselves.- The example's
restockvalidates the quantity it is sent, and the guide to database constraints says when PostgreSQL checks a foreign key. - The contract says that
OPTIONSis in the envelope, that a view's ownpage_sizehas no ceiling, and that aDictFieldkey holding the path separator makes an ambiguous path.
0.1.0 - 2026-11-14 - the first release¶
Everything the contract says, built.
- The envelope -
success,status_code,messageanddataon every answer;paginationon a paged list;error_codeon a failure. Built in one place, which refuses to build it wrong. - A success says what happened - Created, Saved, Deleted or Done, read off the request, and replaced per answer, per view or for the project.
EnvelopeMixinwraps a view's successes once. A delete answers 200 with the envelope. What is not JSON, and a view that opts out, is left alone.- Pagination by page number or by cursor, chosen per view. A client
chooses the page size only where a view allows it, always under a ceiling.
DRF's own
PAGE_SIZEis kept when the library is not told one. - The exception handler answers every failure in the envelope:
validation errors with every field's problem and its code at a flat path;
DRF's and Django's failures with a standard code and their headers; a
project's own
APIExceptionunchanged; a constraint the database refuses by its kind, when turned on; and a bug with a generic 500 whose text never leaves the server - logged, reported, and raised underDEBUG. Every failure undoes the request's write. DomainError- DRF'sAPIExceptionwithdata- and the common errors.- The schema with drf-spectacular: every success, page and failure as the client receives it.
- The
DRF_PARCELsetting refuses a key it does not know, andmanage.py checkreports a value that cannot work. - Persian, for every sentence the library says.
Found by a review before the release, and fixed:
success_response(status_code=204)answers 200 with its body, as every other 204 does - a 204 carries none, and the client read nothing.- Django's
PermissionDeniedkeeps the sentence it was raised with, as DRF's own handler does. - A view with
parcel_wrap = Falseis answered as DRF answers - its pages too, which were still in the envelope. - An
ERROR_CODESthat cannot work never breaks the answer to a failure. - The schema recognises a project's own handler built on the library's, and no longer fails when drf-spectacular names a page outside an operation.
Python 3.11 to 3.14; Django 5.2, 6.0 and 6.1; Django REST framework 3.16 and later; drf-spectacular 0.28 and later.