drf-parcel 0.1.0__tar.gz

drf_parcel-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+
+# Packaging
+build/
+dist/
+*.egg-info/
+
+# Environments
+.venv/
+.nox/
+
+# Tool caches and reports
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Editors
+.idea/
+.vscode/
+
+# The example project's database
+example/db.sqlite3
+
+# The documentation site
+site/

drf_parcel-0.1.0/CHANGELOG.fa.md

@@ -0,0 +1,49 @@
+# تغییرات
+
+[English](CHANGELOG.md)
+
+## منتشرنشده
+
+## 0.1.0 - ۱۴۰۵/۰۸/۲۳ - اولین نسخه
+
+همه‌ی آنچه [قرارداد](https://github.com/amirAI-dot/drf-parcel/blob/main/docs/contract.fa.md) می‌گوید، ساخته شده.
+
+* **قالب پاسخ** - `success`، `status_code`، `message` و `data` روی هر پاسخ؛
+  `pagination` روی لیست صفحه‌بندی‌شده؛ `error_code` روی خطا. در یک جا ساخته
+  می‌شود، که ساختن قالب غلط را رد می‌کند.
+* **پاسخ موفق می‌گوید چه شد** - Created، Saved، Deleted یا Done، از روی خود
+  درخواست، و برای یک پاسخ، یک view یا کل پروژه قابل تغییر.
+* **`EnvelopeMixin`** پاسخ‌های موفق view را یک بار در قالب می‌گذارد. حذف با
+  200 همراه با قالب جواب می‌دهد. چیزی که JSON نیست، و viewی که بیرون می‌ماند،
+  دست نمی‌خورد.
+* **صفحه‌بندی** شماره‌ای یا با cursor، که هر view خودش انتخاب می‌کند. کلاینت
+  فقط جایی تعداد هر صفحه را انتخاب می‌کند که view اجازه بدهد، و همیشه زیر سقف.
+  `PAGE_SIZE` خود DRF وقتی کتابخانه عددی نگرفته حفظ می‌شود.
+* **exception handler** هر خطایی را در قالب جواب می‌دهد: خطای اعتبارسنجی با
+  مشکل هر فیلد و کدش در یک مسیر تخت؛ خطاهای DRF و Django با کد استاندارد و
+  هدرهایشان؛ `APIException` خود پروژه بدون تغییر؛ قیدی که دیتابیس رد می‌کند بر
+  اساس نوعش، وقتی روشن باشد؛ و یک باگ با 500 عمومی که متنش هرگز از سرور بیرون
+  نمی‌رود - لاگ می‌شود، گزارش می‌شود، و در `DEBUG` بالا می‌رود. هر خطا نوشتن
+  درخواست را برمی‌گرداند.
+* **`DomainError`** - همان `APIException` خود DRF با `data` - و خطاهای رایج.
+* **اسکیما** با drf-spectacular: هر پاسخ موفق، صفحه و خطا همان‌طور که به
+  کلاینت می‌رسد.
+* **تنظیم `DRF_PARCEL`** کلیدی را که نمی‌شناسد رد می‌کند، و `manage.py check`
+  مقداری را که کار نمی‌کند گزارش می‌دهد.
+* **فارسی**، برای هر جمله‌ای که کتابخانه می‌گوید.
+
+پیدا شده در یک بررسی پیش از انتشار، و درست شده:
+
+* `success_response(status_code=204)` با 200 و همراه بدنه‌اش جواب می‌دهد، مثل
+  هر 204 دیگری - 204 بدنه ندارد، و کلاینت چیزی نمی‌خواند.
+* `PermissionDenied` خود Django جمله‌ای را که با آن raise شده نگه می‌دارد،
+  همان‌طور که handler خود DRF نگه می‌دارد.
+* viewی که `parcel_wrap = False` دارد همان‌طور جواب داده می‌شود که DRF جواب
+  می‌دهد - صفحه‌هایش هم، که هنوز در قالب بودند.
+* `ERROR_CODES`ی که کار نمی‌کند هرگز پاسخ یک خطا را خراب نمی‌کند.
+* اسکیما handler خود پروژه را که روی handler کتابخانه ساخته شده می‌شناسد، و
+  دیگر وقتی drf-spectacular صفحه‌ای را بیرون از یک عملیات نام‌گذاری می‌کند خطا
+  نمی‌دهد.
+
+Python 3.11 تا 3.14؛ Django 5.2، 6.0 و 6.1؛ Django REST framework 3.16 و
+بالاتر؛ drf-spectacular 0.28 و بالاتر.

drf_parcel-0.1.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+[فارسی](CHANGELOG.fa.md)
+
+## Unreleased
+
+## 0.1.0 - 2026-11-14 - the first release
+
+Everything [the contract](https://github.com/amirAI-dot/drf-parcel/blob/main/docs/contract.md) says, built.
+
+* **The envelope** - `success`, `status_code`, `message` and `data` on every
+  answer; `pagination` on a paged list; `error_code` on 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.
+* **`EnvelopeMixin`** wraps 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_SIZE` is 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 `APIException` unchanged; 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 under `DEBUG`. Every
+  failure undoes the request's write.
+* **`DomainError`** - DRF's `APIException` with `data` - and the common errors.
+* **The schema** with drf-spectacular: every success, page and failure as the
+  client receives it.
+* **The `DRF_PARCEL` setting** refuses a key it does not know, and
+  `manage.py check` reports 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 `PermissionDenied` keeps the sentence it was raised with, as DRF's
+  own handler does.
+* A view with `parcel_wrap = False` is answered as DRF answers - its pages
+  too, which were still in the envelope.
+* An `ERROR_CODES` that 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.

drf_parcel-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, amir mohammad kashanchian
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

drf_parcel-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: drf-parcel
+Version: 0.1.0
+Summary: One response shape for a Django REST framework API - success, page and error alike.
+Project-URL: Documentation, https://amirai-dot.github.io/drf-parcel/
+Project-URL: Repository, https://github.com/amirAI-dot/drf-parcel
+Project-URL: Changelog, https://github.com/amirAI-dot/drf-parcel/blob/main/CHANGELOG.md
+Project-URL: Contract, https://github.com/amirAI-dot/drf-parcel/blob/main/docs/contract.md
+Author: amir mohammad kashanchian
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: api,django,djangorestframework,drf,envelope,errors,pagination,response
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: django>=5.2
+Requires-Dist: djangorestframework>=3.16
+Provides-Extra: schema
+Requires-Dist: drf-spectacular>=0.28; extra == 'schema'
+Description-Content-Type: text/markdown
+
+# drf-parcel
+
+One response shape for a Django REST framework API - success, page and error
+alike - and the generated schema saying exactly that shape.
+
+[فارسی](https://github.com/amirAI-dot/drf-parcel/blob/main/README.fa.md)
+
+```json
+{"success": true,  "status_code": 200, "message": "Done.",    "data": {"id": 7}}
+{"success": true,  "status_code": 200, "message": "Done.",    "data": [], "pagination": {"type": "page", "count": 45, "page": 2, "pages": 3, "page_size": 20, "has_next": true, "has_previous": true}}
+{"success": false, "status_code": 409, "message": "...",      "data": {"branches": 3}, "error_code": "province_in_use"}
+```
+
+A client reads one shape and never special-cases a payload: the answer is
+under `data`, a person reads `message`, and code branches on `error_code` -
+never on the message, which is translated.
+
+**[The documentation](https://amirai-dot.github.io/drf-parcel/)** - a
+quickstart, a tutorial, how-to guides, the reference - in English and
+Persian.
+
+## In a project
+
+```bash
+pip install 'drf-parcel[schema]'      # the schema extra brings drf-spectacular
+```
+
+```python
+INSTALLED_APPS = [
+    ...,
+    'rest_framework',
+    'drf_parcel',
+]
+
+REST_FRAMEWORK = {
+    'EXCEPTION_HANDLER': 'drf_parcel.handlers.exception_handler',
+    'DEFAULT_PAGINATION_CLASS': 'drf_parcel.pagination.PageNumberPagination',
+    'DEFAULT_SCHEMA_CLASS': 'drf_parcel.schema.ParcelAutoSchema',
+}
+```
+
+Each line is independent: the handler alone gives the error envelope and
+nothing else, and a project adopts the rest one view at a time.
+
+```python
+from drf_parcel.pagination import CursorPagination
+from drf_parcel.responses import EnvelopeMixin, success_response
+
+
+class ProductViewSet(EnvelopeMixin, ModelViewSet):
+    queryset = Product.objects.all()
+    serializer_class = ProductSerializer
+    page_size = 12
+    client_page_size = True          # the client may send ?page_size=
+    max_page_size = 48               # and never gets more
+    envelope_messages = {'create': _('The product was added.')}
+
+
+class NotificationViewSet(EnvelopeMixin, ModelViewSet):
+    pagination_class = CursorPagination
+    ordering = '-created_at'
+
+
+class TotalsView(EnvelopeMixin, APIView):
+    def get(self, request):
+        return success_response({'total': 12}, message=_('Totals.'))
+```
+
+`EnvelopeMixin` wraps what a view answers once, in `finalize_response`, so
+no action - `list`, `create`, a custom `@action` - has to remember. A delete
+answers 200 with the envelope rather than a 204 with nothing. A file, a
+stream, a redirect or a CSV is left alone, and so is a view with
+`parcel_wrap = False`.
+
+A shop that uses every part of it, to run and read, is in
+[`example/`](example/README.md).
+
+## Errors
+
+```python
+from drf_parcel.exceptions import DomainError
+
+
+class ProvinceInUse(DomainError):
+    status_code = 409
+    default_code = 'province_in_use'
+    default_detail = _('This province has branches and cannot be deleted.')
+
+
+raise ProvinceInUse(data={'branches': 3})
+```
+
+A `DomainError` is DRF's `APIException` with `data` added, so a project's
+existing errors answer in the envelope unchanged. The handler also:
+
+* says a validation error's first problem in `message` and every problem in
+  `data.fields`, each with its code at a flat path - `items.0.quantity`;
+* answers DRF's and Django's own failures with a standard code -
+  `not_authenticated`, `permission_denied`, `not_found`, `rate_limited` with
+  `retry_after` ... - and keeps the headers DRF puts on them;
+* answers anything unexpected with a generic 500 whose text never leaves the
+  server: it is logged with its traceback and handed to your `REPORTER`.
+  Under `DEBUG` it is raised, so Django's page shows it;
+* undoes the request's write behind every failure it answers.
+
+## Pagination
+
+Numbered pages or a cursor, chosen per view. `pagination.type` says which, so
+one component on a client reads either. A client chooses the page size only
+where a view allows it, and always under a ceiling.
+
+## The schema
+
+With `ParcelAutoSchema` - or `ParcelSchemaMixin` in your own `AutoSchema` -
+the OpenAPI document says what the wire carries: every success inside the
+envelope, each page as its own envelope, `page_size` only where it is
+accepted, and the error envelope as every operation's `default` answer.
+
+## Settings
+
+One dictionary, `DRF_PARCEL`. A key the library does not know stops the
+project at start-up rather than being ignored, and `manage.py check` reports
+a value that cannot work. Every key, every shape and every error code is in
+[the contract](docs/contract.md).
+
+## Languages
+
+Every sentence the library says is in the request's language. It ships
+Persian; DRF's own messages come in DRF's languages.
+
+## Supported
+
+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, for the schema.
+
+## Working on it
+
+Every check runs through [nox](https://nox.thea.codes), the same sessions
+locally and in CI.
+
+```bash
+uv tool install nox
+```
+
+```bash
+nox -s lint types tests
+```
+
+`tests` runs every supported Python and Django; `oldest` runs the oldest
+release of everything supported; `package` builds the wheel and checks what
+is in it. The suite runs on SQLite by default, and on PostgreSQL with
+`DRF_PARCEL_TEST_DATABASE=postgres` and the standard `PG*` variables.
+
+After changing a marked string, translate it in
+`src/drf_parcel/locale/fa/LC_MESSAGES/django.po` and compile it:
+
+```bash
+nox -s messages
+```
+
+## Licence
+
+BSD 3-Clause - see [`LICENSE`](LICENSE).

drf_parcel-0.1.0/README.fa.md

@@ -0,0 +1,163 @@
+# drf-parcel
+
+یک شکل پاسخ برای API ساخته‌شده با Django REST framework - برای پاسخ موفق،
+صفحه و خطا یکسان - و اسکیمایی که دقیقاً همان شکل را می‌گوید.
+
+[English](https://github.com/amirAI-dot/drf-parcel/blob/main/README.md)
+
+```json
+{"success": true,  "status_code": 200, "message": "Done.",    "data": {"id": 7}}
+{"success": true,  "status_code": 200, "message": "Done.",    "data": [], "pagination": {"type": "page", "count": 45, "page": 2, "pages": 3, "page_size": 20, "has_next": true, "has_previous": true}}
+{"success": false, "status_code": 409, "message": "...",      "data": {"branches": 3}, "error_code": "province_in_use"}
+```
+
+کلاینت فقط یک شکل را می‌خواند و هیچ پاسخی را جداگانه مدیریت نمی‌کند: جواب
+زیر `data` است، انسان `message` را می‌خواند، و کد بر اساس `error_code` تصمیم
+می‌گیرد - هرگز بر اساس پیام، که ترجمه می‌شود.
+
+**[مستندات](https://amirai-dot.github.io/drf-parcel/fa/)** - شروع سریع، آموزش،
+راهنماهای کاربردی، مرجع - به انگلیسی و فارسی.
+
+## در یک پروژه
+
+```bash
+pip install 'drf-parcel[schema]'      # the schema extra brings drf-spectacular
+```
+
+```python
+INSTALLED_APPS = [
+    ...,
+    'rest_framework',
+    'drf_parcel',
+]
+
+REST_FRAMEWORK = {
+    'EXCEPTION_HANDLER': 'drf_parcel.handlers.exception_handler',
+    'DEFAULT_PAGINATION_CLASS': 'drf_parcel.pagination.PageNumberPagination',
+    'DEFAULT_SCHEMA_CLASS': 'drf_parcel.schema.ParcelAutoSchema',
+}
+```
+
+هر خط مستقل است: handler به‌تنهایی فقط قالب خطا را می‌دهد و نه چیز دیگری، و
+پروژه بقیه را view به view به کار می‌گیرد.
+
+```python
+from drf_parcel.pagination import CursorPagination
+from drf_parcel.responses import EnvelopeMixin, success_response
+
+
+class ProductViewSet(EnvelopeMixin, ModelViewSet):
+    queryset = Product.objects.all()
+    serializer_class = ProductSerializer
+    page_size = 12
+    client_page_size = True          # the client may send ?page_size=
+    max_page_size = 48               # and never gets more
+    envelope_messages = {'create': _('The product was added.')}
+
+
+class NotificationViewSet(EnvelopeMixin, ModelViewSet):
+    pagination_class = CursorPagination
+    ordering = '-created_at'
+
+
+class TotalsView(EnvelopeMixin, APIView):
+    def get(self, request):
+        return success_response({'total': 12}, message=_('Totals.'))
+```
+
+`EnvelopeMixin` پاسخ view را یک بار، در `finalize_response`، در قالب
+می‌گذارد، پس هیچ اکشنی - `list`، `create`، یک `@action` سفارشی - لازم نیست
+یادش بماند. حذف به جای 204 بدون بدنه، 200 همراه با قالب جواب می‌دهد. فایل،
+استریم، ریدایرکت یا CSV دست نمی‌خورد، و viewی هم که `parcel_wrap = False`
+دارد.
+
+یک فروشگاه که همه‌ی بخش‌های آن را به کار می‌برد، برای اجرا کردن و خواندن، در
+[`example/`](example/README.fa.md) است.
+
+## خطاها
+
+```python
+from drf_parcel.exceptions import DomainError
+
+
+class ProvinceInUse(DomainError):
+    status_code = 409
+    default_code = 'province_in_use'
+    default_detail = _('This province has branches and cannot be deleted.')
+
+
+raise ProvinceInUse(data={'branches': 3})
+```
+
+`DomainError` همان `APIException` خود DRF است با `data` اضافه، پس خطاهای فعلی
+پروژه بدون تغییر در قالب جواب می‌دهند. handler این کارها را هم می‌کند:
+
+* در خطای اعتبارسنجی، اولین مشکل را در `message` و همه‌ی مشکل‌ها را در
+  `data.fields` می‌گوید، هر کدام با کدش و با یک مسیر تخت - `items.0.quantity`؛
+* خطاهای خود DRF و Django را با کد استاندارد جواب می‌دهد - `not_authenticated`،
+  `permission_denied`، `not_found`، `rate_limited` با `retry_after` و ... - و
+  هدرهایی را که DRF روی آن‌ها می‌گذارد حفظ می‌کند؛
+* هر خطای پیش‌بینی‌نشده را با یک 500 عمومی جواب می‌دهد که متنش هرگز از سرور
+  بیرون نمی‌رود: با traceback لاگ می‌شود و به `REPORTER` شما داده می‌شود. در
+  `DEBUG` خطا بالا می‌رود تا صفحه‌ی Django آن را نشان بدهد؛
+* نوشتن درخواست را پشت هر خطایی که جواب می‌دهد برمی‌گرداند.
+
+## صفحه‌بندی
+
+صفحه‌بندی شماره‌ای یا cursor، که هر view خودش انتخاب می‌کند. `pagination.type`
+می‌گوید کدام است، تا یک کامپوننت در کلاینت هر دو را بخواند. کلاینت فقط جایی
+تعداد هر صفحه را انتخاب می‌کند که view اجازه بدهد، و همیشه زیر سقف.
+
+## اسکیما
+
+با `ParcelAutoSchema` - یا `ParcelSchemaMixin` در `AutoSchema` خودتان - سند
+OpenAPI همان چیزی را می‌گوید که واقعاً منتقل می‌شود: هر پاسخ موفق داخل قالب،
+هر صفحه به‌عنوان قالب خودش، `page_size` فقط جایی که پذیرفته می‌شود، و قالب خطا
+به‌عنوان پاسخ `default` هر عملیات.
+
+## تنظیمات
+
+یک دیکشنری، `DRF_PARCEL`. کلیدی که کتابخانه نمی‌شناسد پروژه را هنگام start
+متوقف می‌کند، نه اینکه نادیده گرفته شود، و `manage.py check` مقداری را که کار
+نمی‌کند گزارش می‌دهد. همه‌ی کلیدها، همه‌ی شکل‌ها و همه‌ی کدهای خطا در
+[قرارداد](docs/contract.fa.md) آمده‌اند.
+
+## زبان‌ها
+
+هر جمله‌ای که کتابخانه می‌گوید به زبان درخواست است. فارسی همراه کتابخانه است؛
+پیام‌های خود DRF به زبان‌هایی است که DRF دارد.
+
+## پشتیبانی
+
+Python 3.11 تا 3.14؛ Django 5.2، 6.0 و 6.1؛ Django REST framework 3.16 و
+بالاتر؛ drf-spectacular 0.28 و بالاتر، برای اسکیما.
+
+## کار روی پروژه
+
+همه‌ی بررسی‌ها با [nox](https://nox.thea.codes) اجرا می‌شوند؛ همان sessionها
+هم روی سیستم خودتان و هم در CI.
+
+```bash
+uv tool install nox
+```
+
+```bash
+nox -s lint types tests
+```
+
+`tests` همه‌ی نسخه‌های پشتیبانی‌شده‌ی Python و Django را اجرا می‌کند؛ `oldest`
+قدیمی‌ترین نسخه‌ی همه‌ی وابستگی‌ها را؛ و `package` فایل wheel را می‌سازد و
+بررسی می‌کند چه چیزی در آن است. تست‌ها به‌طور پیش‌فرض روی SQLite اجرا می‌شوند،
+و روی PostgreSQL با `DRF_PARCEL_TEST_DATABASE=postgres` و متغیرهای استاندارد
+`PG*`.
+
+بعد از تغییر یک رشته‌ی علامت‌خورده، آن را در
+`src/drf_parcel/locale/fa/LC_MESSAGES/django.po` ترجمه و کامپایل کنید:
+
+```bash
+nox -s messages
+```
+
+## لایسنس
+
+BSD 3-Clause - فایل [`LICENSE`](LICENSE) را ببینید.

drf_parcel-0.1.0/README.md

@@ -0,0 +1,163 @@
+# drf-parcel
+
+One response shape for a Django REST framework API - success, page and error
+alike - and the generated schema saying exactly that shape.
+
+[فارسی](https://github.com/amirAI-dot/drf-parcel/blob/main/README.fa.md)
+
+```json
+{"success": true,  "status_code": 200, "message": "Done.",    "data": {"id": 7}}
+{"success": true,  "status_code": 200, "message": "Done.",    "data": [], "pagination": {"type": "page", "count": 45, "page": 2, "pages": 3, "page_size": 20, "has_next": true, "has_previous": true}}
+{"success": false, "status_code": 409, "message": "...",      "data": {"branches": 3}, "error_code": "province_in_use"}
+```
+
+A client reads one shape and never special-cases a payload: the answer is
+under `data`, a person reads `message`, and code branches on `error_code` -
+never on the message, which is translated.
+
+**[The documentation](https://amirai-dot.github.io/drf-parcel/)** - a
+quickstart, a tutorial, how-to guides, the reference - in English and
+Persian.
+
+## In a project
+
+```bash
+pip install 'drf-parcel[schema]'      # the schema extra brings drf-spectacular
+```
+
+```python
+INSTALLED_APPS = [
+    ...,
+    'rest_framework',
+    'drf_parcel',
+]
+
+REST_FRAMEWORK = {
+    'EXCEPTION_HANDLER': 'drf_parcel.handlers.exception_handler',
+    'DEFAULT_PAGINATION_CLASS': 'drf_parcel.pagination.PageNumberPagination',
+    'DEFAULT_SCHEMA_CLASS': 'drf_parcel.schema.ParcelAutoSchema',
+}
+```
+
+Each line is independent: the handler alone gives the error envelope and
+nothing else, and a project adopts the rest one view at a time.
+
+```python
+from drf_parcel.pagination import CursorPagination
+from drf_parcel.responses import EnvelopeMixin, success_response
+
+
+class ProductViewSet(EnvelopeMixin, ModelViewSet):
+    queryset = Product.objects.all()
+    serializer_class = ProductSerializer
+    page_size = 12
+    client_page_size = True          # the client may send ?page_size=
+    max_page_size = 48               # and never gets more
+    envelope_messages = {'create': _('The product was added.')}
+
+
+class NotificationViewSet(EnvelopeMixin, ModelViewSet):
+    pagination_class = CursorPagination
+    ordering = '-created_at'
+
+
+class TotalsView(EnvelopeMixin, APIView):
+    def get(self, request):
+        return success_response({'total': 12}, message=_('Totals.'))
+```
+
+`EnvelopeMixin` wraps what a view answers once, in `finalize_response`, so
+no action - `list`, `create`, a custom `@action` - has to remember. A delete
+answers 200 with the envelope rather than a 204 with nothing. A file, a
+stream, a redirect or a CSV is left alone, and so is a view with
+`parcel_wrap = False`.
+
+A shop that uses every part of it, to run and read, is in
+[`example/`](example/README.md).
+
+## Errors
+
+```python
+from drf_parcel.exceptions import DomainError
+
+
+class ProvinceInUse(DomainError):
+    status_code = 409
+    default_code = 'province_in_use'
+    default_detail = _('This province has branches and cannot be deleted.')
+
+
+raise ProvinceInUse(data={'branches': 3})
+```
+
+A `DomainError` is DRF's `APIException` with `data` added, so a project's
+existing errors answer in the envelope unchanged. The handler also:
+
+* says a validation error's first problem in `message` and every problem in
+  `data.fields`, each with its code at a flat path - `items.0.quantity`;
+* answers DRF's and Django's own failures with a standard code -
+  `not_authenticated`, `permission_denied`, `not_found`, `rate_limited` with
+  `retry_after` ... - and keeps the headers DRF puts on them;
+* answers anything unexpected with a generic 500 whose text never leaves the
+  server: it is logged with its traceback and handed to your `REPORTER`.
+  Under `DEBUG` it is raised, so Django's page shows it;
+* undoes the request's write behind every failure it answers.
+
+## Pagination
+
+Numbered pages or a cursor, chosen per view. `pagination.type` says which, so
+one component on a client reads either. A client chooses the page size only
+where a view allows it, and always under a ceiling.
+
+## The schema
+
+With `ParcelAutoSchema` - or `ParcelSchemaMixin` in your own `AutoSchema` -
+the OpenAPI document says what the wire carries: every success inside the
+envelope, each page as its own envelope, `page_size` only where it is
+accepted, and the error envelope as every operation's `default` answer.
+
+## Settings
+
+One dictionary, `DRF_PARCEL`. A key the library does not know stops the
+project at start-up rather than being ignored, and `manage.py check` reports
+a value that cannot work. Every key, every shape and every error code is in
+[the contract](docs/contract.md).
+
+## Languages
+
+Every sentence the library says is in the request's language. It ships
+Persian; DRF's own messages come in DRF's languages.
+
+## Supported
+
+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, for the schema.
+
+## Working on it
+
+Every check runs through [nox](https://nox.thea.codes), the same sessions
+locally and in CI.
+
+```bash
+uv tool install nox
+```
+
+```bash
+nox -s lint types tests
+```
+
+`tests` runs every supported Python and Django; `oldest` runs the oldest
+release of everything supported; `package` builds the wheel and checks what
+is in it. The suite runs on SQLite by default, and on PostgreSQL with
+`DRF_PARCEL_TEST_DATABASE=postgres` and the standard `PG*` variables.
+
+After changing a marked string, translate it in
+`src/drf_parcel/locale/fa/LC_MESSAGES/django.po` and compile it:
+
+```bash
+nox -s messages
+```
+
+## Licence
+
+BSD 3-Clause - see [`LICENSE`](LICENSE).